{
  "markdown": "# Agent Conductor\n\n**AGENTS.md in, governed agent team out.**\n\nAgent Conductor is an [MCP](https://modelcontextprotocol.io) server that turns\nthe two conventions the coding-agent ecosystem has converged on —\n[`AGENTS.md`](https://agents.md) operating manuals and `SKILL.md` skills — from\npassive documentation into an active orchestration layer, with a\nconsensus-hardened decision engine gating high-stakes changes.\n\n- **Mirrors:** [codeberg.org/cubiczan/agent-conductor](https://codeberg.org/cubiczan/agent-conductor) · [github.com/icohangar-ops/agent-conductor](https://github.com/icohangar-ops/agent-conductor)\n- **License:** MIT\n- **Status:** v0.1 — working scaffold; see [Roadmap](#roadmap)\n\n---\n\n## The problem\n\nEvery serious agent tool — Claude Code, Cursor, Copilot, Codex, Gemini CLI —\nnow reads an `AGENTS.md` at the repo root and a catalog of `SKILL.md` files.\nBut both conventions are honor-system prose:\n\n- Nothing **compiles** the contract. The non-negotiable rules, layer\n  boundaries, and verification checklists live as markdown the agent may or\n  may not internalize.\n- Nothing **gates** the decision. An agent that's about to rewrite your\n  scoring model proceeds with the same confidence as one renaming a variable.\n- Nothing **verifies** the checklist ran. \"Run `npm test` before handing off\"\n  is a suggestion, not a gate.\n\nConductor makes the conventions executable — without asking any agent tool to\nchange. It ships as a standard MCP server, so anything that speaks MCP gets\ncontract compilation, skill discovery, and decision gating for free.\n\n## How it works\n\n```text\nMCP client (Claude Code / Cursor / Copilot / ...)\n        │  stdio (JSON-RPC, MCP)\n        ▼\n┌────────────────────────────────────────────────┐\n│ TypeScript front end (src/)                    │\n│   contract/parser.ts   AGENTS.md → contract    │\n│   contract/workspace.ts Multi-root merge       │\n│   skills/loader.ts     SKILL.md discovery      │\n│   server.ts            7 MCP tools             │\n└────────────────┬───────────────────────────────┘\n                 │  newline-delimited JSON, child stdio\n                 ▼\n┌────────────────────────────────────────────────┐\n│ Python decision engine (engine/)               │\n│   vendored Consensus Hardening Protocol core   │\n│   R0 gates · foundation attacks · lifecycle    │\n└────────────────────────────────────────────────┘\n```\n\nThree capability groups:\n\n1. **Contract** — compile an `AGENTS.md` into structured mission,\n   non-negotiable rules, layer do/don't boundaries, verification gates,\n   skill recommendations, and an out-of-scope list.\n2. **Skills** — discover `SKILL.md` skills across project and personal\n   scopes with progressive disclosure: metadata costs ~100 tokens, bodies\n   load only on demand.\n3. **Decision** — gate work through the\n   [Consensus Hardening Protocol](https://codeberg.org/cubiczan/consensus-hardening-protocol):\n   a cheap R0 sanity gate before work starts, and an adversarial\n   foundation-attack pass before a high-stakes change locks.\n\n## Quick start\n\nRequirements: **Node 23+** (runs TypeScript natively) and **Python 3.9+**\n(stdlib only — the engine needs no pip installs).\n\n```bash\ngit clone https://codeberg.org/cubiczan/agent-conductor.git\ncd agent-conductor\nnpm install\nnpm test            # TypeScript tests (parser, skills, multi-root, live engine bridge)\nnpm run test:engine # Python bridge protocol tests\nnpm run build\n```\n\nRegister with Claude Code:\n\n```bash\nclaude mcp add agent-conductor -- node /path/to/agent-conductor/dist/index.js\n```\n\nOr in any MCP client's JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-conductor\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/agent-conductor/dist/index.js\"]\n    }\n  }\n}\n```\n\nSet `CONDUCTOR_PYTHON` if your Python 3 lives somewhere other than `python3`.\n\nThen, from any project that has an `AGENTS.md`:\n\n> \"Load this project's agent contract, list its verification gates, and run a\n> decision_adversary pass on the change I'm about to make.\"\n\n## Tool reference\n\n### `contract_load`\n\nCompile an AGENTS.md (or CLAUDE.md) into a structured contract. Accepts a\nfile path, a project directory, an explicit `roots` list, or a `rootsFile`\nmap; defaults to the current working directory. Multi-root workspaces emit\n**one** contract whose layer table and verification commands are merged.\nSection bodies stay off this tool so callers remain inside progressive-\ndisclosure budgets (metadata + structured fields only).\n\n```jsonc\n// input\n{ \"path\": \"examples/pipeline-pulse\" }\n\n// output (abridged — real output from the bundled example)\n{\n  \"source\": \"examples/pipeline-pulse/AGENTS.md\",\n  \"title\": \"AGENTS.md — Pipeline Pulse CRM\",\n  \"mission\": \"Pipeline Pulse CRM is a lightweight, local-first pipeline review dashboard...\",\n  \"rules\": [\n    \"Deterministic logic — same inputs → same scores, labels, and summaries...\",\n    \"Logic in crm.js — keep main.js thin (fetch, render, events).\",\n    \"... (6 total)\"\n  ],\n  \"layers\": [\n    { \"layer\": \"src/crm.js\", \"role\": \"Domain logic\",\n      \"do\": \"Deterministic scoring, filtering, summaries\", \"dont\": \"DOM manipulation\" }\n  ],\n  \"gates\": [\n    { \"name\": \"Code change checklist\", \"commands\": [\"npm test\"], \"notes\": \"\" },\n    { \"name\": \"Before completion\", \"commands\": [], \"notes\": \"npm test — all green...\\n...\" }\n  ],\n  \"skills\": [\n    { \"task\": \"CRM scoring / forecast changes\", \"skill\": \"obra/test-driven-development\",\n      \"url\": \"https://github.com/obra/superpowers/...\", \"why\": \"Tests-first changes to deterministic logic\" }\n  ],\n  \"outOfScope\": [\"External CRM integrations (Salesforce, HubSpot, etc.)\", \"...\"],\n  \"sectionCount\": 28\n}\n```\n\nThe parser is **lossless**: sections it doesn't recognize are preserved\nverbatim, so nothing in an unconventional AGENTS.md is dropped.\n\n### `contract_verification`\n\nReturns only the verification gates — the named checklists and shell commands\nthat must pass before work is handed off. Pair it with your agent's workflow:\nrun the commands, confirm success, then declare done. Accepts the same\nsingle-root or multi-root inputs as `contract_load`.\n\n### `skills_list`\n\nDiscover SKILL.md skills visible from a project root or a declared\nmulti-root workspace. Metadata only. Extra source roots outside a module\ndirectory are included when they appear in the roots list or map.\n\n```jsonc\n// input\n{ \"projectRoot\": \"examples/pipeline-pulse\" }\n\n// output\n{\n  \"skills\": [\n    {\n      \"name\": \"pipeline-scoring\",\n      \"description\": \"Explain and modify scoreDealRisk weights in src/crm.js with matching test updates...\",\n      \"version\": \"0.1.0\",\n      \"scope\": \"project\"\n    }\n  ]\n}\n```\n\nSearch order (first hit per skill name wins). In a multi-root workspace the\nproject rows run for each declared root, then personal scopes run once:\n\n| Priority | Path | Scope |\n|----------|------|-------|\n| 1 | `<root>/.conductor/skills/*/SKILL.md` | project |\n| 2 | `<root>/.claude/skills/*/SKILL.md` | project |\n| 3 | `<root>/.cursor/skills/*/SKILL.md` | project |\n| 4 | `~/.claude/skills/*/SKILL.md` | personal |\n| 5 | `~/.cursor/skills/*/SKILL.md` | personal |\n\n### `skill_load`\n\nLoad the full SKILL.md body for one named skill — the on-demand half of\nprogressive disclosure. Call it only when the task matches the skill's\ndescription.\n\n### `decision_gate`\n\nThe Consensus Hardening Protocol **R0 gate**: the cheapest, highest-leverage\ncheck, run *before* doing the work.\n\n```jsonc\n// input\n{ \"solvable\": true, \"scoped\": false, \"valid\": true, \"worth_it\": true }\n\n// output\n{ \"verdict\": \"HALT\", \"results\": { \"Solvable\": \"PASS\", \"Scoped\": \"FATAL\", \"Valid\": \"PASS\", \"Worth_it\": \"PASS\" } }\n```\n\nAny `FATAL` answer halts: stop and reframe before burning tokens on a\nproblem that isn't scoped, isn't understood, or isn't worth solving.\n\n### `decision_adversary`\n\nA one-shot adversarial pass for high-stakes changes: CHP attacks the claim's\nfoundations, scores them 0–100, and returns devil's-advocate findings plus a\nsession status.\n\n```jsonc\n// input\n{\n  \"claim\": \"Change scoreDealRisk stale-activity weight from 20 to 30\",\n  \"context\": \"Tests updated; label distribution checked against fixture\"\n}\n\n// output\n{\n  \"status\": \"EXPLORING\",          // or HALT / REFRAME_REQUIRED\n  \"foundation_score\": 77,\n  \"findings\": [\n    \"Treat every financial number as unverified until tied to source data.\",\n    \"Require explicit flip criteria for any provisional recommendation.\"\n  ],\n  \"verification_failures\": [\"PENDING third-party validation\"],\n  \"report\": \"## TriangulationRunner Adversary Pass\\n...\"\n}\n```\n\nStatuses map to the CHP decision lifecycle\n(`EXPLORING → PROVISIONAL_LOCK → LOCKED`, with `HALT` and\n`REFRAME_REQUIRED` exits): `EXPLORING` means the claim survived the attack\nand work may proceed toward a lock; `HALT`/`REFRAME_REQUIRED` mean the\nfoundations failed.\n\n### `engine_status`\n\nHealth-check the Python engine subprocess. Returns\n`{ ok, engine: \"chp\", version }`.\n\n## What the parser recognizes\n\n`contract_load` is convention-based, not schema-based. It extracts the\npatterns AGENTS.md files in the wild actually use:\n\n| Contract field | Source convention |\n|----------------|-------------------|\n| `mission` | First `Mission` / `Purpose` / `Overview` section |\n| `rules` | List items under `Non-negotiables` > `Engineering rules` > generic `rules` (priority-ordered so a generic \"Product rules\" section never shadows explicit non-negotiables) |\n| `layers` | First table with a `Layer` column under an architecture-like heading |\n| `gates` | Shell code blocks + list items under checklist / verification / before-completion headings |\n| `skills` | Tables with `Task` / `Skill` / `Why` columns; links resolved to text + URL |\n| `outOfScope` | List under an out-of-scope / non-goals heading |\n| `sections` | Everything, verbatim — the lossless fallback |\n\nHeadings inside code fences are ignored; tables tolerate emphasis in headers;\nmarkdown links and emphasis are stripped from extracted text.\n\n## Writing skills\n\nA skill is a directory containing `SKILL.md` with YAML frontmatter:\n\n```markdown\n---\nname: pipeline-scoring\ndescription: Explain and modify scoreDealRisk weights in src/crm.js with matching test updates. Use when changing deal risk scoring, risk labels, or forecast thresholds.\nversion: 0.1.0\ntools: [Read, Edit, Bash]\n---\n\n# Pipeline Scoring\n\nStep-by-step instructions the agent follows when the task matches...\n```\n\nQuality bar (inherited from the\n[awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)\nstandards): third-person description with matchable keywords, metadata around\n100 tokens, body under 500 lines, no machine-specific absolute paths, declare\nonly the tools the skill needs.\n\nThe bundled examples:\n\n- [examples/pipeline-pulse](examples/pipeline-pulse/AGENTS.md) — a complete\n  real-world AGENTS.md plus a project-scoped skill (single-root compile).\n- [examples/multimodule](examples/multimodule/AGENTS.md) — a Gradle-style\n  extra source root: skills live under `shared/`, outside `modules/billing`.\n\n## Monorepo cookbook\n\nNaive loaders walk only the directory they were pointed at. That breaks the\nsame way a Gradle module breaks when a `sourceSet` points outside the module\n(`srcDirs = ['src/main/java', '../shared/src']`): the extra tree is real\nwork, but it is not inside the module dir.\n\nDeclare every extra root. Conductor fails closed if one is missing — it\nwill not invent a root or silently skip it.\n\n### 1. Write a roots map\n\nCanonical locations (first hit wins):\n\n| File | When to use |\n|------|-------------|\n| `.conductor/roots.json` | Next to `.conductor/skills` |\n| `conductor.roots.json` | Repo-root convenience |\n| `.conductor/roots` / `conductor.roots` | Line-oriented alternative |\n\nJSON object (ids optional):\n\n```json\n{\n  \"roots\": [\n    { \"id\": \"workspace\", \"path\": \".\" },\n    { \"id\": \"billing\", \"path\": \"modules/billing\" },\n    { \"id\": \"shared\", \"path\": \"shared\" }\n  ]\n}\n```\n\nJSON array of paths:\n\n```json\n[\".\", \"modules/billing\", \"shared\"]\n```\n\nLine-oriented map (`#` comments allowed):\n\n```text\nworkspace: .\nbilling: modules/billing\nshared\n```\n\nRelative paths resolve against the map file's directory.\n\n### 2. Keep skills on the extra root\n\n```text\nexamples/multimodule/\n├── conductor.roots.json\n├── AGENTS.md                    # workspace layers + `npm test`\n├── modules/billing/AGENTS.md    # module layers + `npm -C modules/billing test`\n└── shared/.conductor/skills/shared-ledger/SKILL.md\n```\n\n`modules/billing` alone cannot see `shared-ledger`. After the map is\ndeclared, `skills_list` and `skill_load` walk every root, then personal\nscopes, with first-hit-wins shadowing.\n\n### 3. Call the tools\n\n```jsonc\n// Auto-detect a roots map under a directory\n{ \"path\": \"examples/multimodule\" }\n\n// Explicit list (relative paths resolve against `path` or cwd)\n{ \"path\": \"examples/multimodule\", \"roots\": [\".\", \"modules/billing\", \"shared\"] }\n\n// Explicit map file\n{ \"rootsFile\": \"examples/multimodule/conductor.roots.json\" }\n```\n\n`contract_load` still returns a summary without section bodies;\n`contract_verification` still returns gates only; `skills_list` still\nreturns frontmatter metadata. Single-root projects without a map file —\nincluding `examples/pipeline-pulse` — keep the previous compile path.\n\n## Project structure\n\n```text\n.\n├── AGENTS.md                  # This repo's own contract (compiles with itself)\n├── ARCHITECTURE.md            # Design decisions and component detail\n├── src/\n│   ├── index.ts               # stdio entrypoint\n│   ├── server.ts              # MCP server: 7 tools\n│   ├── contract/              # AGENTS.md → AgentContract compiler (incl. multi-root)\n│   ├── skills/                # SKILL.md loader + registry\n│   ├── engine/chpBridge.ts    # Python engine client\n│   └── utils/logger.ts        # stderr-only logging (stdout is the transport)\n├── engine/\n│   ├── bridge.py              # JSON-over-stdio request router\n│   ├── test_bridge.py         # protocol tests\n│   └── vendor/cme/            # vendored CHP core (MIT, byte-identical; see NOTICE.md)\n├── examples/pipeline-pulse/   # real AGENTS.md fixture + example skill\n├── examples/multimodule/      # extra source root (skills outside the module)\n└── test/                      # node:test suites (run the .ts directly)\n```\n\n## Development\n\n```bash\nnpm test            # TypeScript tests — includes a live engine round-trip\nnpm run test:engine # Python-side protocol tests\nnpx tsc --noEmit    # type check\nnpm run build       # emit dist/\nnpm run dev         # run the server from source (Node type stripping)\n```\n\nHouse rules (the full set is in this repo's own [AGENTS.md](AGENTS.md)):\n\n1. **stdout is sacred** — the MCP transport owns it; all logging goes to\n   stderr on both sides of the bridge.\n2. **Zero new runtime dependencies** — only `@modelcontextprotocol/sdk` and\n   `zod`; markdown and frontmatter parsing stay hand-rolled and tested.\n3. **Erasable TypeScript only** — source must run under Node's type\n   stripping (no enums, no parameter properties).\n4. **Vendor discipline** — `engine/vendor/cme/` stays byte-identical to\n   upstream except the documented `__init__.py` patch; engine behavior\n   changes belong in `bridge.py`.\n\n## Roadmap\n\n| Version | Theme | Scope |\n|---------|-------|-------|\n| **v0.2** | Enforcement | Execute `contract_verification` gates as real subprocesses and return pass/fail evidence — turning \"reads the contract\" into \"enforces the contract\" |\n| **v0.3** | Orchestration | Map contract layers onto CHP `MeshAgent` capabilities (`produces`/`consumes`) and expose full multi-agent deliberation sessions over MCP |\n| **v0.4** | Registry | Install vetted skills from remote catalogs (awesome-agent-skills format) with source-review prompts |\n\n## Provenance\n\nConductor deliberately reuses proven components rather than rewriting them:\n\n| Component | Source | License |\n|-----------|--------|---------|\n| Decision engine (`engine/vendor/cme/`) | [consensus-hardening-protocol](https://codeberg.org/cubiczan/consensus-hardening-protocol) | MIT |\n| MCP server + registry shape | [onchainmind](https://codeberg.org/cubiczan/onchainmind) | MIT |\n| Skill quality standards | [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) | — |\n| Example fixture | Pipeline Pulse CRM operating manual | fixture |\n\nSee [engine/vendor/NOTICE.md](engine/vendor/NOTICE.md) for vendoring details\nand [ARCHITECTURE.md](ARCHITECTURE.md) for the reasoning behind the\ntwo-language design.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Vendored components retain their original MIT\nlicenses.\n",
  "bytes": 16531,
  "sha": "037467dd669f63d6c767f7724ea63b49b91299c327355f16270293c25372c543",
  "repo_slug": "icohangar-ops/agent-conductor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_icohangar_ops_agent_conductor_7f1c0903/readme"
}