ai-workflow-course/capstone/README.md

Capstone — The Full Loop

One feature, taken end to end, with every module doing its job in sequence. This is the finale: not new material, but proof that the twenty-seven pieces you learned separately are actually one motion. By the end you'll have shipped a real change to tasks-app — prompt to running container — and felt the thing the whole course was for: the model did the typing, but the workflow is what made it safe and repeatable.

---

This is a finale, not a module

There's nothing to learn here that the modules didn't already teach. The capstone exists to wire it together. Every step below names the module it comes from, so you can see the dependency chain you climbed now collapse into a single fluent pass. If a step feels unfamiliar, that's a pointer back to the module to re-read — not new content to absorb.

You'll do it twice:

1. The main loop — you driving, the AI assisting. The full pipeline, by hand, once.
2. The stretch variant (optional) — the same feature run the Unit 5 way, with agents inside the pipeline, so you watch the workflow start to run itself.

---

Prerequisites

All of it. Concretely, you need the tasks-app repo in the state the course left it:

• A Git repo (Module 2) with a committed AI instructions file at the root (Module 5), a remote on your forge (Module 8), and a protected main that requires a PR to merge (Module 11).
• test_tasks.py and a green test suite (Module 13).
• A CI workflow that lints and tests on every push and PR (Module 14), with a security-scan step wired in (Module 15), running on a runner you understand (Module 19).
• A Dockerfile and .dockerignore (Module 16), serve.py exposing /health and /tasks (Module 18), .env/.env.example for config (Module 17), and a deploy.sh that tags by commit SHA, injects env, health-checks, and rolls back (Module 18).

If any of those is missing, build it from its module first. The capstone assumes the machine is already standing; it doesn't re-pour the foundation.

---

The feature we're shipping

Pick something small enough to finish in one sitting and real enough to touch the whole stack. We'll add due dates:

• A task can carry an optional due date: python cli.py add "file taxes" --due <YYYY-MM-DD>.
• A new overdue command lists pending tasks whose due date has already passed.
• The deployed service grows a matching GET /overdue endpoint, so the change is visible in the running container, not just the CLI.

This deliberately spans the core (tasks.py), the CLI (cli.py), and the deployable service (serve.py) — one feature, three surfaces, exactly the kind of change that used to mean three copy-paste sessions and a prayer (Module 1). And it has a built-in trap for the review step: "is a task due today overdue?" is the kind of off-by-one an AI will answer confidently and wrongly.

---

The loop, step by step

Read this once as a map before you touch the keyboard. Each arrow is a module.

Prompt → issue (M9). Don't start in your editor. Start with the work written down. File an issue: "Add optional due dates to tasks, an overdue command, and a /overdue endpoint." Acceptance criteria in the body. Label it. The issue is the contract the rest of the loop closes against.

Issue → branch (M6/M11). Never work on main. Branch named after the issue: git switch -c 47-due-dates. The branch is a sandbox you can throw away wholesale (M6) — which is the only reason letting the AI loose on three files at once is a calm decision instead of a gamble.

Branch → AI implementation (M4), config already in place (M5). Now the AI edits the files directly in your editor or CLI — no browser, no paste. It already knows your conventions because the committed instructions file has been in the repo since the first commit (M5): core logic in tasks.py, CLI wiring in cli.py, standard library only, run the tests before claiming done. You didn't re-explain any of that. That's the file earning its keep.

Implementation → tests (M13). The feature isn't done when it runs; it's done when it's pinned. Have the AI extend test_tasks.py with cases for the new logic — and write the boundary cases yourself or demand them by name, because the boundary is exactly where the AI guesses: due yesterday (overdue), due tomorrow (not), due today (not — yet), no due date at all (never overdue, never crashes).

Secrets stay clean (M17). This feature needs no new secret — it reads the system clock. The discipline is that nothing got hardcoded anyway: the service still reads its config from the environment via .env, and .env.example documents any new keys. The win here is a non-event, which is the point — the failure mode (M17: AI hardcodes a value) simply didn't happen, because the pattern was already there.

Tests → PR (M10/M11). Push the branch, open a PR, and put Closes #47 in the description so the merge closes the issue automatically (M11). The PR is the review gate even though it's your own code — especially because an AI wrote most of it.

PR → CI → security scan (M14/M15/M19). Opening the PR triggers the pipeline on your runner (M19): lint, build, tests (M14), then the security gate (M15) — dependency audit, secret scan, SAST. The feature added no dependencies, so SCA should be quiet; the secret scan confirms you didn't smuggle a key into a fixture. CI is the tireless reviewer that catches the code that looks right (M14); the security scan catches the failure classes a build check never would (M15).

Review (M10). Green CI is necessary, not sufficient. Read the diff like you didn't write it (M10). Go straight for the plausibility trap: open overdue() and check the comparison. Did it use < or <=? Does a task due today show up as overdue? Does a task with no due date crash the comparison or get silently treated as overdue? This is the single least-automatable skill in the course, and the capstone is where you prove you have it.

