Agent Conductor

Стек Cubiczan — Профиль · CHP · Вы здесь: agent-conductor

AGENTS.md на входе — управляемая команда агентов на выходе.

Agent Conductor — это MCP сервер, который превращает две конвенции, на которых сошлась экосистема кодинг-агентов, — руководства AGENTS.md и навыки SKILL.md — из пассивной документации в активный слой оркестрации, с усиленным консенсусом движком принятия решений, ограничивающим изменения с высокими ставками.

• Зеркала: Cubiczan/agent-conductor · codeberg.org/cubiczan/agent-conductor · icohangar-ops/agent-conductor

• Лицензия: MIT

• Статус: v0.1 — рабочий каркас; см. Дорожную карту

Проблема

Каждый серьёзный инструмент для агентов — Claude Code, Cursor, Copilot, Codex, Gemini CLI — теперь читает AGENTS.md в корне репозитория и каталог файлов SKILL.md. Но обе конвенции — это проза, работающая на честном слове:

• Ничто не компилирует контракт. Непреложные правила, границы слоёв и чек-листы верификации живут в виде markdown, который агент может усвоить, а может и нет.

• Ничто не ограничивает решение. Агент, который собирается переписать вашу скоринговую модель, действует с той же уверенностью, что и агент, переименовывающий переменную.

• Ничто не проверяет, что чек-лист был выполнен. «Запусти npm test перед сдачей» — это предложение, а не шлюз.

Conductor делает конвенции исполняемыми — не требуя от какого-либо агентского инструмента меняться. Он поставляется как стандартный MCP-сервер, поэтому всё, что говорит на MCP, получает компиляцию контракта, обнаружение навыков и ограничение решений бесплатно.

Related MCP server: @event4u/agent-config

Как это работает

MCP client (Claude Code / Cursor / Copilot / ...)
        │  stdio (JSON-RPC, MCP)
        ▼
┌────────────────────────────────────────────────┐
│ TypeScript front end (src/)                    │
│   contract/parser.ts   AGENTS.md → contract    │
│   skills/loader.ts     SKILL.md discovery      │
│   server.ts            7 MCP tools             │
└────────────────┬───────────────────────────────┘
                 │  newline-delimited JSON, child stdio
                 ▼
┌────────────────────────────────────────────────┐
│ Python decision engine (engine/)               │
│   bridge.py → PyPI consensus-hardening-protocol│
│   R0 gates · foundation attacks · lifecycle    │
└────────────────────────────────────────────────┘

Три группы возможностей:

1. Контракт — компилирует AGENTS.md в структурированную миссию, непреложные правила, границы «можно/нельзя» по слоям, шлюзы верификации, рекомендации по навыкам и список того, что вне области действия.

2. Навыки — обнаруживает навыки SKILL.md в проектных и личных областях с прогрессивным раскрытием: метаданные стоят ~100 токенов, тела загружаются только по требованию.

3. Решение — ограничивает работу через Consensus Hardening Protocol: дешёвый шлюз R0 до начала работы и состязательный проход по атаке на фундамент перед блокировкой изменения с высокими ставками.

Быстрый старт

npx -y @cubiczan/agent-conductor
# decision_* tools also need:
#   pip install -r engine/requirements.txt   # after cloning, or use the published package's engine/

Требования: Node 23+ (нативно запускает TypeScript) и Python 3.10+ с установленным опубликованным пакетом CHP.

git clone https://github.com/icohangar-ops/agent-conductor.git
cd agent-conductor
npm install
pip install -r engine/requirements.txt
npm test            # TypeScript tests (parser, skills, live engine bridge)
npm run test:engine # Python bridge protocol tests
npm run build

Зарегистрируйте в Claude Code:

claude mcp add agent-conductor -- node /path/to/agent-conductor/dist/index.js

Или в JSON-конфиге любого MCP-клиента:

{
  "mcpServers": {
    "agent-conductor": {
      "command": "node",
      "args": ["/path/to/agent-conductor/dist/index.js"]
    }
  }
}

Установите CONDUCTOR_PYTHON, если ваш Python 3 находится не в python3.

Затем, из любого проекта, в котором есть AGENTS.md:

