How the pipeline runs

This section is for someone about to change Groundwork — add a specialist, move a gate, alter a hand-off shape. If you are about to run a stage and want to know what it asks you and what it writes, the user guide is the page you want; this one assumes you have read it.

Groundwork is three stages. The requirements stage turns an interview into a validated requirement set; the design stage turns that set into an architecture; the QA stage turns both into a test strategy. Nineteen agents are dispatched across the three — seven requirements, seven design, five QA — and every one of them is a subagent invoked by a skill or by an orchestrator — no agent runs itself.

Each stage is an interview, then a generation pipeline, then a write. The pipelines are what the maps below describe. The interviews are described in the guide, and the write is the last stage of each pipeline rather than a phase of its own.

The requirements stage

plugin/skills/requirements/SKILL.md runs the interview and then drives requirements-orchestrator through the stages below. Dispatch order inside it is fixed: fr-specialist, then nfr-specialist, then constraint-specialist, then requirements-critic, then requirements-formatter. The constraint specialist runs third because it traces constraints and business rules to concrete FR and NFR IDs, which do not exist until the first two have returned. The critic runs once, on the merged set. After the write, the skill runs generate_dod.py — a deterministic script, not an agent — which projects .sdlc/definition-of-done.md from whichever of the requirements, design and QA artifact sets exist on disk. All three stage skills run it: each rewrites the file with the gates its own stage adds, so the Definition of Done always reflects everything that has run so far.

What exists on disk

Nothing, until Stage 7. The interview, the classification, the ID allocation, the three specialists and the critique gate all happen in memory, passing the typed objects in the hand-off column between them. This is not an optimisation — it is why the critic’s gate is judgment only. There are no files for a structural validator to read at Stage 6, and assumptions.md and glossary.md, which that validator hard-gates, are not assembled until Stage 6.5, after the gate has passed.

There is also a human sign-off between the pipeline and the write. The stage summarises the generated set in conversation and asks before it writes anything; corrections are re-dispatched to the owning specialist rather than edited into files, because at that point there are no files.

At Stage 7, everything appears at once. The formatter writes the atomic requirement files into their type subdirectories, plus assumptions.md, glossary.md and an index.yaml carrying a review_queue of every confidence: low requirement — and then, as part of the same contract, re-runs validate_requirements.py against what it has just written. That re-run is the pipeline’s single structural gate. It is folded into the formatter rather than placed after it so that one agent both writes the set and answers for its structure.

The advisory content linter runs after the gate, over the same files, and generate_dod.py writes .sdlc/definition-of-done.md last, in its requirements-only form.

The design stage

plugin/skills/design/SKILL.md runs its own interview and then drives design-orchestrator. The agents it dispatches, in order: component-specialist, then interface-specialist, then design-critic, then adr-generator, then c4-generator, then design-formatter. The interface specialist runs second because it needs the component set — it designs contracts against the capabilities those components declared. The two generators run after the critic’s gate has passed and before the formatter, which is the whole reason Stages 11 and 12 are retired.

What exists on disk

.sdlc/requirements/ exists already, and the stage reads it — Stage 2 is the orchestrator reading the requirement set once, on everyone’s behalf, so that six downstream agents do not each re-read it and reach six slightly different readings. The stage also runs the requirements validator over that directory as an entry gate before any of this starts.

Nothing exists under .sdlc/design/ until Stage 10. Components, interfaces, the back-filled depends_on edge, the critique gate, the ADR specs and the C4 model all live in memory. c4-generator at Stage 9.6 is the clearest case: it returns a draft_diagram_model and writes no file, because the script that projects that model into Mermaid has to run against the files on disk, and they do not exist yet.

At Stage 10 the formatter writes, in a fixed order. The CMP, IF and ADR files first, then assumptions.md and drivers.md — drivers.md specifically before the diagrams, because the Context view’s traces_from is parsed out of its Architecturally Significant Requirements section — then generate_c4.py projects the model into diagrams/, then the traces_to.diagrams back-fill onto the components those diagrams name, then index.yaml. Only then does the formatter re-run validate_design.py over everything it wrote, diagrams included, followed by validate_traceability.py across the requirement↔design edge that neither structural validator covers.

One writer, one structural gate, over a set that includes the diagrams.

The QA stage

plugin/skills/qa/SKILL.md runs its own interview — covering only what neither prior stage carries — and then drives qa-orchestrator, which reads the approved requirement and design sets once on everyone’s behalf. Five agents are dispatched, in this fixed order: qa-orchestrator, then behavioural-test-specialist and quality-attribute-test-specialist together, then qa-critic, then qa-formatter. The two specialists are dispatched in parallel rather than in sequence — unlike the design stage’s component/interface pair, neither needs the other’s output — and the critic runs once, on their merged draft_test_strategies set.

What exists on disk

.sdlc/requirements/ and .sdlc/design/ both exist already, and Stage 2 is the orchestrator reading both sets once, on everyone’s behalf, so that neither specialist re-reads either directory and arrives at its own reading of it.

Nothing exists under .sdlc/qa/ until the formatter runs. The digest build, ID allocation, both specialists and the critique gate all happen in memory, the same discipline the other two stages hold for the same reason: there is nothing on disk yet for a structural validator to read, so the critic’s gate here is judgment only too.

At the formatter, everything appears together. It writes the atomic TS- files into .sdlc/qa/strategy/, projects qa-strategy.md from the approved set and the synthesised qa_context_artifact, and writes the mandatory index.yaml — all in the same pass. Only then does it re-run validate_qa.py against what it just wrote, followed by validate_traceability.py across the requirement↔design↔QA edges that neither structural validator covers on its own. A non-zero exit on either re-run re-opens the critique loop rather than reaching sign-off.

The gap at the end of the design map

The design orchestrator’s Stages 11 and 12 are retired, their numbers were not reused, and the map renders them so that the gap is visible rather than inferred. Both held generators that originally ran after the formatter; both were moved before it, because a post-formatter generator is a second writer that re-opens files the validator has already passed and re-runs the gate. Renumbering the stages would have made an orchestrator’s stage numbers mean different things at different points in the repository’s history, which is the same reason artifact IDs are never reused.

Where the map stops

It stops where the built pipeline stops. Requirements, design and QA are what exists; implementation — M4 — is backlog, and this section describes the pipeline that runs rather than the one that is planned. Documenting intent as though it were behaviour is the specific defect this section was written to avoid.

This statement has moved once already, from “design” to “QA”, the moment the QA stage landed. It will move again when M4 does, and it changes here, in the same commit as whatever adds the fourth stage, rather than in a follow-up — the same rule this task itself was filed under.