Agent Conductor

Cubiczan stack — Profile · CHP · Estás aquí: agent-conductor

AGENTS.md entra, equipo de agentes gobernado sale.

Agent Conductor es un servidor MCP que convierte las dos convenciones en las que el ecosistema de agentes de codificación ha convergido — los manuales operativos AGENTS.md y las habilidades SKILL.md — de documentación pasiva a una capa de orquestación activa, con un motor de decisiones endurecido por consenso que controla los cambios de alto riesgo.

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

• Licencia: MIT

• Estado: v0.1 — andamiaje funcional; ver Hoja de ruta

El problema

Cada herramienta de agente seria — Claude Code, Cursor, Copilot, Codex, Gemini CLI — ahora lee un AGENTS.md en la raíz del repositorio y un catálogo de archivos SKILL.md. Pero ambas convenciones son prosa de sistema de honor:

• Nada compila el contrato. Las reglas no negociables, los límites de capas y las listas de verificación viven como markdown que el agente puede o no internalizar.

• Nada controla la decisión. Un agente que está a punto de reescribir tu modelo de puntuación procede con la misma confianza que uno que renombra una variable.

• Nada verifica que la lista de verificación se haya ejecutado. «Ejecuta npm test antes de entregar» es una sugerencia, no un control.

Conductor hace ejecutables las convenciones — sin pedir a ninguna herramienta de agente que cambie. Se distribuye como un servidor MCP estándar, por lo que cualquier cosa que hable MCP obtiene compilación de contratos, descubrimiento de habilidades y control de decisiones de forma gratuita.

Related MCP server: @event4u/agent-config

Cómo funciona

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

Tres grupos de capacidades:

1. Contrato — compila un AGENTS.md en misión estructurada, reglas no negociables, límites de capas de hacer/no hacer, controles de verificación, recomendaciones de habilidades y una lista de fuera de alcance.

2. Habilidades — descubre habilidades SKILL.md en ámbitos de proyecto y personales con divulgación progresiva: los metadatos cuestan ~100 tokens, los cuerpos se cargan solo bajo demanda.

3. Decisión — controla el trabajo mediante el Protocolo de Endurecimiento por Consenso: un control de cordura R0 barato antes de que comience el trabajo, y una pasada adversarial de ataque a los cimientos antes de que un cambio de alto riesgo se bloquee.

Inicio rápido

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

Requisitos: Node 23+ (ejecuta TypeScript de forma nativa) y Python 3.10+ con el paquete CHP publicado instalado.

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

Regístrate con Claude Code:

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

O en la configuración JSON de cualquier cliente MCP:

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

Establece CONDUCTOR_PYTHON si tu Python 3 se encuentra en un lugar distinto de python3.

Luego, desde cualquier proyecto que tenga un AGENTS.md:

«Carga el contrato de agente de este proyecto, lista sus controles de verificación y ejecuta una pasada decision_adversary sobre el cambio que estoy a punto de hacer.»

Referencia de herramientas

contract_load

Compila un AGENTS.md (o CLAUDE.md) en un contrato estructurado. Acepta una ruta de archivo o un directorio de proyecto; por defecto, el directorio de trabajo actual.

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

El analizador es sin pérdidas: las secciones que no reconoce se conservan textualmente, por lo que nada en un AGENTS.md no convencional se descarta.

contract_verification

Devuelve solo los controles de verificación — las listas de verificación con nombre y los comandos de shell que deben pasar antes de entregar el trabajo. Combínalo con el flujo de trabajo de tu agente: ejecuta los comandos, confirma el éxito y luego declara que está hecho.

skills_list

Descubre habilidades SKILL.md visibles desde la raíz de un proyecto. Solo metadatos.

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

Orden de búsqueda (la primera coincidencia por nombre de habilidad gana):

skill_load

Carga el cuerpo completo de SKILL.md para una habilidad con nombre — la mitad bajo demanda de la divulgación progresiva. Llámala solo cuando la tarea coincida con la descripción de la habilidad.

decision_gate

El control R0 del Protocolo de Endurecimiento por Consenso: la verificación más barata y de mayor apalancamiento, que se ejecuta antes de hacer el trabajo.

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

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

Cualquier respuesta FATAL detiene: detente y reformula antes de quemar tokens en un problema que no está delimitado, no se entiende o no vale la pena resolver.

decision_adversary

Una pasada adversarial de un solo disparo para cambios de alto riesgo: CHP ataca los cimientos de la afirmación, los puntúa de 0 a 100 y devuelve hallazgos de abogado del diablo más un estado de sesión.

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

Los estados se asignan al ciclo de vida de decisión de CHP (EXPLORING → PROVISIONAL_LOCK → LOCKED, con salidas HALT y REFRAME_REQUIRED): EXPLORING significa que la afirmación sobrevivió al ataque y el trabajo puede continuar hacia un bloqueo; HALT/REFRAME_REQUIRED significan que los cimientos fallaron.

engine_status

Comprueba la salud del subproceso del motor Python. Devuelve { ok, engine: "chp", version }.

Lo que reconoce el analizador

contract_load se basa en convenciones, no en esquemas. Extrae los patrones que los archivos AGENTS.md en la naturaleza realmente usan:

Los encabezados dentro de bloques de código se ignoran; las tablas toleran énfasis en los encabezados; los enlaces y el énfasis de markdown se eliminan del texto extraído.

Escribir habilidades

Una habilidad es un directorio que contiene SKILL.md con frontmatter YAML:

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

Nivel de calidad (heredado de los estándares de awesome-agent-skills): descripción en tercera persona con palabras clave coincidentes, metadatos alrededor de 100 tokens, cuerpo de menos de 500 líneas, sin rutas absolutas específicas de la máquina, declarar solo las herramientas que la habilidad necesita.

El ejemplo incluido — examples/pipeline-pulse — es un AGENTS.md completo del mundo real más una habilidad de ámbito de proyecto, y es lo que compila la suite de pruebas.

Estructura del proyecto

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

Desarrollo

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)

Reglas de la casa (el conjunto completo está en el AGENTS.md de este repositorio):

1. stdout es sagrado — el transporte MCP lo posee; todo el registro va a stderr en ambos lados del puente.

2. Cero dependencias nuevas de Node en tiempo de ejecución — solo @modelcontextprotocol/sdk y zod; markdown/frontmatter se mantienen hechos a mano. CHP es una dependencia de PyPI.

3. Solo TypeScript borrable — el código fuente debe ejecutarse bajo la eliminación de tipos de Node (sin enums, sin propiedades de parámetros).

4. CHP vía PyPI — instala consensus-hardening-protocol; no lo revendas bajo engine/. Las correcciones del protocolo pertenecen al upstream.

5. Python 3.10+ — requerido por el paquete publicado.

Hoja de ruta

Procedencia

Conductor reutiliza deliberadamente componentes probados en lugar de reescribirlos:

Consulta engine/NOTICE.md y ARCHITECTURE.md para el diseño de dos lenguajes.

Cubiczan stack

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

Conductor compila AGENTS.md + SKILL.md en herramientas MCP y enruta decisiones de alto riesgo a través de CHP — el mismo modelo de bloqueo que Metabocommand usa para aprobaciones financieras.

Licencia

MIT — ver LICENSE. Los componentes incluidos conservan sus licencias MIT originales.