agent-harness-template

English · Español

---

English

A project template for AI-agent workflows with an enforced, verifiable review chain — not just a suggested process. Everything beyond this README is in Spanish (see Docs are in Spanish below); this section is a complete, standalone summary of what the repo is and why it's built this way.

One-sentence idea

Instead of piling up many skills that saturate an agent's context, you set up a workflow with clear roles — Claude orchestrates, a builder implements, an auditor closes the loop — and back it with a layered enforcement chain that doesn't rely on the agent's good behavior alone.

Why this is more than a prompt template

Most "AI agent workflow" templates are a system prompt and a hope. This one adds a self-verifying harness: a test suite (scripts/verify-agent-harness.sh, 60+ assertions) that actively tries to bypass its own gates — forged review files, hash mismatches, config spoofing, git-diff-config drift between machines — and fails loudly if any of them work. Three real audit rounds (documented in the commit history) each found and closed genuine bypasses before this was published.

The pipeline

grill-me → grill-with-docs → [prototype?] → to-spec → to-tickets → implement → audit → human review

Each phase feeds the next. Nothing is skipped except prototype (optional — only when a design question can't be resolved on paper).

1. Claude = orchestrator — drives the pipeline, decides what and in what order, delegates construction. Never writes production code directly. Runs on Claude Fable 5 (pinned in the subagent's frontmatter): highest-leverage role, low token volume, so it gets the most capable reasoning model.
2. Builder (Hermes / Codex / the Claude Code builder subagent) — implements closed tickets with TDD. Doesn't negotiate scope. High token volume, so it runs on a mid-cost model (Sonnet, pinned for the Claude Code subagent; a config recommendation for Hermes/Codex — see docs/SUPPORT.md).
3. Security Auditor — closes every ticket on three axes (security, coding standards, spec fidelity). No approval, no "completed" status. Ever.
4. Human review — the PR review on GitHub. This is the real authority; the AI can write the audit trail but cannot approve its own PR (see below).

Quality gates: measurable by default

New projects are born with a gated Python toolchain (pinned in requirements-dev.txt, configured in pyproject.toml): cyclomatic complexity (ruff C901 ≤ 10) and function size (PLR0915 ≤ 40 statements), a module-size ratchet (scripts/check_module_sizes.py, 200-line limit with a shrink-only baseline in quality/), a coverage floor (fail_under = 80) and optional import-direction contracts (import-linter). bash scripts/verify.sh is the single "done means green" entrypoint — CI runs the exact same script, and every gate auto-activates the moment src/ or tests/ exist. The point (borrowed from Robert Martin's take on AI-written code): infer quality from indicators instead of reading every generated line.

Enforcement: three honest layers

Skills ask for good behavior. What actually holds it together is layered, and each layer is explicit about what it guarantees and what it doesn't:

1. Local discipline (git hooks + per-engine adapters). sh scripts/install-hooks.sh installs pre-commit (secrets via gitleaks + lint) and pre-push (a branch-level review gate: you can't push code without an APPROVED review tied to the hash of the base...HEAD diff — strict parser, no NOT APPROVED, no ticket without a digit, no mismatched hash). This curbs drift. It is not authority: under a cooperative agent, the AI can write its own review.

2. Authority — PR + branch protection + CODEOWNERS (scripts/setup-branch-protection.sh). This is what breaks self-approval. main requires a code-owner review, require_last_push_approval, and passing CI checks. The AI writes the review; it cannot approve the PR — approval is a distinct, independent identity. (GitHub also enforces, unconditionally, that a PR's author can never approve their own PR — a hard platform rule, not a repo setting.)

3. Repo-level guarantee (.github/workflows/ci.yml). A quality job (ruff, mypy, bandit, pytest, gitleaks, verify-agent-harness.sh) plus an audit-trail job that requires a versioned APPROVED review tied to the exact diff hash of the PR. The local gate and CI share one library (scripts/lib/scope.sh), so they certify the same object — not two different diffs that happen to look similar. sh scripts/doctor.sh verifies the whole setup, including the actual branch-protection fields (not just that protection is "on").

Tested: verify-agent-harness.sh exercises the full battery against both gates — forged review, NOT APPROVED, digit-less ticket, aggregated multi-commit diffs, a broken base ref, a copy-pasted review from another diff — and fails if any of them slip through. Honestly: this is a cooperative, spec-driven harness with real authority at the PR and a CI backstop — not "impossible to bypass locally," but a verifiable approval chain at merge time. Full threat model in SECURITY.md; how to pass the gate as an outside contributor in CONTRIBUTING.md.

The same pattern at the model level (API)

In Claude Code, orchestrator and builder are subagents with pinned models (see ADR-0003). When the pipeline runs against the raw API instead, the same "direct / build" pattern exists at the model level via Anthropic's advisor tool: a fast executor (builder → Sonnet/Haiku) that consults a smarter advisor mid-generation (orchestrator → Opus 4.8 or 4.7 only — the advisor tool rejects any other model, including Fable, with a 400). See docs/adr/0002-advisor-tool-mapping.md.

Getting started

1. Instantiate the template and run the mandatory bootstrap.

   Path A (recommended): GitHub's "Use this template" button → create your repo → clone it and bootstrap (tolerates the existing .git):

   git clone https://github.com/your-org/my-project.git && cd my-project
   sh scripts/bootstrap.sh --owner @your-username --remote https://github.com/your-org/my-project.git

   Path B: clone this template, drop its history, point at your own empty repo:

   git clone <this-template-url> my-project && cd my-project && rm -rf .git
   sh scripts/bootstrap.sh --owner @your-username --remote https://github.com/your-org/my-project.git

   --remote always points at your own repo, never the template's. Bootstrap configures CODEOWNERS, the remote, audit.baseRef, the initial commit, hooks, the first push, branch protection, and a final doctor check. All further work goes through feature branches + PRs; main only changes via a merge with an approved human review and green CI.

2. Start your engine in that folder (Claude Code, Codex, or Hermes). It acts as the orchestrator, reading AGENTS.md. For Codex/Hermes, see the portability table in AGENTS.md.

3. Kick off the pipeline: tell the orchestrator your goal. It starts with grill-me and interrogates you until every ambiguity is closed.

4. The flow proceeds on its own from there: grill-with-docs fills in docs/CONTEXT.md and the ADRs, to-spec produces the spec, to-tickets slices it, implement delegates each ticket to the builder (TDD), and security-auditor approves before any ticket closes.

License

Copyright © 2026 prgr1no and contributors.

This project is distributed under GPL-3.0 (LICENSE). It includes material adapted from mattpocock/skills (MIT, GPL-3.0 compatible; the original notice is preserved in docs/CREDITS.md).

Note that when you instantiate the template, the harness files copied into your project (scripts, hooks, skills, framework docs) remain GPL-3.0: if you distribute your project, those parts keep the license and its obligations. Your own code on top of the template is yours to license as you choose.

Docs are in Spanish

This README is bilingual by design so anyone landing on the repo gets the full picture without needing Spanish. Every other document — AGENTS.md (the canonical source of truth for agent instructions), the skills, the agent definitions, docs/CONVENTIONS.md, ADRs, etc. — is Spanish-only. That's a deliberate choice, not an oversight: the project is maintained in Spanish day to day. If you want to work with the template itself, start at AGENTS.md.

---

Español

Plantilla para arrancar proyectos con Claude Code siguiendo el modelo Claude orquestador + Hermes constructor, sobre la metodología de skills de Matt Pocock (workflow enforcement: la IA como participante disciplinado del proceso, no como ejecutor de un solo tiro).

Idea en una frase

En lugar de acumular muchas skills que saturan el contexto, montas un flujo de trabajo con roles claros: Claude dirige, Hermes construye, el auditor cierra.

Estructura

agent-harness-template/
├── .claude/
│   ├── agents/
│   │   ├── orchestrator.md       # Claude: dirige el pipeline
│   │   ├── hermes-builder.md     # Hermes: construye con TDD
│   │   └── security-auditor.md   # cierra el ciclo (aprobación obligatoria)
│   ├── hooks/                    # ENFORCEMENT (bloqueos duros, no sugerencias)
│   │   ├── session-start.sh      #   inyecta contexto al arrancar
│   │   ├── block-secrets.sh      #   bloquea filtrar/commitear secretos
│   │   ├── require-review.sh     #   detecta `git push` y lanza el gate de review
│   │   ├── protect-configs.sh    #   protege ficheros de framework
│   │   ├── enforce-lint.sh       #   ruff (formato + lint) automático
│   │   └── scan-output.sh        #   avisa de patrones tipo secreto
│   ├── reviews/                  # veredictos del auditor (REVIEW-*.md)
│   ├── settings.json             # permisos + hooks
│   └── skills/
│       ├── grilling/             # loop de entrevista reutilizable
│       ├── domain-modeling/      # glosario + ADRs (usada por grill-with-docs)
│       ├── grill-me/             # 1. interroga hasta cerrar ambigüedad
│       ├── grill-with-docs/      # 2. alinea dominio → CONTEXT.md + ADRs
│       ├── prototype/            # (opcional) código desechable para dudas de diseño
│       ├── to-spec/              # 3. spec verificable (+ costuras/seams)
│       ├── to-tickets/           # 4. rebanadas verticales (tracer bullets)
│       ├── implement/            # 5. Hermes con TDD → auditar → review humano → commit
│       ├── tdd/                  # disciplina red-green en las costuras
│       └── retro/                # retrospectivas + métricas desde git
├── .agents/                      # adaptador Hermes (hooks $TOOL_INPUT → lib compartida)
├── .github/workflows/ci.yml      # CI: garantía a nivel de repo (backstop)
├── .github/CODEOWNERS            # quién aprueba cambios a la infraestructura de control
├── scripts/
│   ├── lib/checks.sh             # secretos/protect (agnóstico del motor)
│   ├── lib/scope.sh              # definición ÚNICA del diff auditado (local == CI)
│   ├── require-review.sh         # gate de rama (pre-push): review liga base...HEAD
│   ├── git-hooks/pre-commit      # secretos + lint (por commit)
│   ├── git-hooks/pre-push        # gate de review de rama
│   ├── install-hooks.sh          # instala pre-commit y pre-push
│   ├── check-audit-trail.sh      # CI: exige review APROBADO ligado al diff del PR
│   ├── setup-branch-protection.sh # autoridad: PR + code owner + last-push approval
│   ├── doctor.sh                 # verifica montaje + campos de branch protection
│   ├── verify-agent-harness.sh   # prueba ambos gates
│   ├── verify-hook-adapters.sh   # batería de la capa de sesión
│   ├── bootstrap.sh              # montaje obligatorio de una instancia
│   ├── smoke-test-engine.sh      # E2E por motor en repo temporal
│   ├── smoke-test-all-engines.sh # E2E de todos los motores soportados
│   └── verify-github-flow.sh     # valida una PR real
├── docs/
│   ├── CONTEXT.md                # lenguaje de dominio compartido
│   ├── CONVENTIONS.md            # convenciones + lista negra de seguridad
│   ├── METRICS.md                # ¿funciona el harness? (tally; retro lo llena)
│   ├── SUPPORT.md                # qué garantiza cada motor y cómo se verifica
│   ├── CREDITS.md                # atribución (metodología Matt Pocock, MIT)
│   ├── adr/                      # Architecture Decision Records
│   └── retros/                   # retrospectivas generadas por `retro`
├── AGENTS.md                     # instrucciones canónicas para agentes (estándar abierto)
├── CLAUDE.md                     # puntero a AGENTS.md (Claude Code lo lee nativo)
├── CONTRIBUTING.md               # cómo contribuir (incluye el gate audit-trail)
├── SECURITY.md                   # modelo de amenazas y canal de reporte
├── LICENSE                       # GPL-3.0
├── DEVLOG.md                     # memoria de trabajo del agente (se relee tras resets)
├── HUMAN.md                      # canal de peticiones/feedback del owner
├── TASKS.md                      # log del equipo (humanos)
└── README.md

El pipeline

grill-me → grill-with-docs → [prototype?] → to-spec → to-tickets → implement → audit → review humano

Cada fase produce la entrada de la siguiente. No se salta ninguna (salvo prototype, que es opcional: solo cuando una duda de diseño no se resuelve sobre el papel).

Cómo arrancar un proyecto nuevo

1. Instancia la plantilla y ejecuta el bootstrap obligatorio.

   Vía A (recomendada): botón "Use this template" en GitHub → crea tu repo → clónalo y ejecuta el bootstrap (tolera el .git existente):

   git clone https://github.com/tu-org/mi-proyecto.git && cd mi-proyecto
   sh scripts/bootstrap.sh --owner @tu-usuario --remote https://github.com/tu-org/mi-proyecto.git

   Vía B: clona esta plantilla, descarta su historia y apunta a tu repo vacío:

   git clone <url-de-esta-plantilla> mi-proyecto && cd mi-proyecto && rm -rf .git
   sh scripts/bootstrap.sh --owner @tu-usuario --remote https://github.com/tu-org/mi-proyecto.git

   --remote apunta siempre a tu propio repo (no al de la plantilla). El bootstrap configura CODEOWNERS, remoto, audit.baseRef, commit inicial, hooks, primer push, branch protection y doctor. El trabajo posterior va en ramas feature + PR; main solo se toca por merge con review humano aprobado y CI en verde.

2. Arranca tu motor en esa carpeta (Claude Code, Codex o Hermes). Actuará como orquestador leyendo AGENTS.md. Con Codex/Hermes, ver la tabla de portabilidad en AGENTS.md.

3. Lanza el pipeline: pide al orquestador el objetivo del proyecto. Empezará por grill-me y te interrogará hasta cerrar toda ambigüedad.

4. El flujo avanza solo: grill-with-docs rellena docs/CONTEXT.md y los ADRs, to-spec produce la spec, to-tickets la trocea, implement delega cada ticket en hermes-builder (TDD), y security-auditor aprueba antes de cerrar cada ticket.

5. TASKS.md refleja en todo momento el estado del pipeline y de cada ticket.

Principios

• El owner define QUÉ; el equipo decide CÓMO.
• Pocas skills, afiladas y bajo demanda.
• Nada se cierra sin la aprobación del auditor ni sin el visto bueno humano.
• El dominio vive en docs/CONTEXT.md; las decisiones, en docs/adr/.
• Se prueba en costuras (seams): el límite público más alto, cuantas menos mejor.
• Los tickets son rebanadas verticales: cruzan todas las capas, no una sola.
• Implementar enseña: ante una duda de diseño, un prototype desechable antes de la spec.
• Contexto just-in-time: punteros y carga bajo demanda; el contexto es finito.
• DEVLOG.md es la memoria del agente entre sesiones; docs/METRICS.md dice si el método mejora.

Quality gates: medibles por defecto

Los proyectos nuevos nacen con el toolchain Python ya gated (pineado en requirements-dev.txt, configurado en pyproject.toml): complejidad ciclomática (ruff C901 ≤ 10) y tamaño de función (PLR0915 ≤ 40 statements), ratchet de tamaño de módulos (scripts/check_module_sizes.py, límite 200 con baseline en quality/ que solo encoge), suelo de cobertura (fail_under = 80) y contratos de dirección de imports opcionales (import-linter). bash scripts/verify.sh es el entrypoint único de "hecho = verde" — el CI ejecuta exactamente el mismo script, y cada gate se activa solo en cuanto existen src/ o tests/. La idea (prestada del enfoque de Robert Martin para código escrito por IA): inferir la calidad desde indicadores en vez de leer cada línea generada.

Enforcement: dos capas, honestas sobre lo que garantizan

Las skills piden buen comportamiento. Que se cumpla se sostiene en dos capas — y conviene ser claro sobre qué asegura cada una:

1. Disciplina local (git hooks + adaptadores por motor) — sh scripts/install-hooks.sh instala pre-commit (secretos con gitleaks + lint) y pre-push (gate de review de rama: no empujas código sin un REVIEW APROBADO ligado al hash del diff base...HEAD; parser estricto — NO APROBADO, ticket sin dígito o hash ajeno no cuelan). Atajan la deriva. No son autoridad: bajo agente cooperativo la IA puede escribir su review.

2. AUTORIDAD — PR + branch protection + CODEOWNERS (scripts/setup-branch-protection.sh) — lo que rompe la autoaprobación. main exige el review de un code owner (.github/CODEOWNERS), require_last_push_approval y los checks de CI. La IA escribe el REVIEW pero no puede aprobar el PR: la aprobación es una identidad concreta e independiente. (GitHub además impide, sin excepción, que el autor de una PR apruebe su propia PR — una regla dura de la plataforma, no un ajuste de este repo.)

3. Garantía de repo (.github/workflows/ci.yml) — job quality (ruff, mypy, bandit, pytest, gitleaks, verify-agent-harness.sh) + job audit-trail que exige un review versionado APROBADO ligado al diff del PR. Gate local y CI usan la misma lib (scripts/lib/scope.sh), así certifican el mismo objeto. sh scripts/doctor.sh verifica el montaje y los campos de la protección.

Probado: verify-agent-harness.sh ejerce la batería completa sobre ambos gates (local y CI) — review falso, NO APROBADO, ticket sin dígito, multi-commit agregado, base rota, review copiado — y falla si alguno cuela. Honestamente: harness cooperativo spec-driven con autoridad en el PR y backstop en CI — no "imposible de saltar" en local, pero sí una cadena de aprobación verificable en el merge. El modelo de amenazas completo y el canal de reporte están en SECURITY.md; cómo pasar el gate en una PR, en CONTRIBUTING.md.

El mismo patrón a nivel de modelo (API)

En Claude Code, orquestador y constructor son subagentes con modelo fijado (ver ADR-0003). Cuando el flujo se ejecuta contra la API en crudo, el mismo patrón "dirige / construye" existe a nivel de modelo con el advisor tool de Anthropic: un executor rápido (constructor → Sonnet/Haiku) que consulta a mitad de generación a un advisor más inteligente (orquestador → solo Opus 4.8 o 4.7; el advisor tool rechaza cualquier otro modelo, incluido Fable, con un 400). Ver docs/adr/0002-advisor-tool-mapping.md.

Licencia

Copyright © 2026 prgr1no y contribuidores.

Este proyecto se distribuye bajo GPL-3.0 (LICENSE). Incluye material adaptado de mattpocock/skills (MIT, compatible con GPL-3.0; el aviso original se conserva en docs/CREDITS.md).

Ten en cuenta que al instanciar la plantilla, los ficheros del harness copiados a tu proyecto (scripts, hooks, skills, docs del framework) siguen siendo GPL-3.0: si distribuyes tu proyecto, esas partes conservan la licencia y sus obligaciones. El código propio que escribas sobre la plantilla es tuyo y lo licencias tú.

Créditos

La metodología de las skills está adaptada de mattpocock/skills (MIT). Detalle y texto de licencia en docs/CREDITS.md.