8 · Capstone — Drive a Real Change End-to-End¶

Each module so far taught one lever in isolation. The open question is whether those levers work together on real work, where no one tells you which to reach for and the task is one you actually care about finishing. The capstone answers that question. It asks you to drive a real, non-trivial change to completion on a codebase you own, using every lever from Modules 0–7. On the Practice Repo, the capstone uses the built Modules 0–4 loop; Modules 5–7 are applied on your own codebase until those Practice Repo slices land.

There are no new concepts here. The capstone is where context, specification, verification, extension, orchestration, compounding, and judgment come together on work that matters to you. The Practice Repo gives a fixed rehearsal; your own codebase is the full test.

The bar is not that the agent wrote code. The bar is that you operated the agent like a tech lead: scoped context, a real spec, machinery that verified the result, and a clear-eyed call on whether it was worth it.

The brief¶

Pick a real change in a repo you own — big enough to need a plan, small enough to finish in a sitting. Good candidates: a feature with clear acceptance criteria, a refactor across several files, or a bug you can write a failing test for. Avoid anything on the never-delegate line (Module 3.3); the capstone is about operating well, not about taking a risk you would never take at work.

Then run it through the full loop, naming the lever at each step:

Scope the context (Module 1). Write or sharpen the CLAUDE.md so the agent opens the right files on its own.
Write a spec (Module 2). Acceptance criteria, steps, constraints. Get a plan and approve it before any edit.
Verify with machinery (Module 3). A test or eval the agent self-corrects against; a guardrail on anything irreversible.
Shape the harness (Module 4). Add tools, permissions, and skills only where the task repeatedly demands them, and name the check that keeps the broader harness safe.
Parallelize the divisible parts (Module 5). If the work splits into isolated slices, run them in parallel and integrate.
Keep the artifact (Module 6). Leave the repo with a sharper CLAUDE.md, a spec, a gate, or a skill.
Judge it honestly (Module 7). Record what the agent cost and whether it beat doing the work yourself.

Track the north-star metric as you go: how long did the agent run before it needed you? A higher number than your Module 0 baseline is the quantified proof you have learned to operate.

Rubric¶

Grade yourself against the change and what it left behind. A capstone that ships code but leaves nothing reusable has met only half the goal: the curriculum is as much about the artifacts a session leaves behind as about the change itself.

[ ] Scoped the context deliberately (Module 1)
[ ] Wrote a real spec with acceptance criteria (Module 2)
[ ] Verified with machinery, not by reading every line (Module 3)
[ ] Shaped the harness only where it earned its place (Module 4)
[ ] Parallelized only the divisible, isolated parts (Module 5)
[ ] Left behind a reusable artifact (Module 6)
[ ] Judged honestly whether the agent was worth it (Module 7)

The through-line of this course is one question: how long can the agent run before it needs you? The capstone is where you measure it on real work. Each lever you scoped — the context, the spec, the verification loop, the gate — is a stretch of runway the agent covers without stopping for you.

Guided Lab¶

The Practice-Repo capstone runs one fixed change through the whole built loop, naming each lever as you reach for it. The change is the seeded billing bug: billing tickets are mislabeled general, and a red test already encodes the behavior you need to make true. You will scope the context (Module 1), let the red test stand as the spec (Module 2), drive the self-correcting loop (Module 3), gate the fix so it cannot regress (Module 3), and capture the workflow as a reusable skill in the harness (Module 4). Every lever here is one the course already built; the Module 5–7 slices are not required to finish.

On the Practice Repo, work through the following.

Clone Triage, build the offline venv, and confirm the failure is real from a cold start:
```
git clone https://github.com/mrfelixwong/agentic-engineering-triage triage && cd triage
python3 -m venv .venv && .venv/bin/pip install -e . && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -q
```
Expected: one test fails — test_billing_ticket_is_labeled_billing (two parametrized cases) — and the rest pass. Confirm there is no top-level instruction file yet (ls CLAUDE.md → No such file or directory). The cold repo and the red test are your starting point.

Scope the context (Module 1). Write CLAUDE.md at the repo root so a fresh agent opens the right files on its own. Create it with a "where things live" map, one landmine, and a verify step:

# CLAUDE.md — Triage

A support-ticket assistant: classify a ticket into one category. Read this,
then the file it points you to — don't grep the tree.

## Where things live (start here)
- Classification + the routing seam → `app/triage/classify.py`
- Wording the model sees → `app/llm/prompts.py`
- Models / providers → `app/llm/client.py`
- Tests → `tests/`; eval → `eval/run.py` (`python -m eval.run`)

## Non-obvious rules (the landmines)
- The LLM layer returns a bare category string; the mapping to the `Category`
  enum happens in `classify.py`'s `_ALIASES`, not in the provider wrapper. A
  wrong rule there silently mislabels a whole category.

## Verify your work
- `.venv/bin/pytest -q` must pass; `.venv/bin/python -m eval.run` must hold
  its 0.80 baseline (exit 0).

Expected: CLAUDE.md exists at the repo root (ls CLAUDE.md now succeeds). The agent that reads it can navigate to the routing seam without scanning the tree.

