Building an AI Agent Harness From Scratch: AGENTS.md, feature_list.json, verify.sh and an Autonomous Loop

We've spent twelve lectures building the harness piece by piece. Does it actually work as one system?

• AGENTS.md, feature_list., PROGRESS.md, the sprint contract and graph.md were written in different weeks
• Each artefact was verified on its own — never checked for clashes with its neighbours
• Today brings the only test that matters: does the system work when assembled?

Here's the question that's easy never to ask until the very last day of the course: if instructions, state, verification and the feature contract were each written one component at a time, what guarantee is there that they don't contradict one another inside a single repository? The WIP=1 rule from feature_list. can quietly clash with parallel nodes in the role graph. The Definition of Done might demand a step whose script no longer exists. Today we add nothing new — we take the five subsystems of the payments backend we've already written and switch the harness on as a whole, once, to see whether the structure holds.

This is what the repository looks like once the harness is finally finished

• Top level: AGENTS.md, PROGRESS.md, DECISIONS.md, program.md, graph.md
• .agent/: feature_list., session-handoff.md, clean-state-checklist.md, quality.md
• scripts/: verify.sh, arch-check.sh, init.sh, cleanup.sh — gates, not suggestions
• Next we go through each file and see what it actually does in the assembled whole

This is what the root of the payments backend looks like if you open it today rather than in week one of the course. Eleven files and one utility directory — and not a single one of them is there to tick a box: each closes a specific layer of failure we worked through along the way. We'll go through each in turn — first the instructions and the Definition of Done, then the feature list and the verification gate, then cross-session continuity, the architectural rule, the sprint contract, the autonomous loop and the role graph. And at the end — not a story, but figures: what changed in MTTR, the verification gap and the cost of recovery on the very same project.

AGENTS.md isn't a tips file — it's an 80-line router

• The top level answers only three questions: what it is, how to run it, how to verify it
• Everything specific belongs in docs/*, not in the router itself
• Every link to a documentation section carries a 'when' condition, never just a path
• Fewer than 100 lines — otherwise the router starts degrading for the same reasons as any other instructions file

The first thing an agent sees when it opens the repository isn't a thousand lines of instructions but a short router that sends it off in the right direction. Look at what AGENTS.md for the payments backend had become by the end of the course: it contains no topic in full — only commands, hard constraints and conditional links into docs/api-patterns.md, docs/db-rules.md and docs/testing.md. A condition such as 'read before changing models' beats a bare path — the agent sees not just a file but a reason to open it.

## Router: what / how to run / how to verify
- Stack: FastAPI + PostgreSQL + Stripe webhooks.
- Run: `make setup && make dev`. Verify: `make check`.

## Details — read on condition, not everything up front
- `docs/api-patterns.md` — required before adding any endpoint
- `docs/db-rules.md` — required before changing models or migrations
- `docs/payments.md` — required before changing payment logic or webhooks
- `docs/testing.md` — when writing new tests