«Загрузи контракт агента этого проекта, перечисли его шлюзы верификации и запусти проход decision_adversary по изменению, которое я собираюсь внести.»

Справочник по инструментам

contract_load

Компилирует AGENTS.md (или CLAUDE.md) в структурированный контракт. Принимает путь к файлу или каталог проекта; по умолчанию — текущий рабочий каталог.

// input
{ "path": "examples/pipeline-pulse" }

// output (abridged — real output from the bundled example)
{
  "source": "examples/pipeline-pulse/AGENTS.md",
  "title": "AGENTS.md — Pipeline Pulse CRM",
  "mission": "Pipeline Pulse CRM is a lightweight, local-first pipeline review dashboard...",
  "rules": [
    "Deterministic logic — same inputs → same scores, labels, and summaries...",
    "Logic in crm.js — keep main.js thin (fetch, render, events).",
    "... (6 total)"
  ],
  "layers": [
    { "layer": "src/crm.js", "role": "Domain logic",
      "do": "Deterministic scoring, filtering, summaries", "dont": "DOM manipulation" }
  ],
  "gates": [
    { "name": "Code change checklist", "commands": ["npm test"], "notes": "" },
    { "name": "Before completion", "commands": [], "notes": "npm test — all green...\n..." }
  ],
  "skills": [
    { "task": "CRM scoring / forecast changes", "skill": "obra/test-driven-development",
      "url": "https://github.com/obra/superpowers/...", "why": "Tests-first changes to deterministic logic" }
  ],
  "outOfScope": ["External CRM integrations (Salesforce, HubSpot, etc.)", "..."],
  "sectionCount": 28
}

Парсер без потерь: разделы, которые он не распознаёт, сохраняются дословно, так что ничего в нетрадиционном AGENTS.md не теряется.

contract_verification

Возвращает только шлюзы верификации — именованные чек-листы и shell-команды, которые должны пройти до сдачи работы. Сопоставьте их с рабочим процессом вашего агента: выполните команды, подтвердите успех, затем объявите о завершении.

skills_list

Обнаруживает навыки SKILL.md, видимые из корня проекта. Только метаданные.

// input
{ "projectRoot": "examples/pipeline-pulse" }

// output
{
  "skills": [
    {
      "name": "pipeline-scoring",
      "description": "Explain and modify scoreDealRisk weights in src/crm.js with matching test updates...",
      "version": "0.1.0",
      "scope": "project"
    }
  ]
}

Порядок поиска (побеждает первое совпадение по имени навыка):

skill_load

Загружает полное тело SKILL.md для одного именованного навыка — вторая половина прогрессивного раскрытия по требованию. Вызывайте его только тогда, когда задача соответствует описанию навыка.

decision_gate

Шлюз R0 Consensus Hardening Protocol: самая дешёвая и наиболее эффективная проверка, выполняемая до начала работы.

// input
{ "solvable": true, "scoped": false, "valid": true, "worth_it": true }

// output
{ "verdict": "HALT", "results": { "Solvable": "PASS", "Scoped": "FATAL", "Valid": "PASS", "Worth_it": "PASS" } }

Любой ответ FATAL останавливает: остановитесь и переформулируйте, прежде чем сжигать токены на проблему, которая не определена, не понята или не стоит решения.

decision_adversary

Одноразовый adversarial проход для изменений с высокими ставками: CHP атакует фундаменты утверждения, оценивает их от 0 до 100 и возвращает выводы «адвоката дьявола» плюс статус сессии.

// input
{
  "claim": "Change scoreDealRisk stale-activity weight from 20 to 30",
  "context": "Tests updated; label distribution checked against fixture"
}

// output
{
  "status": "EXPLORING",          // or HALT / REFRAME_REQUIRED
  "foundation_score": 77,
  "findings": [
    "Treat every financial number as unverified until tied to source data.",
    "Require explicit flip criteria for any provisional recommendation."
  ],
  "verification_failures": ["PENDING third-party validation"],
  "report": "## TriangulationRunner Adversary Pass\n..."
}

