Agent Conductor

Cubiczan-Stack — Profil · CHP · Du bist hier: agent-conductor

AGENTS.md rein, gesteuertes Agententeam raus.

Agent Conductor ist ein MCP-Server, der die beiden Konventionen, auf die sich das Coding-Agent-Ökosystem geeinigt hat — AGENTS.md-Betriebshandbücher und SKILL.md-Fähigkeiten — von passiver Dokumentation in eine aktive Orchestrierungsebene verwandelt, mit einer konsensgehärteten Entscheidungs-Engine, die risikoreiche Änderungen absichert.

• Mirrors: Cubiczan/agent-conductor · codeberg.org/cubiczan/agent-conductor · icohangar-ops/agent-conductor

• Lizenz: MIT

• Status: v0.1 — funktionierendes Grundgerüst; siehe Roadmap

Das Problem

Jedes ernsthafte Agent-Tool — Claude Code, Cursor, Copilot, Codex, Gemini CLI — liest jetzt eine AGENTS.md im Repository-Stammverzeichnis und einen Katalog von SKILL.md-Dateien. Aber beide Konventionen sind Prosa auf Ehrensystem-Basis:

• Nichts kompiliert den Vertrag. Die nicht verhandelbaren Regeln, Schichtgrenzen und Verifikations-Checklisten existieren als Markdown, das der Agent möglicherweise verinnerlicht oder auch nicht.

• Nichts steuert die Entscheidung. Ein Agent, der kurz davor ist, dein Scoring-Modell neu zu schreiben, geht mit derselben Selbstsicherheit vor wie einer, der eine Variable umbenennt.

• Nichts verifiziert, dass die Checkliste ausgeführt wurde. „Führe npm test aus, bevor du übergibst“ ist ein Vorschlag, kein Tor.

Conductor macht die Konventionen ausführbar — ohne dass ein Agent-Tool geändert werden muss. Es wird als standardmäßiger MCP-Server ausgeliefert, sodass alles, was MCP spricht, Vertragskompilierung, Fähigkeitserkennung und Entscheidungssteuerung kostenlos erhält.

Related MCP server: @event4u/agent-config

So funktioniert es

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

Drei Fähigkeitsgruppen:

1. Vertrag — kompiliert eine AGENTS.md in eine strukturierte Mission, nicht verhandelbare Regeln, Schicht-Grenzen (erlaubt/nicht erlaubt), Verifikations-Gates, Fähigkeitsempfehlungen und eine Liste außerhalb des Geltungsbereichs.

2. Fähigkeiten — entdeckt SKILL.md-Fähigkeiten über Projekt- und persönliche Bereiche mit progressiver Offenlegung: Metadaten kosten ~100 Tokens, Inhalte werden nur bei Bedarf geladen.

3. Entscheidung — steuert Arbeit durch das Consensus Hardening Protocol: ein kostengünstiges R0-Sanity-Gate vor Arbeitsbeginn und ein adversarischer Fundament-Angriffspass, bevor eine risikoreiche Änderung gesperrt wird.

Schnellstart

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

Anforderungen: Node 23+ (führt TypeScript nativ aus) und Python 3.10+ mit dem veröffentlichten CHP-Paket installiert.

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

Registriere bei Claude Code:

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

Oder in der JSON-Konfiguration eines beliebigen MCP-Clients:

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

Setze CONDUCTOR_PYTHON, wenn dein Python 3 nicht unter python3 liegt.

Dann, aus einem beliebigen Projekt mit einer AGENTS.md:

„Lade den Agentenvertrag dieses Projekts, liste seine Verifikations-Gates auf und führe einen decision_adversary-Pass für die Änderung aus, die ich gleich vornehmen werde.“

Tool-Referenz

contract_load

Kompiliert eine AGENTS.md (oder CLAUDE.md) in einen strukturierten Vertrag. Akzeptiert einen Dateipfad oder ein Projektverzeichnis; standardmäßig wird das aktuelle Arbeitsverzeichnis verwendet.

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

Der Parser ist verlustfrei: Abschnitte, die er nicht erkennt, werden wörtlich erhalten, sodass nichts in einer unkonventionellen AGENTS.md verloren geht.

contract_verification

Gibt nur die Verifikations-Gates zurück — die benannten Checklisten und Shell-Befehle, die bestehen müssen, bevor die Arbeit übergeben wird. Kombiniere es mit dem Workflow deines Agents: Führe die Befehle aus, bestätige den Erfolg und erkläre dann die Arbeit für abgeschlossen.

skills_list

