All pages

Agentic pipelines · Lesson 3.1 · 20 min

Capstone: ship a feature agentically

From spec to merged PR, with every technique in the Academy.

After this lesson you have taken one real feature from a written spec to a merged pull request, with agents doing most of the typing and you making the decisions: what to build, how far each agent may go, what counts as done, and what gets merged.

Time: 20 minutes · Works on: macOS app.

The 20 minutes is the time to read the lesson and set the run going. The run itself takes as long as the feature does. Plan an afternoon for your first one, and pick a small feature you'd otherwise build yourself in a day.

The shape of the run

Every lesson in the Academy taught one habit. This capstone strings them together into a single pipeline, so you see where each one earns its place:

  1. Spec. Write down what you're building and how you'll know it works.
  2. Cards. Break the spec into tasks an agent with no other context can finish, in an order the board enforces.
  3. Guard rails. Decide what the agents may do unasked before anything runs.
  4. Parallel work. Give each card its own worktree and its own agent, or let a fleet take them.
  5. Proof. Tests that must pass, a browser check, and a terminal that's watched.
  6. Review. Notes on the diff, sent back as the next task, and a reviewer that isn't the author.
  7. Merge. A pull request you read and merge yourself.
  8. Capture. Save what worked, so the next feature starts further along.

The worked example throughout is a web app feature: export the reports table as CSV. Swap in your own. Any feature that touches a few files, has a visible result and can be tested works.

Stage 1: the spec

Agents are good at doing what they're told and bad at noticing what you forgot to say. A spec is where you say it once, in a file every agent can read, instead of in a conversation only one agent saw. See Specs before code.

Keep it short. For the CSV export:

  • Goal. A user on the reports page can download the table they're looking at, with the current filters applied, as a CSV file.
  • Non-goals. No Excel format, no scheduled exports, no column picker.
  • Done when. A test proves the CSV matches the filtered rows, including a value with a comma and a quote in it. The button appears on the page, the download works, and the console stays clean.
  • Open question. Build the CSV in the browser from the rows already loaded, or stream it from a new server endpoint?

That open question is the one design decision in this feature that's worth a second opinion. Rather than taking the first agent's answer, put it to a panel: several independent attempts from different angles, scored by judges, with the winner explained. Judges and second opinions covers when that's worth the cost. Here it is, because the answer decides how many cards there are.

Stage 2: the cards

Each card is a task brief: a goal, the constraints, and a "done when" an agent can check on its own. Suppose the panel chose a server endpoint. The cards might be:

  1. Add a CSV serializer with tests for commas, quotes and newlines.
  2. Add GET /reports/export, which applies the same filters as the page and returns CSV. Blocked by 1.
  3. Add the Export button to the reports page, wired to the endpoint, with a loading state. Blocked by 2.

Dependencies matter more when agents work in parallel. A card that's blocked isn't offered to any worker, so the button can't be built against an endpoint that doesn't exist yet. The board is the queue explains why the board, not a conversation, should hold this order.

Stage 3: the guard rails

Decide now what the agents may do without asking, while you can think about it calmly. Afterwards you'll be tempted to approve things just to keep them moving.

  • Posture. Approve for everything in this run. Writes wait for you, reads don't. See Choose a posture.
  • Standing rules. Approve the test command and the dev server once each, with Always…, so you aren't asked fifty times. Nothing wider.
  • Rehearsal. If a card touches something you can't easily undo, such as a migration, have the agent do it as a dry run first and read the combined diff. See Rehearse with dry runs, undo with snapshots.
  • Secrets. The endpoint needs a database URL. It goes in the project's environment or the Keys vault, never in a prompt. See Secrets without leaks.

Stage 4: the parallel work

Two cards can't start until the first is done, so this feature is mostly serial. That's normal. Parallelism pays off across features, or within one when cards are independent. You have two ways to run it:

  • By hand. One worktree per agent. You create the worktree, start an agent in it, and watch. Use this for your first capstone, because you see every step.
  • With a fleet. The fleet claims ready cards, gives each one a worktree and a worker, and by default opens a pull request for each. See Run a fleet. Use it once the by-hand run has shown you the cards are well written.

Whichever you choose, mix agents where it helps. The serializer is a good fit for the sidebar agent. You might give the endpoint to Claude Code in a pane, connected to TRMNLY as in Drive TRMNLY from Claude Code. If you can't decide how to build the button, race two agents at it and keep the better branch.

Let agents report to each other in the project chat and raise a flag when they need you, rather than you checking each pane. See Agents that talk.

Stage 5: the proof

"Done" is something an agent shows you, not something it says. Three kinds of proof cover this feature:

  • Tests. Card 1's tests are written first and fail, then pass. That's the contract the agent works to. See Tests are the contract. If you built the preflight plugin in Extend the toolbox with plugins, every agent runs it before calling a card done.
  • The browser. For card 3, the agent opens the reports page in TRMNLY's browser, applies a filter, clicks Export, and checks the console. A screenshot is part of its report. See Verify in the browser.
  • The terminal. A rule watches for test failures and a pane is watched for the dev server's errors, so a failure reaches you even if the agent misses it. See Watch the terminal.

Stage 6: the review

Read every diff before it leaves your machine, and send what you find back as the next task rather than fixing it yourself. Line notes keep their place even after the agent edits the file. See Review the diff.