Статусы соответствуют жизненному циклу решений CHP (EXPLORING → PROVISIONAL_LOCK → LOCKED, с выходами HALT и REFRAME_REQUIRED): EXPLORING означает, что утверждение пережило атаку и работа может продолжаться к блокировке; HALT/REFRAME_REQUIRED означают, что фундаменты не прошли.

engine_status

Проверка работоспособности подпроцесса Python-движка. Возвращает { ok, engine: "chp", version }.

Что распознаёт парсер

contract_load основан на конвенциях, а не на схеме. Он извлекает паттерны, которые реально используются в файлах AGENTS.md:

Заголовки внутри блоков кода игнорируются; таблицы допускают выделение в заголовках; markdown-ссылки и выделение удаляются из извлечённого текста.

Написание навыков

Навык — это каталог, содержащий SKILL.md с YAML-frontmatter:

---
name: pipeline-scoring
description: Explain and modify scoreDealRisk weights in src/crm.js with matching test updates. Use when changing deal risk scoring, risk labels, or forecast thresholds.
version: 0.1.0
tools: [Read, Edit, Bash]
---

# Pipeline Scoring

Step-by-step instructions the agent follows when the task matches...

Планка качества (унаследована от стандартов awesome-agent-skills): описание от третьего лица с сопоставимыми ключевыми словами, метаданные около 100 токенов, тело менее 500 строк, без машинно-специфичных абсолютных путей, объявляйте только те инструменты, которые нужны навыку.

Встроенный пример — examples/pipeline-pulse — это полный реальный AGENTS.md плюс навык в области проекта, и именно его компилирует тестовый набор.

Структура проекта

.
├── AGENTS.md                  # This repo's own contract (compiles with itself)
├── ARCHITECTURE.md            # Design decisions and component detail
├── src/
│   ├── index.ts               # stdio entrypoint
│   ├── server.ts              # MCP server: 7 tools
│   ├── contract/              # AGENTS.md → AgentContract compiler
│   ├── skills/                # SKILL.md loader + registry
│   ├── engine/chpBridge.ts    # Python engine client
│   └── utils/logger.ts        # stderr-only logging (stdout is the transport)
├── engine/
│   ├── bridge.py              # JSON-over-stdio router → PyPI `chp`
│   ├── requirements.txt       # consensus-hardening-protocol pin
│   ├── NOTICE.md              # attribution for the published engine
│   └── test_bridge.py         # protocol tests
├── examples/pipeline-pulse/   # real AGENTS.md fixture + example skill
└── test/                      # node:test suites (run the .ts directly)

Разработка

pip install -r engine/requirements.txt
npm test            # TypeScript tests — includes a live engine round-trip
npm run test:engine # Python-side protocol tests
npx tsc --noEmit    # type check
npm run build       # emit dist/
npm run dev         # run the server from source (Node type stripping)

Домашние правила (полный набор — в собственном AGENTS.md этого репозитория):

1. stdout священен — транспорт MCP владеет им; всё логирование идёт в stderr на обеих сторонах моста.

2. Ноль новых зависимостей Node runtime — только @modelcontextprotocol/sdk и zod; markdown/frontmatter остаются самописными. CHP — зависимость PyPI.

3. Только стираемый TypeScript — исходный код должен работать под стиранием типов Node (без перечислений, без свойств параметров).

4. CHP через PyPI — установите consensus-hardening-protocol; не пере-вендорируйте его в engine/. Исправления протокола принадлежат апстриму.

5. Python 3.10+ — требуется опубликованным пакетом.

Дорожная карта

Происхождение

Conductor намеренно переиспользует проверенные компоненты, а не переписывает их:

См. engine/NOTICE.md и ARCHITECTURE.md для описания двухъязычной архитектуры.

Стек Cubiczan

| Управление | consensus-hardening-protocol · agent-conductor · compliance-as-code-agent · cleanmandate | | Платформа | cubiczan-mcp-server · operational-intelligence · software-factory |

Conductor компилирует AGENTS.md + SKILL.md в MCP-инструменты и направляет решения с высокими ставками через CHP — ту же модель блокировки, которую Metabocommand использует для финансовых одобрений.

Лицензия

MIT — см. LICENSE. Вендорные компоненты сохраняют свои исходные лицензии MIT.