Product Intent

Product Intent

What agentic-harness is, who it's for, and the shape of the problem it's trying to solve. Written to answer "why does this repo exist" in under five minutes — deeper reasoning lives in harness/principles.md and the ADRs.

⚡ Quick Reference

Question	Answer
What is it?	A phase-gated workflow + state layout that any AI coding agent (Claude Code, Antigravity, Codex, Gemini CLI) can follow.
Who's it for?	A developer who wants agents to do production-quality engineering, not a demo.
How big is it?	Six phase commands, two sub-agents, one skill (ship-release). Small on purpose.
How does it get into a project?	One command — install.sh /path/to/project. See Install-Into-Project.
Why this shape?	See the six principles below, or harness/principles.md.

The problem

A modern coding agent can produce a working feature in a single long conversation. What it usually can't do in a single long conversation:

• Stop at the right time (before scope creeps).
• Run deterministic gates before declaring success.
• Leave a successor enough state to pick up cleanly.
• Review its own work adversarially instead of rubber-stamping.
• Keep the docs honest once the code ships.

These are all scaffolding problems, not model problems. They don't get better with a bigger model; they get better with better scaffolding. agentic-harness is that scaffolding.

The shape

Six phases with hard boundaries. Each phase has one job.

Phase	Job	Ends with
/setup	First-time scaffold, feature list, init.sh.	Directory layout + .harness/PLAN.md stub.
/plan	Turn a brief into tasks with verification criteria. No code.	.harness/PLAN.md with tasks.
/work	Implement exactly one task; run gates; commit.	One task [x]; progress.md line appended.
/review	Adversarial critique — must produce a failing test or line-number defect.	Executable artifact, not prose.
/release	Pre-merge gate: clean tree, full test suite, feature flags flipped truthfully.	Verified-ready state; no push.
/bugfix	Report → Analyze → Fix → Verify pipeline for bugs (replaces /plan + /work).	Fix committed with regression test.

A separate skill, ship-release, cuts a tagged GitHub release after /release passes — semver sized from conventional-commit prefixes in the range since the last tag.

Target user

Someone who:

• Pays per-token and per-minute — values minimal ceremony, doesn't want a 150-agent supermarket.
• Wants the same workflow across Claude Code, Antigravity, Codex, and Gemini CLI so their muscle memory travels.
• Thinks tests and typecheckers are the truth and LLM reviews are augmentation.
• Is willing to invest five minutes at the end of each feature to keep the docs honest, in exchange for not having to re-derive the system later.

The six principles (short form)

Full text: harness/principles.md.

1. Phase-gated workflow over free-form conversation. Each session does one thing. Fresh context at boundaries beats compaction.
2. State lives on disk, not in context. .harness/PLAN.md, features.json, progress.md. Next session starts by reading.
3. Single-threaded for coherence; fan-out only for read-only breadth. Parallel implementers produce inconsistent decisions. Parallel readers are fine.
4. Deterministic verification before LLM judgment. Typecheck → lint → test → build, then optional critic. A review that skips gates is not a review.
5. Adversarial review with "assume bugs" framing. The reviewer must produce an executable artifact, not prose. Neutral reviewers rubber-stamp.
6. Re-audit the harness on every model bump. Scaffolding that was load-bearing last quarter often isn't anymore.

Non-goals

• A one-shot "build me a feature" agent. The harness refuses to do plan+implement+review in a single session.
• A supermarket of agents. Two sub-agents (explorer, adversarial-reviewer) + one skill (ship-release). Adding more costs coherence.
• Replacing tests or code review. Deterministic gates come first; LLMs augment.
• Dynamic-doc generation from code. Docs are human-edited narrative, updated by the documenter sub-agent at phase boundaries only. See ADR 0002.
• Universality across every tool. The harness targets tools that read AGENTS.md. Tools without an adapter file tree need one written per Repo-Layout.

Related

• How-The-Pieces-Fit — narrative of how phases, adapters, templates, and scripts interact.
• Repo-Layout — on-disk map of the four-adapter shape.
• Install-Into-Project — install the harness into a project.
• Cut-A-Release — cut a tagged release via ship-release.
• ADR 0001 — why phase gates.
• ADR 0002 — why wiki + phase-boundary docs + installer boundary.