Agent Trainer Harness

File-first multi-agent harness for AI-assisted product delivery. Framework-agnostic — works with Claude Code, Cursor, Copilot, or any AI IDE. This is the reusable public harness/template repo.

Pick Your Mode

Question	Lite	Full	Concurrent
Scope	1-2 phases, single concern	3+ phases, multi-role delivery	Large parallel build
Autonomy	Human-in-the-loop	Human-in-the-loop or autonomous	Fully autonomous
Roles	3 (Orchestrator, Engineer, QA)	10 (PM, Designer, Engineers, QA, Docs, Growth, SME)	10 + parallel workers
Gates	Informal	Formal gate log in STATUS.md	LLM-judged gates
When	Bug fixes, scripts, small features	MVPs, SaaS products, multi-week builds	Week-long autonomous builds

Quick Start

All harness modes now use the same core control-doc contract: BRIEF.md defines the project, ROADMAP.md captures product sequencing and milestones, STATUS.md tracks tactical current state, and DECISIONS.md records non-trivial rationale. STATUS.md uses the canonical header: State, Current Phase, Last Updated, Current Gate, Next Step, Review Cadence, and Re-entry Condition (required for Monitor / Parked, otherwise N/A). Agents are expected to preserve that header on every update.

Each copied harness carries a machine-readable .harness-version file; use dotfile-safe copy commands such as cp -a <template>/. <repo>/ so the stamp is preserved. This is the version/drift anchor for read-only reporting; it is not an auto-upgrade mechanism. Run scripts/harness_drift_report.py (read-only) to compare vendored project copies against the canonical templates — it reports version delta, managed-file divergence, root control-doc migration state, and project-specific section flags without modifying anything.

Concurrent mode is currently parked / opt-in. Keep its validators passing, but do not invest in Concurrent propagation or refactors unless a project explicitly chooses that mode or a dedicated dogfood run is scheduled.

New Project

1. Pick your mode from the table above.
2. Copy the contents of that mode's new-project/ folder into your empty repo.
3. Open start.md and follow the instructions.
4. If your project uses uv, prefer plain uv run ... or explicit repo-local .venv/bin/... commands; avoid uv run --active ... / uv --active run ... unless you deliberately want the caller's active virtualenv.

# Example: start a new full-mode project
cp -a full/new-project/. /path/to/your/new/repo/
cd /path/to/your/new/repo
# Open start.md and follow instructions

Existing Project

1. Pick your mode from the table above.
2. Copy the contents of that mode's existing-project/ folder into your repo.
3. Open start.md — it will guide you through an audit-first onboarding:
   • Audit what exists in your project
   • Classify as well-structured / partial / bare
   • Add only what helps — never overwrite good existing docs
   • Validate with one cycle

# Example: add full-mode harness to existing repo
cp -a full/existing-project/. /path/to/your/existing/repo/
cd /path/to/your/existing/repo
# Open start.md and follow the audit-first flow

Graduation Path

Projects naturally grow. The harness supports upgrading between modes:

Lite ──────> Full ──────> Concurrent
  │                          ▲
  └──────────────────────────┘

• Lite -> Full: Add gate log, handoffs, full role library, evaluation criteria, skills library.
• Lite -> Concurrent: First upgrade to Full, then add runtime/ and cli/.
• Full -> Concurrent: Add runtime/, cli/, configure config.yaml, run preflight.

Each existing-project start.md includes a detailed graduation guide.

CLAUDE.md Integration

If you use Claude Code with a global ~/.claude/CLAUDE.md config, add this trigger:

If AGENTS.md exists in the project root, read it first and follow harness instructions. The harness defines what to work on (phases, gates, files). Your CLAUDE.md defines how to work (behavior, delegation, verification). Both apply.

Folder Structure

agent-trainer/
├── README.md         ← you are here
├── LICENSE
├── lite/
│   ├── new-project/      copy into empty repo
│   └── existing-project/ audit-first onboarding
├── full/
│   ├── new-project/      copy into empty repo
│   └── existing-project/ audit-first onboarding
├── concurrent/
│   ├── new-project/      copy into empty repo
│   └── existing-project/ audit-first onboarding
└── reference/
    └── architecture-spec.md  (frozen original vision)

Design Principles

• AGENTS.md as map, not manual: Each mode's AGENTS.md is ~30-60 lines. It tells the agent what to read first and where to find everything else. Detailed rules live in the files they govern.
• Three-zone model: Files are labeled as System (never delete), State (update as you work), or App (your workspace). Agents know what to touch and what to protect.
• Audit-first onboarding: Existing projects are never blindly overwritten. The agent audits what exists, classifies the project, and adds only what improves outcomes.
• Proportionality is the mode: Pick lite for small work, full for features, concurrent for big builds. No need for complex per-mode proportionality rules.
• Roadmap/status split: ROADMAP.md captures product sequencing and deferred scope; STATUS.md stays tactical.
• Additive phase summaries: Phase snapshots include "Carried Constraints" to prevent context collapse in long sessions.
• Mechanical enforcement: repo-level tests enforce the shared template contract; Concurrent mode also ships cli/validate_harness.py for project-local consistency checks. Gate enforcement is structural, not advisory.
• Runtime truth over stale artifacts: For deployment/live-run work, verify the actual runtime before calling status decision-grade; mark superseded deploy/config sections as historical. If multi-agent work is needed, propose the split explicitly rather than drifting into overlap.

Readings and Influences

This harness was shaped by hands-on trial and error across multiple real projects, combined with ideas from:

• Harness Engineering (OpenAI, Feb 2026) — AGENTS.md as navigational map, progressive context disclosure, garbage collection agents
• Exploring Gen AI: Harness Engineering (Martin Fowler / Thoughtworks) — harnesses as future service templates, retrofitting challenges
• AGENTS.md Standard and Best Practices — file structure, discovery hierarchy, size guidelines
• Agentic Context Engineering (ACE) (Microsoft Research) — context collapse prevention, additive checkpoints
• Agent READMEs: An Empirical Study — analysis of 2,303 context files, what works and what doesn't
• 0xHoneyJar Loa Framework — three-zone model (System/State/App), lossless ledger protocol
• Multi-Agent Orchestration Patterns — handoff validation, hierarchical supervision, failure isolation
• Agentic Coding Handbook (Tweag) — spec-first development, proportionality
• claude-mem — automatic session memory with progressive disclosure, semantic compression
• qmd — local hybrid search (BM25 + vector + re-ranking) over markdown knowledge bases

Verification

Run the harness checks from the repo root:

python3 -m unittest discover -s tests -v
python3 concurrent/new-project/cli/validate_harness.py --project concurrent/new-project
python3 concurrent/existing-project/cli/validate_harness.py --project concurrent/existing-project
git diff --check

Root-level python3 -m unittest discover -v is also expected to discover the same tests.

License

MIT — see LICENSE.