Let the red test be the spec (Module 2). You do not need to invent acceptance criteria here — the failing test already states them. Open tests/test_classify.py and read only the RED case.

Expected: you can state the behavior it demands (a billing ticket must be labeled billing) and what the app does instead (general), without yet knowing why. That red test is the spec the agent will drive against.
Run the self-correcting loop (Module 3). Start the agent in the repo root and hand it the failing test as the goal — keep it honest, it must not edit the test to pass:
```
claude
```
.venv/bin/pytest -q has a failing test in tests/test_classify.py. Investigate the root cause in the app/ code, fix it, and re-run the tests until they pass. Don't edit the test — find why the behavior is wrong and fix the behavior.

Expected: with your CLAUDE.md in place, the agent opens app/triage/classify.py directly, traces the wrong label to the _ALIASES map (one entry folds billing into general), fixes that single line, and re-runs pytest itself until green. You inspected the loop the agent ran rather than the diff it produced.
Verify with both checks yourself (Module 3) — don't trust the agent's say-so. Start a clean session first so the loop's residue is gone:
```
/clear
```
```
.venv/bin/pytest -q
.venv/bin/python -m eval.run
```
Expected: pytest all green; the eval reports 10/10 = 1.00 and exits 0. Before the fix the eval read 7/10 = 0.70, below its committed 0.80 baseline — the three billing cases (E-01, E-02, E-03) were the misses.
Gate the fix so it cannot regress (Module 3). Install the pre-commit hook, then prove it fires:
```
ln -sf ../../scripts/pre-commit .git/hooks/pre-commit
```
Flip the one _ALIASES line you fixed back to its buggy value, stage it, and try to commit.

Expected: the hook runs pytest and the eval, the checks fail, and git refuses the commit. Restore the fix and commit cleanly. The repo caught the regression without you watching.
Shape the harness with a skill (Module 4). You ran the same verify sequence by hand twice — pytest then python -m eval.run, checking the baseline held. That repetition is the signal to capture it. Ask the agent to write a small skill that runs both checks and reports whether the baseline held, then confirm it runs:

Create a project skill at .claude/skills/verify-triage/SKILL.md that runs .venv/bin/pytest -q then .venv/bin/python -m eval.run and reports whether both passed and the eval held its 0.80 baseline.

Expected: the skill file exists at .claude/skills/verify-triage/SKILL.md and, when invoked, runs both checks and reports a clean pass. Adding it only after you felt the repetition is the Module 4 discipline: the harness grows when a repeated workflow earns its place.
Judge it (Module 7, method only). Note how many turns the agent ran before it needed you in step 4, and whether the loop plus the gate left the repo able to catch this class of bug on its own. That turn count, against a cold run with no CLAUDE.md, is the quantified proof the levers compounded.

▶ Coached mode

The verification leg of this capstone can be walked live. The /lesson-3-1-verification instructor skill (it ships in practice-repo/triage/.claude/skills/lesson-3-1-verification/) coaches the red-test → loop → gate sequence from a second terminal — it watches your session, stops at each checkpoint, and asks a leading question before handing you the next move. It never names the bug or edits your repository for you.

On your own codebase, run the same loop on a change you actually care about finishing. Pick one big enough to need a plan and small enough to finish in a sitting — a feature with clear acceptance criteria, a refactor across a few files, or a bug you can pin with a failing test. Scope the context in a CLAUDE.md, write the spec (if the change is a new feature, acceptance criteria replace the ready-made red test), drive the self-correcting loop, gate the result, and add a skill only where you felt a workflow repeat. Stay off the never-delegate line (Module 3.3); the capstone is about operating well on work you would do anyway.

Keep the artifact¶

The capstone leaves the repo sharper than it found it. On the Practice Repo that is a CLAUDE.md that points the next agent at the routing seam, a pre-commit gate that refuses the billing regression automatically, and a verify-triage skill that runs both checks on demand. None of these is a worksheet to throw away; each ships in the repository and earns its keep on every future session. On your own codebase the same holds: commit the instruction file, the gate, and any skill you wrote, and the next change starts from a higher floor. That a session leaves the repo better tooled than it found it is compounding (Module 6) — the capstone is its first full instance.

Self-check¶

You did it right if, on the Practice Repo:

a fresh agent reading your CLAUDE.md opened app/triage/classify.py without you naming the path;
the seeded bug was caught by the existing red test and driven green through a loop the agent ran itself, not by you reading the diff;
.venv/bin/python -m eval.run exits 0 at 10/10; and
the pre-commit gate refuses the bug when you reintroduce it, without you remembering to check.

If you found the bug by reading code, or had to remember to run the check, you operated by hand instead of by machinery — push each step up a rung until the repo does the watching for you.

Recall¶

The final question: could you now teach the operator's loop to a teammate — scope the context, write the spec, verify with machinery, gate the result — and name the call on when not to reach for the agent?

Answer

Yes if you drove the capstone end-to-end — a CLAUDE.md that scoped the context, a spec the agent built against, a self-correcting loop the agent ran, and a gate that made the check unskippable — and can say where the never-delegate line falls. The levers are the lesson; the artifacts they leave behind are the proof.