Merge (M11). Once CI is green and the diff is honest, squash-merge. Issue #47 closes itself. main is now ahead by one clean, tested, scanned commit.

Merge → containerized deploy (M16/M18). The merge to main triggers delivery (M18): CI builds the image from your Dockerfile (M16), tags it with the new commit SHA (immutable, not latest), runs deploy.sh to start the container with env injected (M17), polls /health, and — if health fails — rolls back to the previous SHA. Hit GET /overdue on the running container. The feature is live, in a reproducible artifact, behind a health check that can undo itself.

If it goes wrong (M12). Something slips past every gate eventually. Because you squash-merged (one commit on main, not a two-parent merge), a bad change reverts cleanly with plain git revert <squash-sha> — a new commit, safe on shared history, no rewriting what teammates pulled (M12). Skip the -m 1 you saw in Module 12: that flag is only for true merge commits, the kind git merge --no-ff makes, and a squash merge isn't one. A bad deploy is already handled by deploy.sh's rollback to the last good SHA. Recovery is a discipline you rehearsed, not a panic.

That's the whole motion. Notice what carried it: not the model. The model wrote the diff; the workflow is everything that made the diff safe to merge and trivial to undo. Swap the model next quarter and every arrow above is unchanged. That's the Module 1 thesis — the model is the cheap, swappable part; the workflow is the durable skill — now demonstrated rather than asserted.

---

Hands-on lab

Lab language: shell + Python, on the tasks-app repo. You'll use your editor-integrated or CLI agent (M4) for the implementation; everything else is your normal toolchain.

You'll need: the tasks-app repo in the prerequisite state above, your agentic tool, your forge account, and a working Docker install.

Part A — Issue and branch (M9, M6, M11)

1. File the issue on your forge. Title: "Task due dates + overdue command + /overdue endpoint." In the body, write the acceptance criteria as you'd hand them to a contributor you don't trust to guess:

   • add takes an optional --due YYYY-MM-DD.
   • overdue lists pending tasks with a due date strictly before today.
   • A task due today is not overdue. A task with no due date is never overdue.
   • serve.py exposes GET /overdue returning the same set as the CLI.

2. Branch off main, named for the issue:

   cd ~/ai-workflow-course/tasks-app
   git switch main && git pull
   git switch -c 47-due-dates        # use your real issue number
   

Part B — Implement with the AI (M4, M5)

3. In your editor/CLI agent, give it the issue, not a vague wish:

   "Implement issue #47. Add an optional due date to tasks (core in tasks.py), wire --due into the add command and a new overdue command in cli.py, and add a GET /overdue endpoint to serve.py. Follow the acceptance criteria exactly. Run the tests before you tell me it's done."

   You should not have to specify "stdlib only" or "don't touch tasks.json" — that's in the committed instructions file (M5). If the agent reaches for a date library or hand-edits the JSON, your file needs a line; that's signal, not failure.

4. Run it by hand to confirm it's real. Choose the two dates relative to your today — one comfortably in the future, one safely in the past — so the assertion below holds whenever you run this:

   python cli.py add "file taxes" --due <a date a few months out>   # future → NOT overdue
   python cli.py add "renew domain" --due 2020-01-01                # past   → overdue
   python cli.py overdue        # should list "renew domain", not "file taxes"
   

   Verify-before-publish: refresh the example due dates so the "future" one is still in the future at publish time — a hardcoded near-future date silently inverts this assertion once it passes.

Part C — Tests (M13)

5. Have the AI extend test_tasks.py, then read the test names and confirm the boundaries are actually covered. If "due today" and "no due date" aren't each their own test, add them — by hand or by demanding them. Run the suite:

   pytest        # or: python -m unittest
   

   Commit only when it's green:

   git add -A && git commit -m "Add task due dates, overdue command, and /overdue endpoint"
   

Part D — PR, CI, security, review (M10, M11, M14, M15, M19)

6. Push and open the PR with the closing keyword:

   git push -u origin 47-due-dates
   # open the PR on your forge; put "Closes #47" in the description
   

7. Watch the pipeline run on your runner (M19): lint + tests (M14), then the security scan (M15). Don't proceed until it's green.

8. Review the diff as if a stranger wrote it (M10). Open overdue() and answer, from the code:

   • Is the comparison strict (< today) or inclusive (<=)? A task due today must not appear.
   • What happens for a task with due == None? It must be skipped, not crash, not counted.

   If either is wrong — and an AI gets at least one of these wrong more often than you'd like — request the fix on the branch, let CI re-run, and review again. Catching this here, before merge, is the entire point of the gate.

Part E — Merge and deploy (M11, M16, M18, M17)

9. With CI green and the diff honest, squash-merge. Issue #47 closes itself.

10. Let delivery run, or run it locally if that's your setup (M18):

    ./deploy.sh           # builds image tagged by commit SHA, injects env, health-checks, can roll back
    curl localhost:8000/overdue
    

    You should see your overdue task served from the running container — the feature live in a reproducible artifact (M16), configured from the environment (M17), behind a self-rolling-back health check (M18).

