{"_id":"@cubiczan/agent-conductor","name":"@cubiczan/agent-conductor","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cubiczan/agent-conductor","version":"0.1.0","description":"Agent Conductor — AGENTS.md in, governed agent team out. MCP server that compiles AGENTS.md contracts and SKILL.md skills into orchestrated, consensus-gated agent operations.","mcpName":"io.github.icohangar-ops/agent-conductor","type":"module","main":"dist/index.js","bin":{"agent-conductor":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"node src/index.ts","test":"node --test test/*.test.ts","test:engine":"python3 engine/test_bridge.py","prepublishOnly":"npm run build"},"keywords":["mcp","agents-md","skills","agent-orchestration","consensus","governance","chp"],"author":{"name":"Shyam Desigan","email":"sam@cubiczan.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/icohangar-ops/agent-conductor.git"},"homepage":"https://github.com/icohangar-ops/agent-conductor#readme","bugs":{"url":"https://github.com/icohangar-ops/agent-conductor/issues"},"engines":{"node":">=23.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","zod":"^3.24.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"publishConfig":{"access":"public"},"gitHead":"6491689fd2ee43812ccf019de6efc7701c622292","types":"./dist/index.d.ts","_id":"@cubiczan/agent-conductor@0.1.0","_nodeVersion":"26.0.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-jE8BL0zWlRLRO4ed1oPc/H8IOL1S3rYqDGxIBACqDU9wSoHShQ5sfNlwEMBj5eF0vJbAG/1QmNuHhkrquA0Duw==","shasum":"9380809493b6e2033525bcef5f367b11251a928c","tarball":"https://registry.npmjs.org/@cubiczan/agent-conductor/-/agent-conductor-0.1.0.tgz","fileCount":32,"unpackedSize":74401,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEJBJfK7BCdfpRhxoYdbwlmbDUw9B4otiVAEJACQqqi2AiAnB8V3FpfAqJp1reDXpyraiBiuBah+TAVGRdls8uRFeg=="}]},"_npmUser":{"name":"cubiczan","email":"icohangar@gmail.com"},"directories":{},"maintainers":[{"name":"cubiczan","email":"icohangar@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-conductor_0.1.0_1787364450081_0.8011102993415564"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-22T02:07:29.683Z","0.1.0":"2026-08-22T02:07:30.333Z","modified":"2026-08-22T02:07:30.649Z"},"maintainers":[{"name":"cubiczan","email":"icohangar@gmail.com"}],"description":"Agent Conductor — AGENTS.md in, governed agent team out. MCP server that compiles AGENTS.md contracts and SKILL.md skills into orchestrated, consensus-gated agent operations.","homepage":"https://github.com/icohangar-ops/agent-conductor#readme","keywords":["mcp","agents-md","skills","agent-orchestration","consensus","governance","chp"],"repository":{"type":"git","url":"git+https://github.com/icohangar-ops/agent-conductor.git"},"author":{"name":"Shyam Desigan","email":"sam@cubiczan.com"},"bugs":{"url":"https://github.com/icohangar-ops/agent-conductor/issues"},"license":"MIT","readme":"# Agent Conductor\n\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.icohangar--ops%2Fagent--conductor-00C4B4)](https://registry.modelcontextprotocol.io)\n[![npm](https://img.shields.io/npm/v/@cubiczan/agent-conductor)](https://www.npmjs.com/package/@cubiczan/agent-conductor)\n[![Conformance](https://img.shields.io/badge/CHP_Profile_A-via_PyPI-brightgreen)](https://pypi.org/project/consensus-hardening-protocol/)\n\n> **Cubiczan stack** — [Profile](https://github.com/Cubiczan) · [CHP](https://github.com/Cubiczan/consensus-hardening-protocol) · **You are here:** `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:** [Cubiczan/agent-conductor](https://github.com/Cubiczan/agent-conductor) · [codeberg.org/cubiczan/agent-conductor](https://codeberg.org/cubiczan/agent-conductor) · [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│   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│   bridge.py → PyPI consensus-hardening-protocol│\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://github.com/icohangar-ops/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\n```bash\nnpx -y @cubiczan/agent-conductor\n# decision_* tools also need:\n#   pip install -r engine/requirements.txt   # after cloning, or use the published package's engine/\n```\n\n\n\nRequirements: **Node 23+** (runs TypeScript natively) and **Python 3.10+**\nwith the published CHP package installed.\n\n```bash\ngit clone https://github.com/icohangar-ops/agent-conductor.git\ncd agent-conductor\nnpm install\npip install -r engine/requirements.txt\nnpm test            # TypeScript tests (parser, skills, 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 or a project directory; defaults to the current working directory.\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.\n\n### `skills_list`\n\nDiscover SKILL.md skills visible from a project root. Metadata only.\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):\n\n| Priority | Path | Scope |\n|----------|------|-------|\n| 1 | `<project>/.conductor/skills/*/SKILL.md` | project |\n| 2 | `<project>/.claude/skills/*/SKILL.md` | project |\n| 3 | `<project>/.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 example —\n[examples/pipeline-pulse](examples/pipeline-pulse/AGENTS.md) — is a complete\nreal-world AGENTS.md plus a project-scoped skill, and is what the test suite\ncompiles.\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\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 router → PyPI `chp`\n│   ├── requirements.txt       # consensus-hardening-protocol pin\n│   ├── NOTICE.md              # attribution for the published engine\n│   └── test_bridge.py         # protocol tests\n├── examples/pipeline-pulse/   # real AGENTS.md fixture + example skill\n└── test/                      # node:test suites (run the .ts directly)\n```\n\n## Development\n\n```bash\npip install -r engine/requirements.txt\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 Node runtime dependencies** — only `@modelcontextprotocol/sdk`\n   and `zod`; markdown/frontmatter stay hand-rolled. CHP is a PyPI dep.\n3. **Erasable TypeScript only** — source must run under Node's type\n   stripping (no enums, no parameter properties).\n4. **CHP via PyPI** — install `consensus-hardening-protocol`; do not\n   re-vendor under `engine/`. Protocol fixes belong upstream.\n5. **Python 3.10+** — required by the published package.\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 | Expose `decision_lock` + mesh session tools over MCP (multi-agent deliberation on top of published CHP) |\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 (PyPI) | [consensus-hardening-protocol](https://github.com/icohangar-ops/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/NOTICE.md](engine/NOTICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md)\nfor the two-language design.\n\n---\n\n## Cubiczan stack\n\n| Governance | [consensus-hardening-protocol](https://github.com/Cubiczan/consensus-hardening-protocol) · **agent-conductor** · [compliance-as-code-agent](https://github.com/Cubiczan/compliance-as-code-agent) · [cleanmandate](https://github.com/Cubiczan/cleanmandate) |\n| Platform | [cubiczan-mcp-server](https://github.com/Cubiczan/cubiczan-mcp-server) · [operational-intelligence](https://github.com/Cubiczan/operational-intelligence) · [software-factory](https://github.com/Cubiczan/software-factory) |\n\nConductor compiles `AGENTS.md` + `SKILL.md` into MCP tools and routes high-stakes decisions through CHP — the same lock model [Metabocommand](https://github.com/Cubiczan/Metabocommand) uses for finance approvals.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Vendored components retain their original MIT\nlicenses.\n","readmeFilename":"README.md","_rev":"1-bb11925b857b7c39662e3fcd215fc707"}