Add one review you don't do yourself. With a fleet, turn on Review first, and a reviewer agent that can't edit anything reads each branch before it lands. A rejected card goes back on the board with the findings. By hand, ask a second agent, in a different model if you can, to leave notes on the branch diff with the review tools. Either way, the author isn't the only one who checked.

Stage 7: the merge

Open the pull request from the worktree, read it the way you'd read a colleague's, and merge it yourself. Keep the fleet's land policy on Open a PR (default) for this run. Merging is the step where a person is most valuable and costs the least time.

After the merge, clean up: the worktree is removed, the card moves to Done, and the next card on the board becomes ready.

Stage 8: the capture

The last stage is what makes the next feature faster. Ask what you repeated:

  • A prompt you typed three times becomes a saved prompt. See Prompts and runbooks.
  • A sequence of prompts that always went the same way becomes a runbook.
  • A check you ran by hand every morning becomes a schedule. See Schedules and unattended runs.
  • A rule the agents kept breaking becomes a line in your project instructions. See Context that sticks.
  • What the run did is in the audit log, if you need to explain it later. See Read the audit trail.

Do it in TRMNLY

Spec

  1. Create a branch for the feature or work on your main checkout, and write the spec in a file in the repository, such as specs/csv-export.md.
  2. Show the right sidebar with ⌘⇧\, click Files, select the spec and choose Pin to agent. The spec is now in the agent's context on every turn for this project, up to 24 KB.
  3. In the Agent tab, ask: "Use judge_panel on this question from the pinned spec: build the CSV in the browser or stream it from a server endpoint? Our tables can reach 50,000 rows." The panel runs two to four independent attempts, scores them and explains the winner. Write the decision into the spec.

Cards

  1. Ask the agent: "Turn the pinned spec into cards on the Tasks board. One card per independently testable change, each with a goal and a done-when, and set Blocked By so they run in order." It uses kanban_add and kanban_depend.
  2. Open More ▾ → Tasks and read every card as if you were the agent. Fix any that rely on context only you have. Click the bolt button in the filter bar: only the first card should be ready.

Guard rails

  1. Check the posture chip in the agent header reads Approve. When the first test-command approval card appears, use Always… to allow it for the project.
  2. If a card involves a migration, ask the agent to do it as a dry run and show you the combined diff before applying it.

Parallel work, by hand

  1. Click the worktree selector at the top of the left sidebar and choose New Worktree…, or press ⌃⌘N. Name the branch after card 1. TRMNLY copies your .env and node_modules into the new checkout.
  2. In that worktree, ask the sidebar agent: "Take card #1. Write the tests first and show me they fail, then make them pass." It claims the card, so no other agent takes it.
  3. When card 2 becomes ready, make a second worktree and start claude in a pane there. Tell it: "Take card #2. Use TRMNLY's worktree tools, not your own. Post a summary to the project chat when you're done."
  4. If you're unsure how to build card 3, ask the agent to race it: "Use race_start on card 3 with two workers and a $2 budget." Check progress with race_status and keep the winner with race_pick.

Parallel work, with a fleet

  1. For your second capstone, skip steps 8 to 11. Expand the Fleet strip under the Tasks header, set workers to 1 or 2, enter a Budget, leave When done on Open a PR (default), turn on Review first and click Start. Watch the strip and the board. Stop hands every unfinished card back.

Proof

  1. Under More ▾ → Flows → Tab-monitor rules, click Open editor… and add a Contains rule for failed with the Notify action. A failing test run anywhere in the project now notifies you.
  2. For card 3, ask: "Open the reports page in the TRMNLY browser, filter to last week, click Export, and confirm the download and a clean console. Include a screenshot." The agent uses the browser_* tools; watch it work in the browser sidebar.
  3. Ask the agent to run the project's tests, or call preflight if you have the plugin, before it says each card is done.

Review

  1. Open More ▾ → Review in the card's worktree. Click lines to leave notes, then Send to agent. Notes that have moved report moved to line N; lost ones quote their original line.
  2. For a second reviewer, start another agent and ask it to read the branch diff and leave notes with diff_comment_add. Its notes appear in the same Review tab, ready to send.

Merge

  1. Commit, click the worktree selector and choose Open PR…. Read the pull request on GitHub. When you're satisfied, open Manage Worktrees… and use Merge PR & Clean Up… to merge and remove the worktree in one step. If you merged on GitHub instead, remove the worktree from its row. Then move the card to Done.
  2. Repeat for the remaining cards. Each one becomes ready as the card it's blocked by is done.

Capture

  1. Open Flows and press Save current session (⌘⇧S) on the session that went best. Trim it with Edit…. Save the prompts you repeated in Prompts, and put the ones your team should share in a watched folder in the repository.

Check yourself

  • The spec is in the repository and records the design decision and why.
  • Every card on the board could be finished by an agent that had read only the card and the spec.
  • No two agents worked in the same checkout.
  • Every card's "done" came with proof: a passing test, a screenshot or a clean console.
  • Someone other than the author reviewed each branch.
  • You merged every pull request yourself.
  • You saved at least one prompt or runbook from this run that you'll use on the next feature.

Go further

  • Agentic development is delegation — start the Academy again with a feature under your belt
  • Fleet — races, repair cards and the fleet_* tools
  • Kanban — claims, dependencies and several boards per project
  • Review — the diff notes and the tools agents use to share them
  • Worktrees — the worktree selector, PRs and clean-up