The /module-sprint runner
Building a whole module means building page after page without letting them drift apart. This runner walks each page through the same three pipelines in order, pausing for your sign-off between every step, and keeps a ledger so you can stop and pick up later.
Still finding the right amount of ceremony here. If the gates feel like too many stops, or too few, we want to know which. Reply on LinkedIn.
How to read this map
Pick a stage to walk, or start at the top
The walkthrough, as text
Every stage of the interactive walkthrough above, as plain readable text. Each stage has its own link.
Stage 0Get a locked specFind one, or build one first
Spec gate
A sprint needs a plan of what it's building before it builds anything. So step zero is making sure a locked Module Spec exists: the document that lists every page the module needs and what each one is for.
No page work starts until there is a locked Module Spec to build against. Find the existing one, or build it first.
What happens
The runner looks for a spec at docs/plans/*-<module>-spec.md. If exactly one exists, it uses it and says so. If several match, it asks you which. If none exist, it hands off to /module-build to draft and lock one before anything else happens.
The rule is simple: the spec must carry status: locked in its frontmatter. A draft is not enough. If the spec is still a draft, the runner stops and asks you to lock it or cancel, because everything downstream reads this one file as the source of truth.
Who acts
- /module-build, skill: Drafts and locks a Module Spec when none exists yet.
- AskUserQuestion, command: Asks which spec to use when several match, or whether to lock a draft.
The rules
- One locked spec, or stop. The runner will not start page work against a draft. Lock it, or cancel the sprint.
- Skip the build if a spec exists. If a locked spec is already on disk,
/module-buildis skipped silently and the sprint jumps straight to reading it.
In: A module name in kebab-case, and optionally a path to an existing spec. Out: One locked Module Spec, its page list ready to read.
Stage 1Read the spec, open the ledgerExtract the pages, track them
Setup
With a locked spec in hand, the runner reads out the list of pages to build and writes down a ledger: which pages are done, which are in progress, which are still waiting. That ledger is what lets you stop halfway and come back later.
Read the page list from the spec, then write a resumable state file so the sprint can be paused and picked up without losing its place.
What happens
The runner reads the locked spec's page-breakdown section and pulls out each page: its name, its route, its order. That ordered list is the whole plan for the sprint.
It then opens a state file at docs/plans/_module-sprint/<module>/_sprint-state.md with every page marked pending. On a --resume run it reads that same file instead, sees which pages already shipped, and builds only what's left.
Who acts
- Read, tool: Pulls the ordered page list out of the locked spec.
- the state file, agent: A plain-markdown ledger of per-page progress; the resume anchor.
The rules
- Spec order is sprint order. Pages are built in the order the spec lists them, never reshuffled.
- The ledger is the memory. Progress lives in the state file, not in the session; that is what makes
--resumework after a stop.
In: The locked Module Spec. Out: An ordered page list and a resumable state ledger.
Stage 2One page at a timeSequential, gated, never batched
Per-page loop
Now the loop begins. The runner takes the first page and stops to ask before it starts. It never builds two pages at once, and it never presses on without a nod from you. Building pages one after another is what keeps them looking and behaving like a set.
The heart of the sprint: each page goes through the same three pipelines in order, and every hand-off waits for you.
What happens
For each page the runner announces where it is (Page 2 of 5) and asks whether to start. You can start it, skip it, pause the whole sprint, or end it. Pause and end both write the ledger first, so nothing is lost.
Why one page at a time and never in parallel? Because pages share a growing design language, button styles, header choices, error patterns, and building them together lets those drift apart. Sequential work lets each page inherit the decisions the last one settled.
Who acts
- AskUserQuestion, command: The gate before every page, and before every pipeline within it.
The rules
- Never batch pages. One page fully finished before the next begins. Parallel page builds destroy inter-page consistency.
- Every hand-off is a gate. Start, skip, pause, or end. The runner never advances a stage on its own.
In: The ordered page list. Out: The current page, cleared to begin its first pipeline.
Stage 3Design the pageHand off to /page-design
Per-page · design
The first pipeline for a page is design. The runner hands the page to /page-design, which runs its own critics over a design draft and locks a design doc. The runner just waits for that to finish and notes it in the ledger.
The runner invokes /page-design and waits for it to lock a design doc. It does not do the design work itself.
What happens
The runner passes the module name, the page name, and the relevant slice of the spec to /page-design, which has its own three-critic-and-adjudicate flow and its own lock checkpoint. That guide has the full story of what happens inside.
When /page-design emits a locked design doc, the runner marks the page's design stage complete in the ledger and asks whether to move on to code. If the design never locks, the sprint pauses on this page rather than pressing ahead.
Who acts
- /page-design, skill: Runs the design critics and locks the design doc. Its own guide covers the internals.
The rules
- The runner scaffolds, it does not design. All the real design work happens inside
/page-design; the runner only invokes and waits. - No lock, no advance. If a locked design doc does not land, the sprint stops on this page and surfaces the problem.
In: The current page and its spec context. Out: A locked design doc; the ledger's design stage checked.
Stage 4Plan the codeHand off to /page-code
Per-page · code
With the design locked, the runner hands the page to /page-code. That pipeline runs critics for structure, security, and performance against a code plan, adjudicates them, and locks the plan. Again the runner waits and records.
The runner invokes /page-code against the locked design and waits for a locked code plan.
What happens
The runner passes the page context and the locked design doc to /page-code, which vets a code plan through three critics and a security-asymmetric adjudication before locking it. The /page-code guide walks that in full.
When the code plan locks, the ledger's code stage is checked and the runner asks whether to proceed to implementation.
Who acts
- /page-code, skill: Vets and locks the code plan. Its own guide covers the critics.
The rules
- Design before code. Code planning only starts once the design doc for this page is locked.
- Locked plan or pause. No locked code plan means the sprint holds on this page.
In: The current page and its locked design doc. Out: A locked code plan; the ledger's code stage checked.
Stage 5Build and verify the pageHand off to /page-implement
Per-page · build
The last pipeline for a page is implementation. /page-implement executes the locked code plan, then runs its own critique, simplify, and verify passes before the page counts as shipped. The runner waits for all of it.
The runner invokes /page-implement, which writes the code and runs its own post-build checks. Only a clean finish ships the page.
What happens
The runner hands the locked code plan to /page-implement. That pipeline is the only one that writes code into src/; it executes the plan, then critiques, simplifies, and verifies the result. Its guide has the detail.
If verification fails, a broken build or a failing test, the sprint pauses on this page and does not move to the next one until it is fixed. A clean finish marks the page shipped in the ledger with the date.
Who acts
- /page-implement, skill: Executes the code plan and runs the post-build critic loop. The only stage that writes code.
The rules
- Only implementation writes code. Every earlier stage plans;
/page-implementis where the page is actually built. - A failed verify halts the sprint. A broken build or failing test pauses this page; the next page waits until it is green.
In: The locked code plan. Out: A built, verified page, marked shipped in the ledger.
Stage 6Record it, move onThe ledger advances
Advance
With the page shipped, the runner updates the ledger and loops back to the next page. Because the ledger is written to disk, you can stop here, close everything, and resume days later exactly where you left off.
Update the state file, then loop to the next page. The written ledger is what makes a stop-and-resume safe.
What happens
The runner writes the page's shipped status and date into the state file, then returns to the top of the loop for the next page in spec order.
At any gate you could have paused or ended instead. Pause writes the ledger and exits with a resume hint; end writes a Status: ENDED marker so a stray --resume will not silently restart an abandoned sprint.
Who acts
- the state file, agent: Updated after every page; the single source of resume truth.
The rules
- Write state after every page. The ledger is updated the moment a page ships, never batched to the end.
- Pause and end are different. Pause can be resumed; end is a deliberate stop that resume refuses to override.
In: A shipped page. Out: An updated ledger, and the next page queued, or a clean pause.
Stage 7Close the sprintEvery page shipped, audit on offer
Close
When the last page ships, the sprint is done. The runner reports what it built and offers to run /module-audit, the pre-ship sweep, over the finished module. You take that or leave it.
With every page shipped, the runner summarises the sprint and offers a full module audit before you call the module done.
What happens
The runner announces completion, stamps the state file, and offers to hand the finished module to /module-audit for a pre-ship sweep across every component and cross-cutting axis.
It closes with a short summary: how many pages shipped, how many checkpoints you cleared, anything that was skipped. The module is built; the audit is the optional next gate.
Who acts
- /module-audit, skill: The optional pre-ship sweep over the finished module. Offered, not forced.
The rules
- Done means every page shipped. The sprint only reaches close when the ledger shows no pending pages.
- The audit is offered, not automatic. You decide whether the freshly built module goes straight into
/module-audit.
In: A ledger with every page shipped. Out: A finished module, and an optional hand-off to the audit.
Stage ✓A module, page by pageConsistent because it was sequential
Module built
What you end with is a whole module whose pages feel like a set, because each one was built on the decisions the last one settled, with you signing off at every hand-off.
The point of the runner: a coherent module, not a pile of pages, built one at a time with a checkpoint at every step.
What happens
The sprint never did any design, coding, or building itself. It was the connective tissue: lock a spec, walk each page through the three pipelines in order, keep a ledger, stop when you say stop.
Each of those three per-page pipelines has its own field guide. This one is the map of how they fit together into a module.
The rules
- A runner, not a builder. Sprint sequences other skills; it writes no code and dispatches no agents of its own.
In: A locked spec and your checkpoints. Out: A module whose pages hold together.