Agent Conductor

Agent Conductor

AGENTS.md を入力すれば、統制されたエージェントチームが出力されます。

Agent Conductor は、MCP サーバーです。コーディングエージェントのエコシステムで定着した 2 つの規約、つまり AGENTS.md の運用マニュアルと SKILL.md のスキルを、 受動的なドキュメントから能動的なオーケストレーション層へと変え、重大な変更をコンセンサス強化型の意思決定エンジンで制御します。

• ミラー: codeberg.org/cubiczan/agent-conductor · github.com/icohangar-ops/agent-conductor
• ライセンス: MIT
• ステータス: v0.1 — 動作する足場です。ロードマップをご覧ください。

---

課題

Claude Code、Cursor、Copilot、Codex、Gemini CLI など、本格的なエージェントツールはどれも、 リポジトリのルートにある AGENTS.md と、SKILL.md ファイルのカタログを読み込むようになりました。 しかし、どちらの規約も、守るかどうかは本人次第の文章にすぎません。

• 契約をコンパイルするものはありません。譲れないルール、レイヤーの境界、検証チェックリストは Markdown として記述されており、エージェントがそれを理解するかどうかはわかりません。
• 意思決定をゲートするものはありません。スコアリングモデルを書き換えようとしているエージェントも、変数名を変更するエージェントと同じ確信度で作業を進めます。
• チェックリストの実行を検証するものはありません。「引き渡す前に npm test を実行する」は提案であって、ゲートではありません。

Conductor は、エージェントツールに変更を求めることなく、これらの規約を実行可能にします。 標準的な MCP サーバーとして提供されるため、MCP に対応するあらゆるツールが、契約のコンパイル、スキルの検出、意思決定のゲート機能をすぐに利用できます。

仕組み

MCP client (Claude Code / Cursor / Copilot / ...)
        │  stdio (JSON-RPC, MCP)
        ▼
┌────────────────────────────────────────────────┐
│ TypeScript front end (src/)                    │
│   contract/parser.ts   AGENTS.md → contract    │
│   contract/workspace.ts Multi-root merge       │
│   skills/loader.ts     SKILL.md discovery      │
│   server.ts            7 MCP tools             │
└────────────────┬───────────────────────────────┘
                 │  newline-delimited JSON, child stdio
                 ▼
┌────────────────────────────────────────────────┐
│ Python decision engine (engine/)               │
│   vendored Consensus Hardening Protocol core   │
│   R0 gates · foundation attacks · lifecycle    │
└────────────────────────────────────────────────┘

3 つの機能グループがあります。

1. 契約 — AGENTS.md を、構造化されたミッション、譲れないルール、レイヤーごとの禁止事項と許可事項、検証ゲート、スキルの推奨事項、対象範囲外のリストにコンパイルします。
2. スキル — プロジェクトおよび個人のスコープにある SKILL.md スキルを、段階的開示によって検出します。メタデータのコストは約 100 トークンで、本文は必要なときにのみ読み込まれます。
3. 意思決定 — コンセンサス強化プロトコルを通じて作業を制御します。作業開始前に低コストの R0 サニティゲートを実行し、重大な変更を確定する前に、敵対的な基盤攻撃チェックを行います。

クイックスタート

要件: Node 23 以降（TypeScript をネイティブに実行）および Python 3.9 以降 （標準ライブラリのみ。エンジンの実行に pip のインストールは不要です）。

git clone https://codeberg.org/cubiczan/agent-conductor.git
cd agent-conductor
npm install
npm test            # TypeScript tests (parser, skills, multi-root, 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

または、任意の MCP クライアントの JSON 設定で登録します。

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

Python 3 が python3 以外の場所にある場合は、CONDUCTOR_PYTHON を設定してください。

次に、AGENTS.md がある任意のプロジェクトで、次のように指示します。

「このプロジェクトのエージェント契約を読み込み、検証ゲートを一覧表示して、これから行う変更に対して decision_adversary パスを実行してください。」

ツールリファレンス

contract_load