Part F — Rehearse recovery (M12)

11. Sync local main first. The squash-merge in step 9 happened on the forge, so the new commit lives only on the remote — your local main is one behind. Pull it down and capture the SHA of the squash commit you're about to rehearse undoing:

    git switch main && git pull      # bring the squash-merge commit into local main
    git log --oneline -1             # the top line IS your squash commit — note its SHA
    

12. Prove you can undo it. Cut a throwaway branch off the freshly-synced main and revert that squash commit, just to watch it work, then delete the branch:

    git switch -c throwaway-revert-test
    git revert <squash-sha>     # plain revert: a squash merge is one ordinary commit, so no -m 1
    pytest && git switch main && git branch -D throwaway-revert-test
    

    No -m 1 here, and nothing to "find": that flag is only for the two-parent merge commits Module 12 rehearsed with git merge --no-ff. A squash merge produces a single-parent commit, so plain git revert <squash-sha> is the right undo. You just confirmed the escape hatch is real before you ever need it in anger.

---

Stretch variant — run the same feature the Unit 5 way (optional)

Everything above had you in the driver's seat. Now run the identical feature with agents inside the pipeline and watch how much of the loop keeps running when you step back. Do this only after the main loop succeeded — you can't supervise a pipeline you haven't run by hand.

The feature, the branch flow, the gates, and the deploy are unchanged. What changes is who does each step:

1. Issue-to-PR agent does the first pass (M25). Assign the issue to an autonomous agent instead of opening your editor. It reads issue #47, creates the branch, implements across tasks.py, cli.py, and serve.py, writes tests, and opens the PR — all landing as a reviewable PR behind CI, exactly like a human contributor's. It is allowed to propose, never to merge. The supervision is structural: the same CI (M14) and security (M15) gates stand whether the author is a human or an agent.

2. An assistive reviewer comments first (M24). Before you look, an AI reviewer reads the diff against your committed rubric and posts comments on the PR — flagging, ideally, the very overdue() boundary you hunted by hand. It comments; it does not approve and does not merge (M24). A human still decides. You read its comments, then read the diff yourself, and notice the reviewer caught the off-by-one — or notice it missed it, which is its own lesson about not trusting the assistant blindly.

3. Evals tell you whether to trust any of it (M27). Turn the boundary cases from Part C into an eval set — due yesterday, due today, due tomorrow, no due date — and score the agent's implementation against it. Now do the thing the whole course was building to: swap the model behind the agent and re-run the same eval. If the new model's overdue() regresses on the "due today" case, the eval catches it before the PR ever merges. That's the close of the thesis — evals are how you judge a model swap, so the swap you will make stays safe (M27).

When this runs, look at what's left for you: filing a crisp issue, reading a diff the assistant already annotated, and reading an eval score. The agent drafted; the gates held; the eval judged. The workflow didn't just make AI safe to use — it started running itself, with you supervising instead of typing. That only works because every catch-net from Units 2–3 was already in place. Take those away and "let an agent open a PR" is reckless; with them, it's just another contributor (M11).

---

Where it breaks

• A finale is not a shortcut. The loop is fluent because you climbed the modules. Running the capstone without the foundation — no protected main, no CI, no tests — isn't "the full loop," it's the copy-paste problem with extra steps. The pipeline's value is entirely in the gates; skip them and you've kept the ceremony and thrown away the safety.
• Green CI is not correctness. Every gate in this loop is a filter, not a guarantee. CI proves the tests pass; it can't prove the tests test the right thing. The overdue() boundary trap passes a weak test suite happily. The human review step (M10) is load-bearing and stays load-bearing — the automation raises the floor, it doesn't remove the ceiling.
• The stretch variant moves the work, it doesn't delete it. An issue-to-PR agent doesn't reduce the importance of a well-written issue — it raises it, because a vague issue now produces a vague PR with no human in the authoring loop to course-correct. You trade typing for specifying and judging. That's a better trade, not a free one.
• Evals are only as honest as their cases. An eval set that omits the "due today" boundary will bless a broken model swap. The eval doesn't know what you forgot to test (M27). It scales your judgment; it doesn't supply it.

---

Check for understanding

You're done when:

• You shipped the due-dates feature from a filed issue to a running container, and curl .../overdue returns the right tasks from the deployed artifact.
• Issue #47 closed itself on merge, main is one clean commit ahead, and you caught (or consciously verified) the overdue() boundary in review rather than in production.
• You can point at each step and name the module it came from without looking — and explain why the order is the dependency chain, not an arbitrary checklist.
• You can state, from what you just did rather than from the syllabus, why the model is the swappable part: every step would survive replacing the model, and the stretch variant's eval is exactly how you'd prove a swap was safe.

If you ran the stretch variant, add one more: you watched an agent author the PR and an assistant review it, and you can say precisely which catch-nets from earlier units made handing that work to an agent a calm decision instead of a leap.

That's the course. The model wrote the code. You built the workflow that made the code matter — and that's the part that's still yours when the next model ships.