agent-conductor

# Agent Conductor

[![icohangar-ops/agent-conductor MCP server](https://glama.ai/mcp/servers/icohangar-ops/agent-conductor/badges/score.svg)](https://glama.ai/mcp/servers/icohangar-ops/agent-conductor)


[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.icohangar--ops%2Fagent--conductor-00C4B4)](https://registry.modelcontextprotocol.io)
[![npm](https://img.shields.io/npm/v/@cubiczan/agent-conductor)](https://www.npmjs.com/package/@cubiczan/agent-conductor)
[![Conformance](https://img.shields.io/badge/CHP_Profile_A-via_PyPI-brightgreen)](https://pypi.org/project/consensus-hardening-protocol/)

> **Cubiczan stack** — [Profile](https://github.com/Cubiczan) · [CHP](https://github.com/Cubiczan/consensus-hardening-protocol) · **You are here:** `agent-conductor`

**AGENTS.md in, governed agent team out.**

Agent Conductor is an [MCP](https://modelcontextprotocol.io) server that turns
the two conventions the coding-agent ecosystem has converged on —
[`AGENTS.md`](https://agents.md) operating manuals and `SKILL.md` skills — from
passive documentation into an active orchestration layer, with a
consensus-hardened decision engine gating high-stakes changes.

- **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)
- **License:** MIT
- **Status:** v0.1 — working scaffold; see [Roadmap](#roadmap)

---

## The problem

Every serious agent tool — Claude Code, Cursor, Copilot, Codex, Gemini CLI —
now reads an `AGENTS.md` at the repo root and a catalog of `SKILL.md` files.
But both conventions are honor-system prose:

- Nothing **compiles** the contract. The non-negotiable rules, layer
  boundaries, and verification checklists live as markdown the agent may or
  may not internalize.
- Nothing **gates** the decision. An agent that's about to rewrite your
  scoring model proceeds with the same confidence as one renaming a variable.
- Nothing **verifies** the checklist ran. "Run `npm test` before handing off"
  is a suggestion, not a gate.

Conductor makes the conventions executable — without asking any agent tool to
change. It ships as a standard MCP server, so anything that speaks MCP gets
contract compilation, skill discovery, and decision gating for free.

## How it works

```text
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    │
└────────────────────────────────────────────────┘
```

Three capability groups:

1. **Contract** — compile an `AGENTS.md` into structured mission,
   non-negotiable rules, layer do/don't boundaries, verification gates,
   skill recommendations, and an out-of-scope list.
2. **Skills** — discover `SKILL.md` skills across project and personal
   scopes with progressive disclosure: metadata costs ~100 tokens, bodies
   load only on demand.
3. **Decision** — gate work through the
   [Consensus Hardening Protocol](https://github.com/icohangar-ops/consensus-hardening-protocol):
   a cheap R0 sanity gate before work starts, and an adversarial
   foundation-attack pass before a high-stakes change locks.

## Quick start

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



Requirements: **Node 23+** (runs TypeScript natively) and **Python 3.10+**
with the published CHP package installed.

```bash
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
```

Register with Claude Code:

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

Or in any MCP client's JSON config:

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

Set `CONDUCTOR_PYTHON` if your Python 3 lives somewhere other than `python3`.

Then, from any project that has an `AGENTS.md`:

> "Load this project's agent contract, list its verification gates, and run a
> decision_adversary pass on the change I'm about to make."

## Tool reference

### `contract_load`

Compile an AGENTS.md (or CLAUDE.md) into a structured contract. Accepts a
file path or a project directory; defaults to the current working directory.

```jsonc
// 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
}
```

The parser is **lossless**: sections it doesn't recognize are preserved
verbatim, so nothing in an unconventional AGENTS.md is dropped.

### `contract_verification`

Returns only the verification gates — the named checklists and shell commands
that must pass before work is handed off. Pair it with your agent's workflow:
run the commands, confirm success, then declare done.

### `skills_list`

Discover SKILL.md skills visible from a project root. Metadata only.

```jsonc
// 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"
    }
  ]
}
```

Search order (first hit per skill name wins):

| Priority | Path | Scope |
|----------|------|-------|
| 1 | `<project>/.conductor/skills/*/SKILL.md` | project |
| 2 | `<project>/.claude/skills/*/SKILL.md` | project |
| 3 | `<project>/.cursor/skills/*/SKILL.md` | project |
| 4 | `~/.claude/skills/*/SKILL.md` | personal |
| 5 | `~/.cursor/skills/*/SKILL.md` | personal |

### `skill_load`

Load the full SKILL.md body for one named skill — the on-demand half of
progressive disclosure. Call it only when the task matches the skill's
description.

### `decision_gate`

The Consensus Hardening Protocol **R0 gate**: the cheapest, highest-leverage
check, run *before* doing the work.

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

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

Any `FATAL` answer halts: stop and reframe before burning tokens on a
problem that isn't scoped, isn't understood, or isn't worth solving.

### `decision_adversary`

A one-shot adversarial pass for high-stakes changes: CHP attacks the claim's
foundations, scores them 0–100, and returns devil's-advocate findings plus a
session status.

```jsonc
// 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..."
}
```

Statuses map to the CHP decision lifecycle
(`EXPLORING → PROVISIONAL_LOCK → LOCKED`, with `HALT` and
`REFRAME_REQUIRED` exits): `EXPLORING` means the claim survived the attack
and work may proceed toward a lock; `HALT`/`REFRAME_REQUIRED` mean the
foundations failed.

### `engine_status`

Health-check the Python engine subprocess. Returns
`{ ok, engine: "chp", version }`.

## What the parser recognizes

`contract_load` is convention-based, not schema-based. It extracts the
patterns AGENTS.md files in the wild actually use:

| Contract field | Source convention |
|----------------|-------------------|
| `mission` | First `Mission` / `Purpose` / `Overview` section |
| `rules` | List items under `Non-negotiables` > `Engineering rules` > generic `rules` (priority-ordered so a generic "Product rules" section never shadows explicit non-negotiables) |
| `layers` | First table with a `Layer` column under an architecture-like heading |
| `gates` | Shell code blocks + list items under checklist / verification / before-completion headings |
| `skills` | Tables with `Ta