AGENTS.md（または CLAUDE.md）を構造化された契約にコンパイルします。ファイルパス、プロジェクトディレクトリ、明示的な roots リスト、または rootsFile マップを受け付けます。デフォルトでは現在の作業ディレクトリを使用します。複数ルートのワークスペースでは、レイヤーテーブルと検証コマンドを統合した1 つの契約を出力します。呼び出し元が段階的開示の予算内に収まるよう、セクション本文はこのツールでは出力されません（メタデータと構造化フィールドのみ）。

// 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

検証ゲート、つまり作業の引き渡し前に通過する必要がある、名前付きチェックリストとシェルコマンドのみを返します。エージェントのワークフローに組み込み、コマンドを実行して成功を確認してから完了を宣言してください。contract_load と同じ単一ルートまたは複数ルートの入力を受け付けます。

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"
    }
  ]
}

検索順（スキル名ごとに最初に見つかったものを採用します）。マルチルートワークスペースでは、プロジェクトの各ルートを順に処理した後、個人用スコープを一度だけ処理します。

優先度	パス	スコープ
1	<root>/.conductor/skills/*/SKILL.md	プロジェクト
2	<root>/.claude/skills/*/SKILL.md	プロジェクト
3	<root>/.cursor/skills/*/SKILL.md	プロジェクト
4	~/.claude/skills/*/SKILL.md	個人用
5	~/.cursor/skills/*/SKILL.md	個人用

skill_load

指定したスキルの SKILL.md 本文全体を読み込みます。段階的開示におけるオンデマンド部分です。タスクがそのスキルの説明に合致する場合にのみ呼び出してください。

decision_gate

Consensus Hardening Protocol の R0 ゲートです。最も低コストで効果の高いチェックであり、作業を始める前に実行します。

// 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

重大な変更に対する、1 回限りの敵対的レビューです。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 ファイルで使われているパターンを抽出します。

コントラクトのフィールド	参照する規約
mission	最初の Mission／Purpose／Overview セクション
rules	Non-negotiables ＞ Engineering rules ＞ 一般的な rules の順に優先されるリスト項目（優先順位により、一般的な「Product rules」セクションが明示的な必須事項より優先されることはありません）
layers	アーキテクチャ関連の見出しの下にある、Layer 列を含む最初の表
gates	チェックリスト／検証／完了前の見出しの下にある、シェルコードブロックとリスト項目
skills	Task／Skill／Why 列を含む表。リンクはテキストと URL に解決されます
outOfScope	対象外／目標外の見出しの下にあるリスト
sections	すべてをそのまま保持する、情報を失わないフォールバック

コードフェンス内の見出しは無視されます。表の見出しに強調が含まれていても処理できます。抽出したテキストからは Markdown のリンクと強調が取り除かれます。

スキルの作成

スキルは、YAML フロントマターを含む SKILL.md を格納したディレクトリです。

---
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（単一ルートでのコンパイル）。
• examples/multimodule — 追加のソースルートを持つ Gradle 形式の例。スキルは modules/billing の外にある shared/ の下にあります。

モノレポの手引き

単純なローダーは、指定されたディレクトリだけを走査します。これは、sourceSet がモジュールの外を指す（srcDirs = ['src/main/java', '../shared/src']）場合に Gradle モジュールで問題が起きるのと同じです。追加のツリーは実際の作業対象ですが、モジュールディレクトリ内にはありません。

追加のルートはすべて宣言してください。Conductor はルートが欠けている場合はフェイルクローズし、ルートを勝手に作成したり、暗黙にスキップしたりすることはありません。

1. ルートマップを作成する

標準の場所（最初に見つかったものを使用）：

ファイル	使用するタイミング
.conductor/roots.json	.conductor/skills の隣
conductor.roots.json	リポジトリルートで使う場合
.conductor/roots / conductor.roots	行指向の代替形式

JSON オブジェクト（ID は省略可能）：

{
  "roots": [
    { "id": "workspace", "path": "." },
    { "id": "billing", "path": "modules/billing" },
    { "id": "shared", "path": "shared" }
  ]
}

パスの JSON 配列：

[".", "modules/billing", "shared"]

行指向のマップ（# コメントを使用できます）：

workspace: .
billing: modules/billing
shared

相対パスは、マップファイルのディレクトリを基準に解決されます。

2. スキルを追加ルートに配置する

examples/multimodule/
├── conductor.roots.json
├── AGENTS.md                    # workspace layers + `npm test`
├── modules/billing/AGENTS.md    # module layers + `npm -C modules/billing test`
└── shared/.conductor/skills/shared-ledger/SKILL.md

modules/billing だけでは shared-ledger を参照できません。マップを宣言すると、skills_list と skill_load はすべてのルートを走査し、その後で個人スコープを走査します。重複時は最初に見つかったものが優先されます。

3. ツールを呼び出す

// Auto-detect a roots map under a directory
{ "path": "examples/multimodule" }

// Explicit list (relative paths resolve against `path` or cwd)
{ "path": "examples/multimodule", "roots": [".", "modules/billing", "shared"] }

// Explicit map file
{ "rootsFile": "examples/multimodule/conductor.roots.json" }

contract_load は引き続きセクション本文を含まない要約を返し、contract_verification は引き続きゲートのみを返し、skills_list は引き続きフロントマターメタデータを返します。examples/pipeline-pulse を含む、マップファイルのない単一ルートのプロジェクトでは、従来のコンパイルパスが維持されます。

プロジェクト構成

.
├── 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 (incl. multi-root)
│   ├── 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 request router
│   ├── test_bridge.py         # protocol tests
│   └── vendor/cme/            # vendored CHP core (MIT, byte-identical; see NOTICE.md)
├── examples/pipeline-pulse/   # real AGENTS.md fixture + example skill
├── examples/multimodule/      # extra source root (skills outside the module)
└── test/                      # node:test suites (run the .ts directly)

開発

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. 実行時依存関係を新たに追加しない — @modelcontextprotocol/sdk と zod のみを使用します。Markdown とフロントマターの解析は手書きのまま維持し、テストします。
3. 消去可能な TypeScript のみを使用する — ソースは Node の型ストリッピングで実行できる必要があります（enum とパラメータープロパティは禁止）。
4. ベンダーコードの取り扱いを厳守する — engine/vendor/cme/ は、文書化された __init__.py のパッチを除き、上流とバイト単位で同一に保ちます。エンジンの動作変更は bridge.py に加えてください。

コントラクト検証 CLI（行 21：実行可能なコントラクト）

contract_load を支えるものと同じパーサーを CLI サブコマンドとして公開しているため、CI で AGENTS.md をフェイルクローズでコンパイルし、宣言されている検証ゲートを（任意で）実行できます。

agent-conductor verify AGENTS.md                  # compile; exit 0/1
agent-conductor verify --require-gates AGENTS.md  # also fail when the contract
                                                  # declares no gates (anti-placeholder)
agent-conductor verify --run-gates AGENTS.md      # run every declared gate
                                                  # command; exit 1 on failure

--run-gates を指定することで、「コントラクトを読み取る」が「コントラクトを強制する」に変わります。AGENTS.md 内のチェックリストのシェルブロックが CI のステップになります。このリポジトリ独自の CI でも、自身の AGENTS.md をこの方法でコンパイルしています。パターンの元となるリポジトリで、そのパターンを実際に活用しています。

ゲート実行の信頼ポリシー。 --run-gates は、コマンドラインで渡された単一のコントラクトファイルのゲートコマンドのみを実行します。CLI は単一ファイルパーサー（loadContract）でそのファイルをコンパイルし、他のワークスペースルートのゲートを結合することはありません。複数ルートのワークスペース全体に適用する場合は、CI でルートごとに CLI を実行してください（このリポジトリの CI もそのように実行します）。ワークスペースコンパイラー（src/contract/workspace.ts）は、ライブラリとして使用すると、宣言されたルート全体のゲートを結合します。このインターフェースは、宣言されたすべてのルートを信頼し、ルートごとのフィルタリングや確認機能はありません。完全に信頼できるルートのみを指定してください。コマンドごとのタイムアウト（デフォルトは 120s）は、ハングしたプロセスの実行時間を制限しますが、悪意のあるプロセスには対処できません。

スキルロック（行 23：サプライチェーンの規律）

プロジェクトでは、プロジェクトルートの skills-lock.json で信頼するスキルを固定できます。

{
  "version": 1,
  "skills": {
    "pipeline-scoring": {
      "path": ".conductor/skills/pipeline-scoring/SKILL.md",
      "sha256": "<hex digest of the SKILL.md bytes>"
    }
  }
}

ロックファイルが存在する場合、skill_load はフェイルクローズで動作します。SKILL.md のバイト列をハッシュ化（SHA-256）して固定されたダイジェストと比較し、エントリの欠落、ファイルの改ざん、または古いハッシュがある場合は、スキル名と両方のダイジェストを示す SkillLockError を返して読み込みを拒否します。検出（フロントマターのみ）は未検証のままです。脅威の境界は、スキルの コンテンツ がエージェントに渡る時点です。ロックファイルがない場合は動作に変更はありません（ロックのコミットによる検証はオプトインです）。

脅威モデルに関する注記 — ロックで保護されるものと、保護されないもの。

• ダイジェストの対象は SKILL.md ファイル全体で、フロントマターも含まれます。フロントマター（説明、ツール一覧）を編集するとダイジェストが変わり、ロックを更新するまで skill_load はハッシュ不一致で失敗します。個別には検証されないのは、検出時のメタデータです。読み込み前に description に基づいてスキルを選択するルーターは、未検証のフロントマターを読み取ります（ロックファイルのないルートでは、何も検証されません）。メタデータと本文の境界はファイル単位ではなく API レベルです。ロックはバイト列をハッシュ化することで両方を保護し、この区別は検証前にどの利用者がどの部分を読み取るかを説明するものにすぎません。
• ロックの解決はルートごとに行われます。loadSkill は、スキルを所有するルート（そのパスを含む許可済みルート）の skills-lock.json に照らしてスキルを検証します。複数ルートのワークスペースでは、独自のロックファイルを持たないルートのスキルは未検証で読み込まれます。ロックがルートをまたいで統合されることはありません。これは、宣言されたルート間でレイヤーを先勝ちで統合するコントラクト仕様のコンパイルとは意図的に異なります。あるルートのロックで別のルートのスキルも保護されると思い込まないでください。

今すぐロックを導入する方法。 まだ lock generate サブコマンドはありません（予定：agent-conductor lock generate で .conductor/skills/ を走査し、検証側と同じ computeLockEntry を使って skills-lock.json を生成／更新します）。それまではロックを手動で作成し、shasum -a 256 SKILL.md（または openssl dgst -sha256）を使って、SKILL.md の正確なバイト列からダイジェストを固定してください。ダイジェストの対象はフロントマターを含むファイル全体です。

ロードマップ

バージョン	テーマ	範囲
v0.2	強制適用	contract_verification ゲートを実際のサブプロセスとして実行し、合格／不合格の証拠を返すことで、「コントラクトを読む」から「コントラクトを強制適用する」へ移行します — 0.2.0 でリリース済み、CLI の提供範囲：agent-conductor verify --run-gates <AGENTS.md>（プレースホルダー対策ゲートには --require-gates も使用）。contract_verification MCP ツールは引き続きゲートを一覧表示するだけで、実行はしません。セッション内の実行証拠は 0.2.0 には含まれません。副作用を伴う実行を MCP のインターフェースに導入するには、明示的な同意／サンドボックス化モデルが必要です
v0.3	オーケストレーション	コントラクトのレイヤーを CHP の MeshAgent 機能（produces／consumes）に対応付け、複数エージェントによる完全な熟議セッションを MCP 経由で公開します
v0.4	レジストリ	ソースレビュー用プロンプトを使用して、リモートカタログ（awesome-agent-skills 形式）から審査済みスキルをインストールします

出典

Conductor は、実績のあるコンポーネントを書き直すのではなく、意図的に再利用しています。

コンポーネント	出典	ライセンス
意思決定エンジン（engine/vendor/cme/）	consensus-hardening-protocol	MIT
MCP サーバーとレジストリの構成	onchainmind	MIT
スキル品質基準	VoltAgent/awesome-agent-skills	—
サンプルフィクスチャ	Pipeline Pulse CRM 運用マニュアル	フィクスチャ

ベンダリングの詳細は engine/vendor/NOTICE.md を、2 言語設計の背景にある考え方は ARCHITECTURE.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。ベンダリングされたコンポーネントには、引き続き各コンポーネントの元の MIT ライセンスが適用されます。