Entdeckt SKILL.md-Fähigkeiten, die von einem Projektstammverzeichnis aus sichtbar sind. Nur Metadaten.

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

Suchreihenfolge (erster Treffer pro Fähigkeitsname gewinnt):

skill_load

Lädt den vollständigen SKILL.md-Inhalt für eine benannte Fähigkeit — die On-Demand-Hälfte der progressiven Offenlegung. Rufe es nur auf, wenn die Aufgabe zur Beschreibung der Fähigkeit passt.

decision_gate

Das R0-Gate des Consensus Hardening Protocol: die kostengünstigste und wirkungsvollste Prüfung, die vor der Arbeit ausgeführt wird.

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

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

Jede FATAL-Antwort stoppt: Halte an und formuliere neu, bevor du Tokens für ein Problem verbrennst, das nicht abgegrenzt, nicht verstanden oder nicht lösenswert ist.

decision_adversary

Ein einmaliger adversarischer Pass für risikoreiche Änderungen: CHP greift die Grundlagen der Behauptung an, bewertet sie mit 0–100 und liefert Teufelsanwalt-Ergebnisse sowie einen Sitzungsstatus.

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

Statuswerte entsprechen dem CHP-Entscheidungslebenszyklus (EXPLORING → PROVISIONAL_LOCK → LOCKED, mit HALT- und REFRAME_REQUIRED-Ausgängen): EXPLORING bedeutet, dass die Behauptung den Angriff überstanden hat und die Arbeit in Richtung einer Sperre fortgesetzt werden kann; HALT/REFRAME_REQUIRED bedeuten, dass die Grundlagen versagt haben.

engine_status

Überprüft den Zustand des Python-Engine-Subprozesses. Gibt { ok, engine: "chp", version } zurück.

Was der Parser erkennt

contract_load ist konventionsbasiert, nicht schemabasiert. Es extrahiert die Muster, die AGENTS.md-Dateien in der Praxis tatsächlich verwenden:

Überschriften in Codeblöcken werden ignoriert; Tabellen tolerieren Hervorhebungen in Kopfzeilen; Markdown-Links und Hervorhebungen werden aus extrahiertem Text entfernt.

Fähigkeiten schreiben

Eine Fähigkeit ist ein Verzeichnis, das SKILL.md mit YAML-Frontmatter enthält:

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

Qualitätsmaßstab (übernommen aus den awesome-agent-skills-Standards): Beschreibung in dritter Person mit abgleichbaren Schlüsselwörtern, Metadaten um 100 Tokens, Inhalt unter 500 Zeilen, keine maschinenspezifischen absoluten Pfade, nur die Werkzeuge deklarieren, die die Fähigkeit benötigt.

Das gebündelte Beispiel — examples/pipeline-pulse — ist eine vollständige reale AGENTS.md plus eine projektspezifische Fähigkeit und wird von der Testsuite kompiliert.

Projektstruktur

.
├── 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)

Entwicklung

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)

Hausregeln (die vollständige Liste steht in der eigenen AGENTS.md dieses Repos):

1. stdout ist heilig — der MCP-Transport besitzt es; alle Protokollierung geht auf stderr auf beiden Seiten der Brücke.

2. Null neue Node-Laufzeitabhängigkeiten — nur @modelcontextprotocol/sdk und zod; Markdown/Frontmatter bleiben handgeschrieben. CHP ist eine PyPI-Abhängigkeit.

3. Nur löschbares TypeScript — Quellcode muss unter Node's Typ-Stripping laufen (keine Enums, keine Parameter-Eigenschaften).

4. CHP über PyPI — installiere consensus-hardening-protocol; nicht unter engine/ erneut venden. Protokoll-Fixes gehören upstream.

5. Python 3.10+ — vom veröffentlichten Paket gefordert.

Roadmap

Herkunft

Conductor verwendet bewusst bewährte Komponenten wieder, anstatt sie neu zu schreiben:

Siehe engine/NOTICE.md und ARCHITECTURE.md für das Zweisprachen-Design.

Cubiczan-Stack

| Governance | consensus-hardening-protocol · agent-conductor · compliance-as-code-agent · cleanmandate | | Plattform | cubiczan-mcp-server · operational-intelligence · software-factory |

Conductor kompiliert AGENTS.md + SKILL.md in MCP-Werkzeuge und leitet risikoreiche Entscheidungen über CHP — dasselbe Sperrmodell, das Metabocommand für Finanzgenehmigungen verwendet.

Lizenz

MIT — siehe LICENSE. Eingebettete Komponenten behalten ihre ursprünglichen MIT-Lizenzen.