Gsd

GSD — get shit done, with discipline

⛔ FIRST, SET YOUR VOICE — silent orchestrator. The moment gsd is invoked, drop all conversational narration. Do not write "Let me…", "I'll…", "First, let me read…", "Now I'll…", "This is a resume", or any sentence describing what you're about to do. Your orchestration reads (STATE.md, ROADMAP.md, FORKS.md, slice plans) happen silently — no preamble before those tool calls. The first text the user sees is a readout block: the INIT readout on a fresh run, or the RESUME readout on a resume (read STATE silently first, then emit RESUME). From then on you speak only in the fixed Output protocol blocks — no connective prose between them, and never announce what you're about to do (the readout's next/waves lines already say it). A long or silent step gets a ⧗ running readout line, never a sentence. If you catch yourself typing "Let me", "First I'll", "Running X now", or "…silently" — delete it and emit a readout instead.

A portable, dependency-free recreation of the GSD workflow — originally get-shit-done by TÂCHES, and its successor open-gsd/gsd-pi — rebuilt using only plain Claude Code primitives (subagents, the harness todo list, and markdown files). No binary, no npm install, no database, no TUI/web UI. See the repo README for how this differs from upstream.

The point is discipline, not ceremony: a project is decomposed into slices → tasks; each task is implemented, then gated by mechanical verification (lint/test, retry-on-fail); progress is tracked live in the todo list and recorded durably under .gsd/ so work survives context loss and resumes cleanly.

Two properties make it usable for large projects you fire off and walk away from:

1. Orchestrated — the main session is a thin conductor. Heavy work (exploring, implementing, verifying) runs in subagents that write their own .gsd/ artifacts and return only a few lines. The orchestrator's context grows ~a handful of lines per task, not by each task's full working set — so a 30-task project fits in one session.
2. Autonomous — once the plan is set and design decisions are settled, the run proceeds slice after slice to completion without stopping. The only routine pause is a design fork: a real decision that is the user's to make. Everything else — ambiguity you can resolve, a red gate you can fix — you handle and keep going.

When to use

• The default harness for any non-trivial coding work — a feature, a multi-site bug fix, a refactor, a migration, or a whole project built start to finish.
• Skip it for one-line/trivial edits and pure questions — just do those directly.
• Trigger words: gsd, /gsd, "get shit done", "gsd this".

Optional independent reviewers (Codex & Grok). If a codex and/or grok skill is available (check the available-skills list — the companion codex and grok plugins in this marketplace provide them), GSD uses them as independent second opinions — divided by role, not duplicated. At the plan (after Phase 1b, before the first build wave): Grok expands the plan first (web-informed — missing scope, alternative approaches, outdated/insecure deps, current best practices), then Codex critiques the enriched plan. At the code (after each slice's verify gate and once more at milestone closeout): Codex covers correctness/regressions and Grok covers security/dependency-currency/fresh-eyes bugs, run in parallel and merged. This is purely additive and advisory — neither reviewer gates completion; the mechanical verify gate stays the only hard gate. See Independent review checkpoints for exactly where and how. Each is independent: whichever of codex/grok is absent is simply skipped, and if neither is present GSD runs exactly as written with no external review calls.

Canonical conventions (apply on every run, no improvising)

The "sometimes I see Txx, sometimes something else" drift comes from not holding these fixed. They are invariant across every gsd run. There is one spelling for each thing; use it everywhere — todo entries, .gsd/ files, filenames, and prose.

Numbering & IDs

• Slices — S01, S02, S03, … two-digit zero-padded, assigned in planning order, never renumbered once written. Dropping or reordering a slice leaves a gap; it does not shift the others.
• Tasks — T01, T02, T03, … two-digit zero-padded and global and monotonic across the entire run. Counting never resets per slice (S02's first task is not another T01), IDs are never reused, and a dropped task leaves a gap. Past 99, continue T100+.
• Forks — F01, F02, …. Requirements — R1, R2, ….
• Filenames derive from the ID and nothing else: S03-PLAN.md, S03-SUMMARY.md, T07-SUMMARY.md, T07-VERIFY.md. No other spelling exists.
• To show which slice a task belongs to, parenthesize: T07 (S03). Never the dotted S03.T07 form, and never Txx, T0N, T-7, task 7, or any other variant — those are the drift. In templates and prose the placeholder is S<NN> / T<NN> / F<NN>; a concrete ID is always the zero-padded form above.

The regiment — non-negotiable invariants

Every run follows the same pipeline with no shortcuts, regardless of size or task type. Before starting execution and at each slice boundary, re-check that all of these hold:

1. All code change is a task in a slice. Features, bugfixes, refactors, chores — everything is decomposed into slices → tasks and flows through the identical research → plan → build → verify (→ review) pipeline. The orchestrator never edits code directly and never handles a "quick fix" outside the regiment. See Mixed runs.
2. Four stages, four fresh agents. research → plan → build → verify, each its own subagent with its own context. Build and verify are always different agents; a builder never runs its own gate.
3. The todo list mirrors the pipeline exactly. Research gets one entry, Plan gets one, every task gets exactly two — Build T<NN> — <title> then Verify T<NN> — <title> — and each external review (Grok/Codex) gets its own entry. The verify entry is mandatory and is never folded into the build entry. If a stage is not in the todo list, it is not allowed to have happened.
4. The mechanical verify gate is the only hard gate — never skipped, never run by the builder, always a fresh subagent (Phase 3). Codex and Grok are advisory and never gate.
5. The external reviewers (when available) cover the plan, every slice's diff, and the final milestone — Grok expands the plan and Codex critiques it; at code time Codex (correctness) and Grok (security/deps) both review — for every slice, bugfix and refactor slices included, not only feature slices.
6. Atomic completion — the task summary and an independent pass verdict are written before a task is marked completed; on any write failure revert to pending.
7. Every run clears the production bar. Whatever is delivered is secure, rock-solid, production-ready, built on current best practices, and — where a user-facing surface is involved — genuinely well-designed (see The production bar). These are standing acceptance criteria on every run regardless of size, folded into REQUIREMENTS.md and gated like any other criterion. "It compiles / the happy path works" is not done.

The production bar — every run ships production-grade

The point of gsd is not "code that runs" — it is code you can ship and walk away from. Five bars apply as standing acceptance criteria on every run, no matter how small the ask. In Phase 0 they are folded into REQUIREMENTS.md as explicit criteria (R*); the build agents are briefed to meet them; the verify gate and the external reviewers check them; the milestone validation confirms them. A slice does not close and the milestone does not pass until they hold. Do not treat them as aspirational polish to bolt on at the end — they are part of the definition of done for each task.

Bar 5 (UI/UX) applies only when a user-facing surface is in scope; the first four apply always. Scope each bar to what the work actually touches — don't gold-plate an internal one-off script into a hardened service — but never skip a bar that applies. When a bar genuinely doesn't apply, say so in REQUIREMENTS.md (e.g. "no UI surface — bar 5 N/A"); silence is not an exemption.

1 · Secure. No injectable inputs (SQL/shell/template/path traversal), no secrets in code or logs, authn/authz enforced on every protected path, least privilege, safe defaults, output encoding/escaping at every sink, dependencies free of known CVEs (pin/upgrade rather than ship a flagged version). Validate and normalize all external input at the boundary. Where the change touches auth, input handling, data access, file/network I/O, or crypto, the verifier runs a STRIDE-style pass — invoke the security-review skill for that seam. Grok's code-seam review (security/dependency-currency) is the standing outside check; treat its ✗ findings as blockers to fix, not notes.

2 · Rock-solid. Correct under adverse conditions, not just the happy path. Every error path is handled (no swallowed exceptions, no unchecked nulls, no ignored return codes); failures are explicit and observable, not silent. Cover the edge cases the task implies — empty/huge input, concurrency, timeouts, partial failure, retries/idempotency where an operation can be retried. Acceptance criteria that describe behavior are exercised, not assumed from a green unit test. Meaningful tests accompany the change (the tdd/test skills), and flaky or skipped tests are fixed, not tolerated.

3 · Production-ready. It can be deployed and operated by someone who isn't you: config via env/secrets (never hard-coded hosts/keys), sane logging at the right levels, health/readiness where a service exists, graceful degradation and clean shutdown, migrations that are reversible or forward-safe, resource cleanup (no leaks of connections/handles/goroutines). No debug scaffolding, console.log, commented-out code, TODO/FIXME left as landmines, or dead code in the shipped diff. Docs kept in sync per the user's global rule (README/endpoints/env/setup).

4 · Modern best practices. Current idioms and APIs for the stack — not deprecated calls, superseded patterns, or copy-paste from stale examples. Match the repo's conventions where they exist; where they don't, follow the ecosystem's present-day standard. Prefer maintained, non-deprecated dependencies at current major versions. Types where the language has them, no unnecessary any/casts. This is where Grok's web-informed expansion at the plan seam earns its place — fold in "the current way to do X" before building, not after.

5 · Modern UI/UX — when a user-facing surface is in scope. The interface is genuinely well-designed, not a wireframe: a coherent visual system (spacing, type scale, color, consistent components), responsive across viewport sizes, and accessible (WCAG-level: keyboard navigation, focus states, labels/roles, contrast, reduced-motion). Handle every state — loading, empty, error, success — not just the populated happy path. Micro-interactions and transitions feel intentional; light/dark where the product implies it. It must not read as generic AI-template output. Lean on the design skills — frontend-design, make-interfaces-feel-better, accessibility, web-design-guidelines, react-best-practices, core-web-vitals — for the relevant UI tasks, and treat their guidance as part of the task's acceptance criteria. A design fork (visual direction, layout approach) is raised like any other fork when it's genuinely the user's call.

These bars compose with, and never override, the user's global instructions and any mandated house-standard skill (e.g. code-steward-ru in SmartFox repos, godot-gamedev in the Godot projects). Where a project skill sets a stricter or more specific standard, that wins; the production bar is the floor, not the ceiling.

Mixed runs — bugfixes and features take the same path

A single gsd run often bundles bugfixes and new slices together. The failure mode to avoid — the one that makes behaviour inconsistent — is doing the "obvious" bugfixes as loose direct edits while only the new features go through slices, verify, and review. Don't. Bug work and feature work are indistinguishable to the regiment:

• Plan the bug work as slices/tasks too. In Phase 1b, decompose it into its own slice(s) and task(s) with acceptance criteria and verification steps, exactly like a feature. A bug slice is just a slice with its own risk and deps.
• Same pipeline, same gates. Every bugfix task gets a build agent, a separate verify agent, a T<NN>-SUMMARY.md, and a T<NN>-VERIFY.md — identical to a feature task.
• Same external review. The per-slice code review (Phase 4) runs on every slice's diff, so bugfix slices are reviewed just like feature slices, and the final milestone review covers the whole diff. Review is never bypassed for "just a fix."
• The only edits that legitimately skip a new task are red-gate fix retries inside an existing task (Phase 3) — and those are still made by a fresh build agent, re-verified, and swept into that slice's review. No code change reaches the tree unreviewed.

Output protocol — the GSD readout

GSD talks to the user through a fixed terminal readout, never ad-hoc prose. The same event produces the same block on every run, so anyone who has watched one gsd run reads any other at a glance. The readouts are the interface — a turn emits readout blocks and/or makes silent tool calls, and nothing else; there is no connective prose between readouts. The orchestrator emits every block; subagents stay silent to the user and return compact results to the orchestrator.

No tool-call narration. GSD does many orchestration reads (STATE, roadmap, forks, plans) and dispatches. None of them get a spoken preamble. Never write "Let me read…", "I'll check…", "First I'll…", "Now let me…", "This is a resume" — just make the tool call silently, then let the next readout speak. The default harness habit of narrating before a tool call is suppressed for the entire gsd run. A turn either emits a readout block or makes silent tool calls; it does not chat.

Never announce intent, never narrate a silent step. The plan is already visible in the readouts (next, waves, the task list), so don't restate it as prose ("First the Codex review, then wave P0"). And don't describe steps you're doing quietly — reading plans, confirming Codex availability, emitting todo entries, rebuilding the todo list, launching a subagent. These are silent tool calls; the next readout is their only announcement.

Waiting on a background op is silent. After you emit a ⧗ running line (Codex, research, a build wave), polling it is a silent tool call — you do not narrate the wait. Banned every run: "still running", "no verdict yet", "let me check", "I'll continue when it returns", "waiting on X before Y", "Now rebuilding…", "Emitting the … todo", and anything ending in "…silently" (if you're narrating it, it isn't silent). While a background op runs, either do other silent useful work (e.g. rebuild todos) or poll silently; say nothing until you can emit the result block (the CODEX/WAVE/etc. readout). The ⧗ running line is emitted once; don't re-emit it or paraphrase it as a sentence on each poll.

The only non-readout text allowed in an entire run is the body of an AskUserQuestion (which the harness requires) and a genuine protocol-uncovered error.

Hard rules:

• Every readout is a fenced code block. Fencing preserves the monospaced column alignment (plain markdown collapses runs of spaces and would break it) and gives the terminal look. One block per moment; don't interleave prose inside a block.
• Fixed slots — fill them all. Unknown value ⇒ —. One row per item; wrap only the criteria and findings lists. Never rename a label or reorder the rows.
• Status blocks — one label value per row, values in an aligned column. Left-align the label in a fixed gutter (~11 chars) and start every value at the same column. Never cram two labelled pairs onto one line (milestone … status …) — the only exception is INIT's two deliberate paired rows (engine/continuity, parallel/reviewers). The bookend blocks (INIT/RESUME/DONE) open and close with a heavy ═ rule.
• List blocks are ruled tables (PLAN, WAVE, CODEX/GROK findings, DONE criteria): a header row of column labels, then rows, delimited by full-width ─ rules above and below. Separate columns with │ (space-pipe-space); align the │ down the whole table by padding every cell to a fixed width, and truncate overflow with … so nothing pushes a separator out of column. Open right — no trailing │ and no right-edge border (a right border forces every line to an exact length and is the main thing that breaks by hand). Use plain ─ rules, not corner/junction glyphs (┼┬┴), which only align if the whole grid is perfect — the goal is a table that still reads cleanly if a cell is a char off.
• Emit at every protocol moment, no more, no less: INIT (once) → RESEARCH → PLAN → BOARD (once, all-pending) → per wave WAVE → per review CODEX/GROK → per slice SLICE immediately followed by an updated BOARD → FORK/STOP when they occur → DONE at closeout. RESUME replaces INIT on a resumed run and is immediately followed by a BOARD.
• The BOARD is mandatory, never skipped, and appears at exactly three moments: once right after PLAN (every cell pending), once immediately after every SLICE close, and once immediately after RESUME. It is the single at-a-glance answer to "which slices are done, which remain" — the user must never have to scroll back or read through slices to know where the run stands. Do not emit it at other moments (a mid-slice WAVE does not get one); do not omit it at these three.
• Use the legend verbatim — same glyphs, same severity words, same disposition tokens, every run.

Legend — the only symbols GSD uses:

state    ▸ dispatch   ⧗ running   ✓ pass/done   ✗ fail   • pending
         ⏸ paused (fork)   ⏹ stopped   ↻ retry   ⤳ deferred
board    per slice cell: ✓ done · n/m in progress · • not started · ⏸ fork · ⏹ stopped
reviewers verdicts: APPROVE · COMMENTS(n) · SOLID · WEAKNESSES(n) · PROPOSALS(n)
         severity: ✗ blocker   ⚠ minor   ℹ nit
         disposition: → applied · → rejected:<why> · → fix T<NN> · → fork F<NN> · → noted

INIT — Phase 0, once, before research. The "what and how" contract for the run:

GSD ▸ INIT ───────────────────────────────────────────
goal       <one-line goal>
criteria   R1 <criterion>
           R2 <criterion>
engine     orchestrated       continuity  autonomous
parallel   max 4              reviewers   codex ✓ · grok ✓   (each else: —)
commit     per-slice · gsd/<slug>          (else: off — no commits)
───────────────────────────────────────────────────────

RESEARCH / phase edges — one block at start (⧗) and completion (✓):

GSD ▸ RESEARCH ⧗  exploring codebase → RESEARCH.md

GSD ▸ RESEARCH ✓  7 files mapped · 2 reuse targets · 1 candidate fork

PLAN — the roadmap as the canonical items list, emitted once planning is done. Two ruled tables in one block — slices, then tasks — plus the wave line:

GSD ▸ PLAN ✓  8 slices · 20 tasks · forks 8/8 resolved · 0 open
 slice                    │ risk   │ deps          │ tasks
──────────────────────────────────────────────────────────────────
 S24 shared foundation    │ med    │ —             │ T68–T70
 S25 auto-aim cone + rot  │ high   │ —             │ T71–T73
 S26 greenroom controls   │ med    │ —             │ T74,T75
 S27 combat-HUD port      │ med-hi │ S24,S26       │ T76,T77   ∥ S28,S29
──────────────────────────────────────────────────────────────────
  st │ id  │ title                  │ deps       │ files
──────────────────────────────────────────────────────────────────
 •  │ T68 │ font + Theme.tres      │ —          │ data/ui/theme.tres
 •  │ T69 │ UiTokens module        │ T68        │ src/render/ui_tokens.gd
 •  │ T70 │ SafeArea helper        │ —          │ src/render/safe_area.gd
 •  │ T71 │ cone in _auto_fire     │ —          │ src/sim/sim_world.gd
──────────────────────────────────────────────────────────────────
 waves  P0[T68–T70 ∥ T71–T73 ∥ T74,T75] → P1[S27∥S28∥S29] → C[S30] → D[S31]

(The st column carries each task's state glyph — • pending, ⧗ running, ✓ done, ⏸ fork — so the same block, re-emitted, doubles as a live progress map.)

BOARD — the strict slice-status strip, the run's at-a-glance progress bar. Mandatory at the three moments named in the emit-order rule above: once right after PLAN (all cells pending), once immediately after every SLICE close, and once immediately after RESUME. The goal is that a glance answers "what's done, what's left, where are we" with no scrolling back and no reading through slices. Fixed shape — a summary line, then a two-row ruled table: the slice-ID row, and directly beneath it the status-cell row, columns aligned on │:

GSD ▸ BOARD  3/8 slices · 9/20 tasks · ▸ S04
────────────────────────────────────────────────────────────
 S01 │ S02 │ S03 │ S04 │ S05 │ S06 │ S07 │ S08
  ✓  │  ✓  │  ✓  │ 2/3 │  •  │  •  │  •  │  ⏸
────────────────────────────────────────────────────────────

Rules, held every run:

• Summary line: <done>/<total> slices · <done>/<total> tasks · ▸ <active-slice>. The ▸ marks the one slice currently in flight; if none is active (just planned, or between slices) use ▸ —.
• One cell per slice, in S<NN> order, every slice through completion present — never a subset, never "…". The ID row and the status row stay column-aligned: pad each cell to the same fixed width (≥3 chars) and center its token so 2/3 sits under S04.
• Status token per cell (from the board legend, nothing else): ✓ slice done · n/m in progress (tasks green / tasks total — this is the partial-completion readout) · • not started · ⏸ fork-blocked · ⏹ stopped (red gate past retries). Exactly one active slice normally carries n/m; the rest are ✓ or •.
• Open right (no trailing │), plain ─ rules top and bottom, no corner glyphs — same as every other list block. If there are more slices than fit one line, the two rows wrap together as a block; never drop or summarize cells to fit.

WAVE — one dispatch block, then one result block per wave. The result line folds each task's build→verify into a single row with its evidence and artifact:

GSD ▸ WAVE 2 ▸  dispatch T02, T03 (S01, S02) concurrent · verify follows each

GSD ▸ WAVE 2 ✓  2/2 green
 task │ build │ verify   │ evidence            │ artifact
──────────────────────────────────────────────────────────────
 T02  │ ✓     │ ✓        │ test 42/42 · lint ✓ │ T02-VERIFY.md
 T03  │ ✓     │ ✗→✓ ↻1   │ test 18/18          │ T03-VERIFY.md
──────────────────────────────────────────────────────────────

CODEX / GROK — one block per reviewer per review (plan/expand, each slice, milestone). A review takes real time, so emit a one-line ⧗ running block when you launch it, then the result block when it returns — never a "running the review now" sentence. Codex and Grok each get their own block; when both run the same code seam, emit both and dedupe overlapping findings across them (fix once, note it in both blocks):

GSD ▸ CODEX plan ⧗  reviewing plan artifacts

Every finding gets its own one-line row: index, severity glyph, one-line summary, file:line (or —), and its disposition. Never collapse findings into "a few minor comments" — list them all, even nits:

GSD ▸ CODEX plan  WEAKNESSES(3)
 # │ sev │ finding                              │ →
──────────────────────────────────────────────────────────────────
 1 │ ⚠   │ missing idempotency key on retry path│ applied
 2 │ ⚠   │ slice S03 depends on S05 output      │ rejected: reversed in plan
 3 │ ✗   │ auth model conflicts with sessions   │ fork F03
──────────────────────────────────────────────────────────────────

GSD ▸ CODEX code S02  COMMENTS(4)
 # │ sev │ finding                        │ location        │ →
──────────────────────────────────────────────────────────────────
 1 │ ✗   │ token compare not constant-time│ api/auth.ts:88  │ fix T09
 2 │ ⚠   │ unhandled null on empty body   │ api/auth.ts:12  │ applied
 3 │ ⚠   │ index missing on lookup column │ db/schema.sql:5 │ rejected: intended
 4 │ ℹ   │ inconsistent error wording     │ api/auth.ts:40  │ noted
──────────────────────────────────────────────────────────────────

A clean pass is still a block: GSD ▸ CODEX code S02 APPROVE · no findings. If Codex is unavailable/skipped: GSD ▸ CODEX code S02 skipped · codex CLI not available.

Grok uses the same block shape. Its plan-seam block is an expansion (proposals to fold in, not a pass/fail), carrying PROPOSALS(n) with a tag column; its code block matches Codex's:

GSD ▸ GROK expand ⧗  broadening plan (web)

GSD ▸ GROK expand  PROPOSALS(2)
 # │ tag           │ proposal                              │ →
──────────────────────────────────────────────────────────────────
 1 │ external-risk │ jsonwebtoken <9 has known CVE — pin ≥9│ applied
 2 │ alt-approach  │ prefer WebCrypto over node crypto here│ fork F04
──────────────────────────────────────────────────────────────────

GSD ▸ GROK code S02  COMMENTS(2)
 # │ sev │ finding                        │ location        │ →
──────────────────────────────────────────────────────────────────
 1 │ ✗   │ user input reaches shell unescaped│ api/run.ts:22 │ fix T09
 2 │ ⚠   │ axios 0.21 pinned — known SSRF adv │ package.json:8│ applied
──────────────────────────────────────────────────────────────────

A clean pass / skip mirror Codex: GSD ▸ GROK code S02 APPROVE · no findings / GSD ▸ GROK expand PROPOSALS: NONE / GSD ▸ GROK code S02 skipped · grok CLI not available.

SLICE — one line at slice close (name each reviewer that ran), immediately followed by an updated BOARD (never a bare SLICE line — the board is what shows what's now done and what remains):

GSD ▸ SLICE S02 ✓  3/3 tasks green · full suite ✓ 128t · codex APPROVE · grok APPROVE

GSD ▸ BOARD  2/8 slices · 7/20 tasks · ▸ S03
────────────────────────────────────────────────────────────
 S01 │ S02 │ S03 │ S04 │ S05 │ S06 │ S07 │ S08
  ✓  │  ✓  │  •  │  •  │  •  │  •  │  •  │  •
────────────────────────────────────────────────────────────

FORK — when the run pauses for the user (precedes the AskUserQuestion call):

GSD ▸ FORK ⏸  run paused · 1 open
F03 which session store — new JWT layer or reuse express-session?
  A new JWT       — stateless, touches api/*, ~1 slice
  B reuse session — fastest, keeps server state

STOP — a non-fork hard stop (gate red past retries, stuck loop):

GSD ▸ STOP ⏹  T07 gate red after 2 retries · need you
  last  AssertionError: expected 200, got 500 (api/profile.test.ts:31)

DONE — milestone closeout, the "you came back and it's done" report:

GSD ▸ DONE ════════════════════════════════════════════
verdict    PASS
shipped    S01 auth · S02 profile api · S03 ui
verify     full suite ✓ · 128 tests · lint ✓
reviewers  milestone: codex APPROVE · grok APPROVE
diff       42 files · +2110 −340   (git diff <base>..HEAD)
forks      3 resolved · 0 open
follow-up  —
────────────────────────────────────────────────────────
 crit │ status │ evidence
 R1   │ ✓      │ T71-VERIFY.md · cone within 12°
 R2   │ ✓      │ VALIDATION.md · 60fps on device
 R3   │ ✓      │ manual UAT
════════════════════════════════════════════════════════

(Verdict PARTIAL/FAIL uses the same block; unmet criteria show ✗ and follow-up lists what remains.)

RESUME — replaces INIT when re-invoked on an existing .gsd/. Same bordered frame and single-column layout as INIT; one label value per row (never two pairs on a line). Immediately followed by a BOARD so a returning user sees the whole slice landscape at a glance before the run continues:

GSD ▸ RESUME ══════════════════════════════════════════
milestone  <title> · <status>
at         <slice·task position> · <N built / M total tasks>
open fork  none               (else: F<NN> — blocks, resolve first)
next       <the single next action>
gates      <suite: pass/fail counts> · HEAD <sha>
═══════════════════════════════════════════════════════

GSD ▸ BOARD  3/8 slices · 9/20 tasks · ▸ S04
────────────────────────────────────────────────────────────
 S01 │ S02 │ S03 │ S04 │ S05 │ S06 │ S07 │ S08
  ✓  │  ✓  │  ✓  │ 2/3 │  •  │  •  │  •  │  •
────────────────────────────────────────────────────────────

Two knobs (pick in Phase 0)

Knob	Options	Default	Pick by
engine	inline · orchestrated	orchestrated	inline only for ≈1 slice / a handful of files; orchestrated once it's multi-slice or the repo is large
continuity	checkpoint · autonomous	autonomous	checkpoint pauses for a check-in after each slice; autonomous runs to completion and stops only for forks

The fire-and-forget large-project case is orchestrated + autonomous — assume this unless the user asks to be looped in per slice or the task is tiny. Both knobs are reported in the INIT readout (see Output protocol); you can escalate inline→orchestrated mid-run.

The orchestrator model (how large work stays in one context)

When engine: orchestrated, the main session never does the heavy lifting itself. It holds only the small, durable state and dispatches everything else:

Stays in the orchestrator's context — ROADMAP.md, STATE.md, FORKS.md, DECISIONS.md, and the compact return (frontmatter + a few lines) of each finished task. That's it.

Offloaded to subagents — repo exploration, reading source, writing code, running the verify gate, and reading verbose command output. Each subagent:

• gets a tight brief: the task/slice plan, plus pointers by path to the specific prior summaries it needs (.gsd/S01-SUMMARY.md, .gsd/T04-SUMMARY.md) — not the repo, not the transcript;
• writes its own artifacts directly to .gsd/ (it has Write access), so the orchestrator never has to hold file contents just to persist them;
• returns only a compact result: the T-SUMMARY frontmatter, a 2–4 line "what changed", the verify verdict + key evidence lines, and any fork it hit. The orchestrator discards the subagent's verbose working context.

So the rule is: the orchestrator reads state, not code. If you find yourself about to read a source file or paste command output into the main session, dispatch a subagent instead. This is the entire mechanism for completing a big project without blowing context.

Four stages, four fresh agents, all visible to the user. The pipeline is research → plan → build → verify, and each stage runs as its own subagent with its own fresh context — never one agent doing several stages. Critically, build and verify are different agents: the builder implements, then a separate verifier — which never saw the builder's reasoning — runs the gate against the result. Fresh eyes catch what the author rationalizes away (a builder that "knows" its code is correct tests it less honestly). Each stage is also surfaced as its own entry in the harness todo list (TaskCreate), so the user watches the run advance stage by stage and can see exactly where it is:

Stage	Agent	Produces
Research	Explore/Plan subagent	findings digest → .gsd/RESEARCH.md
Plan	Plan subagent	ROADMAP.md + S<NN>-PLAN.md (slices, tasks, deps)
Build	Agent per task	code + T<NN>-SUMMARY.md
Verify	fresh Agent per task	gate verdict → T<NN>-VERIFY.md

Inline engine (small work): the stages still happen in order and still each get a todo entry, but may run in the main context — except verify still gets a fresh subagent so the check stays independent of the build.

Parallelism is a first-class decision, not an afterthought. Independent tasks run concurrently by default — idling a task behind another it doesn't depend on wastes wall-clock the user is paying for. The orchestrator computes the dependency graph, finds the set of ready-and-independent tasks, and dispatches them together. See Parallel execution for the full mechanism.

Parallel execution — decide what runs concurrently

Sequential execution is the safe default, but it is rarely the right one. A gsd run often has whole slices and tasks that share no data and touch no common files — running them one-after-another just to keep things simple leaves the user waiting. The orchestrator's job is to actively find that concurrency and take it.

Model the plan as a dependency graph. Each task is a node; an edge A → B means B depends on A (B needs A's output, edits files A creates, or builds on a pattern A establishes). Two tasks are independent iff neither is reachable from the other. The graph comes straight from the deps you record in Phase 1 (slice-level and task-level) plus the key_files/affects each task declares.

A task is ready to dispatch when both hold:

1. Dependencies satisfied — every task it depends on is completed.
2. No file conflict — its declared key_files/affects don't overlap any task currently in_progress. Two tasks writing the same file must not run at once (last-write races, merge garbage) — either sequence them or give each its own git worktree (isolation: worktree) so their edits can't collide.

Execute in waves. At each step, compute the ready set (all ready tasks, across any slice — parallelism is not confined to a single slice) and dispatch the whole set in one message so the subagents run concurrently. As each returns and is marked completed, recompute the ready set and dispatch the next wave. This is a topological wavefront: the run is as parallel as the graph allows and never more.

How many at once. Cap concurrency at max_parallel_tasks (default 4). Prefer grouping tasks that are genuinely independent and cheap to verify; don't fan out so wide that a red gate in one forces you to unwind several. When in doubt about a shared-file risk, sequence those two and parallelize the rest.

Two ways to drive the waves:

• Default (manual fan-out): dispatch the ready set as multiple Agent calls in a single orchestrator message; collect their compact returns; recompute; repeat. Works with no special opt-in.
• Workflow (opt-in): if the user has asked for workflow orchestration ("ultracode" / "use a workflow"), drive a Workflow that pipeline()s the roadmap — it handles the wavefront, the concurrency cap, and worktree isolation for you. Use this for large graphs with many independent branches.

When not to parallelize — collapse to sequential for these:

• tasks that touch the same files and can't be cheaply worktree-isolated;
• a task whose result is likely to reshape the tasks after it (refine-then-execute beats guessing in parallel);
• engine: inline small runs, where the coordination overhead isn't worth it;
• when a red gate on one task should gate the others (tight coupling despite no file overlap).

Record the decision. In the roadmap, mark each task's deps and note which tasks form a parallel group (safe to run together). Before executing a wave, emit the WAVE dispatch readout (see Output protocol) naming the concurrent tasks by their canonical IDs.

Design forks — the only routine stop

A design fork is a decision that is genuinely the user's to make — so the autonomous run pauses, asks, records the answer, and continues. A choice is a fork when it is:

• materially divergent — the options lead to substantially different systems (a data model, an architecture, a public API shape, a core dependency/framework choice); or
• hard or expensive to reverse later; or
• outward-facing / irreversible in the world — sending, publishing, deleting, migrating prod data, spending money, anything the harness rules say to confirm; or
• an ambiguity in the goal itself that changes what gets built (not just how).

It is not a fork — decide it yourself and keep going — when it's an internal implementation detail with a sane default, a naming/structure choice, or an ambiguity you can resolve from the code, conventions, or success_criteria. Don't manufacture forks to offload ordinary judgment; the goal is a run the user can walk away from.

Surface forks early and batch them. During planning, list every fork you can foresee and resolve them in one round with the user: emit the FORK readout (Output protocol), then the AskUserQuestion call (up to 4 at a time), before execution starts — so the run then proceeds uninterrupted. Record each in FORKS.md (open → resolved) and mirror durable ones into DECISIONS.md.

When a subagent hits an unforeseen fork mid-run, it must not guess: it returns a blocked_on_fork result describing the options and consequences. The orchestrator writes the fork to FORKS.md, sets ROADMAP status: blocked_on_fork, and asks the user. On the answer, it records the resolution and re-dispatches the task with the decision baked in. Where possible, keep executing other independent tasks while one is fork-blocked rather than idling the whole run.

Phase 0 — Scope & setup

1. Restate the goal as success criteria. A few crisp, checkable statements ("GET /health returns 200 {status:"ok"}; existing tests pass"). These become the milestone's acceptance gate. Fold in the production bar — add the applicable bars (secure, rock-solid, production-ready, modern best practices, and UI/UX when a user-facing surface is in scope) as explicit R* criteria in REQUIREMENTS.md, marking any bar that genuinely doesn't apply as N/A with a one-line reason (see The production bar). If the request is ambiguous in a way that changes what gets built, that's a fork — raise it now, not mid-execution.
2. Pick the two knobs (engine, continuity) per the table above and report them, with the goal/criteria and reviewer (Codex/Grok) availability, in the INIT readout (Output protocol) — the first thing the user sees.
3. Ensure .gsd/ exists at the repo root (mkdir -p .gsd). In a non-git directory everything below still works except worktree isolation and the final diff review — sequence file-conflicting tasks and summarize changes by file instead. Read gsd.config if present (precedence: the user's live request > gsd.config > defaults). If .gsd/STATE.md already exists, this is a resume — jump to Resumability instead of replanning.
4. For a multi-slice run, settle commit cadence up front. Hours of autonomous work sitting as one uncommitted working tree is fragile — one stray reset loses everything. Add it to the Phase-1b batched fork round: propose a work branch with a commit per completed slice. If the user doesn't opt in, don't commit — never commit unasked.

Phase 1a — Research (its own task)

Research is a distinct, visible stage — add a "Research" todo entry and run it in its own Explore/Plan subagent (breadth "very thorough" for a large/unfamiliar repo). It explores the codebase with full tool access and returns only a findings digest, which it also writes to .gsd/RESEARCH.md; raw exploration stays out of the main context. Keeping research separate from planning means the planner works from a written, reviewable digest rather than from whatever happened to be in one agent's head.

Identify: where the work lives, existing patterns/utilities to reuse (avoid net-new code when something fits), constraints, risky unknowns, and candidate design forks. Mark the Research task completed once RESEARCH.md exists.

Phase 1b — Plan the whole project

Add a "Plan" todo entry and run planning in its own Plan subagent, fed the .gsd/RESEARCH.md digest by path. It turns research into the roadmap:

1. Decompose the entire project into slices → tasks — start to finish, not just the first slice. A large project has many slices; plan them all so the run can complete unattended.
   • A slice is a bounded, shippable unit of scope with a risk level (low/med/high) and explicit dependencies. Aim for 2–4 tasks per slice.
   • A task is one concrete implementation unit with explicit acceptance criteria, verification steps (the command that proves it), and the files it will touch (key_files/affects — used later to detect parallel-safety).
   • Number slices and tasks per Canonical conventions — S<NN> and global-monotonic T<NN>, never reset per slice — so deps: references and T<NN>-* filenames never collide.
   • Build the dependency graph. For every slice and every task, record its deps (what must finish first). A task with deps: none and no file overlap with its peers is independent. From these deps, identify the parallel groups — sets of tasks safe to run at once — and note them in the roadmap. This is the input the executor uses to run waves concurrently; getting it right in planning is what makes the run fast.
2. Surface and batch-resolve design forks with the user now (see above), so execution runs uninterrupted.
3. Write the plan artifacts from templates/: .gsd/ROADMAP.md (the spine — all slices, all tasks, deps, status), .gsd/S<NN>-PLAN.md per slice, .gsd/FORKS.md, and .gsd/REQUIREMENTS.md (the Phase-0 success criteria, each pending until validated).
4. Mirror the pipeline into the harness todo list (TaskCreate) as the live view, per regiment invariant 3 — for every task, a Build T<NN> — <title> entry and a separate Verify T<NN> — <title> entry (the verify entry is mandatory, never optional and never merged into build), plus the Research, Plan, and each external-review (Grok/Codex) entry. This holds for bugfix tasks exactly as for feature tasks. Emit the PLAN readout, then immediately the initial BOARD — every slice cell • — so the slice landscape is on screen before any build wave starts.
5. Progressive detail is allowed, full coverage is not optional. Every slice through completion must exist in the roadmap; you may leave distant slices' tasks sketched and refine each slice's tasks just before executing it, using what prior slice summaries taught you. Don't over-detail distant work that early findings may reshape — but don't leave the back half of the project unplanned either.
6. External plan review (if grok/codex are available), in this order. Once the roadmap exists and forks are resolved but before dispatching the first build wave:
   • 6a — Grok plan expansion (if grok available). Run grok.sh expand first to broaden the plan (web-informed): missing scope, alternative approaches, external risks, edge cases. Fold accepted PROPOSALS into ROADMAP.md/REQUIREMENTS.md/S<NN>-PLAN.md and sync the todo list; route any genuine design choice through the FORKS.md + AskUserQuestion flow; record rejections in DECISIONS.md. Add a visible "Plan expansion (Grok)" todo entry. Expand before Codex so Codex critiques the enriched plan.
   • 6b — Codex plan review (if codex available). Then get an independent critique of the (now-enriched) plan. Add a visible "Plan review (Codex)" todo entry. See Independent review checkpoints for the calls and how to act on each result. Skip either silently if its skill is absent.

Phase 2 — Execute (wavefront, orchestrated)

Execution is driven by the ready set, not a fixed task order. Repeat until the roadmap is done:

0. Compute the ready set (see Parallel execution): every task whose deps are all completed and whose key_files don't overlap any currently in_progress task. If more than max_parallel_tasks are ready, take the highest-leverage subset (unblocks the most downstream work); sequence the rest. Dispatch the whole ready set in a single orchestrator message so its subagents run concurrently. A ready set of one is just the sequential case — same machinery.

For each task in the wave:

1. Refine the slice if its tasks are still sketched (just-in-time detail).
2. Mark the task in_progress in the todo list and STATE.md (do this for the whole wave before dispatching, so file-conflict detection sees them as claimed).
3. Dispatch the build subagent with a tight brief: the task plan, the slice context, and paths to the prior summaries it needs — never the whole repo. Instruct it to: implement (matching surrounding style/idioms, reusing researched utilities, building to the production bar — secure, rock-solid, production-ready, current best practices, and well-designed UI/UX where the task touches a user-facing surface, invoking the relevant design/security skills — and honoring the user's global and project instructions — CLAUDE.md and any house-standard skills they mandate); record non-obvious patterns/gotchas and durable decisions in its own T<NN>-SUMMARY.md (frontmatter + notes) — builders never write the shared KNOWLEDGE.md/DECISIONS.md (two concurrent appenders corrupt them; the orchestrator merges at slice rollup); and return only the compact summary, or a blocked_on_fork report. The builder does not run the gate — that's Phase 3, a separate agent. Inline engine: implement in the main context, but still hand verify to a fresh subagent.
4. A task is not done without its summary — the T-SUMMARY frontmatter (provides/requires/affects/key_files/key_decisions/patterns_established) is what later tasks and the rollup aggregate.
5. On a build's green return, dispatch its Phase-3 verifier (fresh agent) before marking the task done. Move the verify todo entry to in_progress.
6. On a blocked_on_fork return: handle per "Design forks" — record, ask, resolve, re-dispatch; meanwhile keep the rest of the wave (and any other independent tasks) moving.
7. When a task's verify passes, mark it completed and recompute the ready set — its completion may unblock new tasks that join the next wave. Don't wait for the whole wave to finish before dispatching newly-ready work if slots are free.

File-collision safety. The executor must never run two tasks that write the same file at once. If the graph makes that unavoidable (both are ready, both touch config.ts), prefer sequencing them — cheap and always correct. Worktree isolation (isolation: worktree) is the fallback when sequencing would idle too much, and it is only half the job: each agent's changes land in its own worktree, so the orchestrator must dispatch an explicit merge-back step and re-verify after the merge. A task whose changes sit in an unmerged worktree is not done. When unsure whether two tasks conflict, treat them as conflicting.

Phase 3 — Verify gate (fresh agent, per task)

The gate is mechanical and non-optional — a red gate blocks task completion. It runs in its own fresh subagent, separate from the builder (its own todo entry). The verifier is handed the task's acceptance criteria and verification steps plus the paths to T<NN>-SUMMARY.md and the changed files — but not the builder's reasoning. That independence is the point: an agent that didn't write the code won't wave through the case the author was sure couldn't happen. Only the verdict + key evidence lines return to the orchestrator.

1. Run the verification commands (lint, type-check, tests, build) — from gsd.config if present, else auto-detected (see Configuration). Run what's relevant to the task plus the project's test suite. Where the acceptance criteria describe observable behavior, exercise it (drive the flow, hit the endpoint), don't just trust that tests cover it. Scope the gate to the task while a wave is in flight: if other builders are mid-edit in the same working tree, a project-wide suite run fails on their half-written work and produces false reds — so during a wave the verifier runs the task's own verification commands (its tests, lint/type-check on its files), and the full suite runs once the tree is quiescent (wave drained or slice complete) as the slice's exit gate. Solo tasks get the full treatment immediately. 1a. Check the production bar for what this task touched (regiment invariant 7). Beyond the commands passing, the verifier confirms the applicable bars actually hold for the diff: inputs validated / no injectable sinks / no leaked secrets (secure); error and edge paths handled, not just the happy path (rock-solid); no debug scaffolding, dead code, or hard-coded config left in the diff and docs kept in sync (production-ready); current, non-deprecated idioms and deps (best practices); and — if a UI surface changed — responsive, accessible, all states (loading/empty/error) handled and visually coherent, not a wireframe (UI/UX). A bar that's in REQUIREMENTS.md but unmet is a red gate, handled by the same fix→re-verify loop as a failing test.
2. On failure: report it back. The verifier writes the red evidence and returns fail; the orchestrator re-dispatches the build agent with that output to fix, then verifies again — up to verification_max_retries (default 2). A red gate is not a fork — fix and keep going; do not advance on red. (Keeping fix-work in the builder and judgment in the verifier preserves the independence; a verifier that both patches and blesses its own patch is back to marking its own homework.)
3. Write .gsd/T<NN>-VERIFY.md — commands, exit status, verdict (pass/fail), evidence (key output lines).
4. Atomic completion: only after the summary and an independent pass verdict are written do you mark the task completed (todo + ROADMAP). If a write fails, revert to pending and retry — never leave a half-completed task marked done.

Phase 4 — Slice completion & the autonomous loop

When every task in a slice passes its gate:

1. Run the slice exit gate if any wave deferred it — the full verification suite on the now-quiescent tree (fresh subagent, as always). A red here means an interaction between tasks that each passed alone; fix via the normal build→verify retry loop before closing the slice.
2. Aggregate task summaries into .gsd/S<NN>-SUMMARY.md (roll up the frontmatter), and merge each task's patterns_established/key_decisions (from the compact returns you already hold) into .gsd/KNOWLEDGE.md and .gsd/DECISIONS.md — the orchestrator owns those files, builders never touch them.
3. Update .gsd/REQUIREMENTS.md (mark covered criteria validated).
4. External code review of the slice diff (if codex/grok are available), both in parallel. With the tree quiescent, get independent reviews of what this slice changed against its goal + acceptance criteria — Codex for correctness/regressions/quality and Grok for security/dependency-currency/fresh-eyes bugs (complementary lenses, not a duplicate). This runs for every slice — bugfix and refactor slices included, not only feature slices (regiment invariant 5). Add a per-slice todo entry for each that runs: "Code review (Codex): S<NN>" and "Code review (Grok): S<NN>". See Independent review checkpoints. Merge + dedupe findings across the two; valid ones are fixed via a fresh build subagent + re-verify (keep judgment in the orchestrator, edits in a builder); both are advisory, so don't loop — log residual disagreement and proceed. Skip either silently if its skill is absent.
5. Mark the slice done in ROADMAP.md; update STATE.md. Emit the SLICE readout and, immediately after it, the updated BOARD (see Output protocol) — this pairing is mandatory at every slice close so the user sees, without scrolling, which slices are now done and which remain.
6. Reassess the roadmap silently. Given what this slice taught you, do remaining slices still make sense? Reorder / add / drop as needed and log it in the reassessment log.
   • continuity: autonomous — keep going to the next slice without stopping. Only surface something if the reassessment reveals a new fork or a material scope change the user should know about (no silent scope drift on the big stuff; ordinary refinements just get logged).
   • continuity: checkpoint — after the step-5 SLICE+BOARD pairing, pause for the go-ahead.

When all slices are done (milestone closeout):

1. UAT / validation pass (in a subagent): check delivered work against the Phase-0 success criteria including the production-bar R* criteria (secure, rock-solid, production-ready, best practices, UI/UX where applicable), re-run the full verification suite, and — for a user-facing surface — exercise it across states and viewports rather than trusting the build. Record a verdict (PASS/PARTIAL/FAIL) with per-criterion evidence in .gsd/VALIDATION.md; an unmet production-bar criterion is a ✗ like any other.
2. Write the milestone .gsd/SUMMARY.md (what shipped, key decisions, patterns, follow-ups).
3. Final external code review (if codex/grok are available), both in parallel — one review each of the whole milestone against the Phase-0 success criteria (Codex = correctness, Grok = security/deps). Add a visible "Code review (Codex): milestone" and/or "Code review (Grok): milestone" todo entry for whichever runs. See Independent review checkpoints; the slices are usually committed by now, so pass the committed-range base (CODEX_DIFF_BASE / GROK_DIFF_BASE). Fold any COMMENTS into the closeout report and follow-ups. Skip either silently if its skill is absent.
4. Surface the final result in the DONE readout (Output protocol): verdict, shipped slices, per-criterion status, verify + reviewer (Codex/Grok) results, the diff stat (from git diff/git status), and open forks/follow-ups. A non-PASS verdict shows the unmet criteria as ✗ and lists what remains in follow-up. This is the "you came back and it's done" report.

Independent review checkpoints (optional)

If a codex and/or grok skill is available, GSD uses them as independent second opinions — divided by role, not duplicated. It is purely additive and advisory — neither reviewer gates completion; the mechanical verify gate (Phase 3) stays the only hard gate. Adopt valid findings, briefly note what you reject with a reason, and keep going. The two are independent: whichever skill is absent is simply skipped; if neither is present, skip all of this silently.

The role split (why two reviewers, not the same review twice):

• Plan seam — Grok expands first, then Codex critiques. Grok is web-enabled, so it broadens the plan with outside knowledge (missing scope, alternative approaches, outdated/ insecure deps, current best practices) before Codex evaluates the enriched plan for internal soundness/executability. Expand before you converge.
• Code seam — Codex and Grok run in parallel as complementary lenses. Codex judges correctness / regressions / quality; Grok judges security / dependency-currency (web-checked) / fresh-eyes bugs. Merge their findings and dedupe where they overlap (fix once).

Every review is its own user-visible todo entry (TaskCreate), created before it runs and closed after — never a silent background step. Canonical names: Plan expansion (Grok) and Plan review (Codex) at the plan seam; Code review (Codex): S<NN> and Code review (Grok): S<NN> per slice; Code review (Codex): milestone and Code review (Grok): milestone at closeout. This is part of regiment invariant 3 (the todo list mirrors the pipeline exactly).

Report the findings in a CODEX / GROK readout, one row per item — all of them. Every finding is surfaced: index, severity (✗ blocker / ⚠ minor / ℹ nit) — or a tag for a Grok expansion — a one-line summary, its file:line, and the disposition you gave it (→ applied / → rejected:<why> / → fix T<NN> / → fork F<NN> / → noted). Never compress them into "a few minor comments" or drop the nits — the whole point is that the disposition of each item is visible. The verdict/summary line carries the count (COMMENTS(4), WEAKNESSES(3), PROPOSALS(2)); a clean pass and an unavailable/skipped reviewer are each still a one-line block. See the CODEX / GROK templates in Output protocol.

Detecting availability. Each reviewer skill appears in the available-skills list — the companion codex and grok plugins in this marketplace provide them. Their drivers are the codex.sh (modes plan/code) and grok.sh (modes expand/plan/code) bundled with those plugins; the commands below write bare codex.sh / grok.sh for brevity — substitute the bundled path (each plugin installs its driver at its own ${CLAUDE_PLUGIN_ROOT}) or follow that skill's own instructions to invoke it. Every call is best-effort: a missing CLI, out-of-quota, or timeout prints a note and yields no verdict — log "<reviewer> review skipped" and continue. <root> below = the GSD project root (where .gsd/ lives).

Plan seam — after Phase 1b, before the first build wave

1. Grok expansion (first). Broaden the plan with web-informed proposals:

grok.sh expand "$ROOT"

(same .gsd/ auto-discovery as below). PROPOSALS: NONE → note and proceed. PROPOSALS(n) → for each, fold the valid ones into ROADMAP.md/REQUIREMENTS.md/S<NN>-PLAN.md and sync the todo list (disposition → applied); route any genuine design fork through FORKS.md + AskUserQuestion; record rejections in DECISIONS.md. Then run Codex over the enriched plan.

2. Codex plan review (then). Over the plan artifacts:

codex.sh plan "$ROOT"

(auto-discovers RESEARCH.md/REQUIREMENTS.md/ROADMAP.md/FORKS.md/S*-PLAN.md under .gsd/). Verdict SOLID → note and proceed. WEAKNESSES → apply the valid points (edit ROADMAP.md/S<NN>-PLAN.md/REQUIREMENTS.md and sync the todo list), record deliberate rejections in DECISIONS.md, route any genuine design fork through FORKS.md + AskUserQuestion. Re-run once to confirm at most; stop after two rounds and log residual comments. Then continue into Phase 2.

grok.sh also has a symmetric plan mode (SOLID/WEAKNESSES) as a drop-in alternative critic. GSD deliberately uses expand for Grok here — Codex already owns the critique, so Grok's job is to broaden, not to grade the same plan twice.

Code seam — per slice (Phase 4) and at milestone closeout

Once a slice is fully green and the tree is quiescent, run both reviewers over its diff (in parallel). Same instruction + file list for both:

# instruction = the slice's goal + acceptance criteria
printf '%s\n' "<slice goal + acceptance criteria>" > /tmp/gsd-review-instr.md
# files = the slice's changed files — prefer the exact union of key_files/affects from the
# slice's task summaries. If deriving from git instead, include NEW untracked files too
# (plain `git diff --name-only` misses them):
#   { git -C "$ROOT" diff --name-only; git -C "$ROOT" ls-files --others --exclude-standard; } \
#     | sed "s#^#$ROOT/#" | sort -u > /tmp/gsd-review-files.txt
printf '%s\n' "$ROOT/path/changed1.ext" "$ROOT/path/changed2.ext" > /tmp/gsd-review-files.txt
codex.sh code "$ROOT" /tmp/gsd-review-instr.md /tmp/gsd-review-files.txt   # correctness
grok.sh  code "$ROOT" /tmp/gsd-review-instr.md /tmp/gsd-review-files.txt   # security/deps

Both APPROVE → close the slice. Any COMMENTS → merge + dedupe the two reviewers' findings, fix the valid ones via a fresh build subagent, re-run the verify gate, optionally re-review; don't loop indefinitely — after one fix round, log any residual disagreement and proceed.

At milestone closeout: run one final code review from each reviewer where the instruction is the Phase-0 success criteria and the file list is the whole milestone's changed files. By closeout the slices are usually committed, so git diff HEAD is empty — set the per-tool base var so the review diffs the milestone against its base, and build the file list from that committed range:

git -C "$ROOT" diff --name-only <base-commit>..HEAD | sed "s#^#$ROOT/#" > /tmp/gsd-review-files.txt
CODEX_DIFF_BASE=<base-commit> \
  codex.sh code "$ROOT" /tmp/gsd-review-instr.md /tmp/gsd-review-files.txt
GROK_DIFF_BASE=<base-commit> \
  grok.sh  code "$ROOT" /tmp/gsd-review-instr.md /tmp/gsd-review-files.txt

Fold COMMENTS from either into the closeout report and, if material, into follow-ups.

.gsd/ artifact layout

The todo list is the live view; .gsd/ is the durable, git-friendly record and the source of truth for resuming.

File	Role
RESEARCH.md	Phase-1a findings digest the planner builds on (where work lives, reusable patterns, unknowns)
ROADMAP.md	All slices with id/title/risk/deps/status + task breakdown — the spine
STATE.md	Current position: active slice/task, open forks, what's next (read first on resume)
FORKS.md	Design forks — open (blocking) and resolved (with the user's choice)
S<NN>-PLAN.md	Per-slice task plans with acceptance + verification steps
T<NN>-SUMMARY.md	Per-task: what changed + frontmatter for aggregation (required)
T<NN>-VERIFY.md	Per-task gate result: commands, verdict, evidence
S<NN>-SUMMARY.md	Per-slice rollup of its task summaries
KNOWLEDGE.md	Patterns discovered + lessons/gotchas (orchestrator-owned; merged from task summaries at slice rollup)
DECISIONS.md	Durable architecture/design decisions (orchestrator-owned; same merge path)
REQUIREMENTS.md	Success criteria and their validation status
VALIDATION.md	Milestone UAT verdict vs. success criteria
SUMMARY.md	Milestone closeout summary

Whether .gsd/ is committed, gitignored, or kept local follows the repo's existing rules and the user's instructions. When reporting what a commit included, check what git actually staged rather than assuming.

Configuration

Optional .gsd/gsd.config (YAML) — read if present, otherwise inferred:

verification_commands:      # what the gate runs; auto-detected if omitted
  - npm run lint
  - npm test
verification_max_retries: 2 # auto-fix attempts before stopping on a red gate
verification_auto_fix: true
artifact_dir: .gsd          # where artifacts live
engine: orchestrated        # orchestrated | inline
continuity: autonomous      # autonomous | checkpoint
max_parallel_tasks: 4       # max independent tasks per wave; 1 forces fully sequential

Auto-detection when verification_commands is unset — pick what the repo actually has: package.json scripts (lint, test, typecheck, build via npm/pnpm/yarn); pytest / ruff (Python); go test ./... / go vet (Go); cargo test / cargo clippy (Rust); a Makefile test/check target; PHPUnit / composer test (PHP). If nothing is detectable, say so and ask how to verify rather than skipping the gate.

Guardrails (from gsd-pi auto-mode)

• Fresh context per task — never carry one task's working state into the next; that's what the per-task subagent guarantees.
• Verify with a different agent than built — the gate always runs in a fresh subagent that never saw the builder's reasoning. Never let a builder bless its own work; independent eyes are what catch the errors the author is blind to. The build agent fixes red gates; the verify agent decides pass/fail.
• Every stage is visible — research, plan, build, and verify each get their own todo entry so the user can watch the run advance and knows exactly where it stands. Per task this is always two entries, Build T<NN> and Verify T<NN> — the verify entry is never dropped or merged (regiment invariant 3).
• One path for all change — bugfixes, refactors, and chores are decomposed into slices/tasks and run through build → verify → review exactly like features; the orchestrator never side-channels a direct edit (regiment invariant 1, Mixed runs).
• Speak only in readouts — user-facing output is the fixed Output protocol blocks (INIT/RESEARCH/PLAN/ BOARD/WAVE/CODEX/SLICE/FORK/STOP/DONE), same every run, with no connective prose between them and no announcing intent or narrating silent steps. Reads and dispatches are silent; long steps show a ⧗ running line. Every Codex finding is listed with its disposition. The only non-readout text in a run is an AskUserQuestion body.
• Always show the slice board — the BOARD strip is mandatory after PLAN (all pending), immediately after every SLICE close, and after RESUME. It carries one aligned cell per slice (✓ done · n/m in progress · • pending · ⏸ fork · ⏹ stopped) so the user reads where the run stands in one glance — no scrolling back, no re-reading slices. Never skip it at those moments and never abbreviate it to a subset of slices.
• Orchestrator reads state, not code — dispatch a subagent rather than pulling source or command output into the main session. This is what lets a large run finish in one context.
• Context-pressure wrap-up — if the orchestrator's own context ever gets full (~70%), stop cleanly: persist the current task's summary and update STATE.md so the run resumes from there. With proper offloading this should be rare.
• Stuck detection — if a task's gate is still red after verification_max_retries fix attempts, or you're looping (fix A breaks B breaks A), stop that task and ask the user instead of burning turns — but keep independent tasks moving meanwhile, same as a fork block. A persistent red gate is not a fork but it is a stop.
• Full-suite runs need a quiescent tree — never run the project-wide suite while builders are mid-edit in the same tree; task-scoped checks gate tasks inside a wave, the full suite gates the slice.
• Don't guess a fork — a subagent that hits a genuine design fork returns blocked_on_fork; it never picks arbitrarily and marches on.
• Atomic completion — persist summary + verify evidence before marking done; revert to pending on any write failure.
• No silent scope drift — log every reassessment; announce new forks and material scope changes even in autonomous mode.
• Parallelize the independent, isolate the conflicting — run the ready set concurrently to save wall-clock, but never let two concurrent tasks write the same file; sequence them or give each a worktree. Concurrency is for independent work, not a way to rush coupled changes.
• Clear the production bar, every run — the delivered work is secure, rock-solid, production-ready, on current best practices, and (for any user-facing surface) genuinely well-designed. These are R* criteria in REQUIREMENTS.md, briefed into the builders, checked at the verify gate, and confirmed at milestone validation — not end-of-run polish. "It compiles / the happy path works" is not done (regiment invariant 7, The production bar).

Resumability

On re-invoke in a repo that already has .gsd/: silently read STATE.md, FORKS.md, and ROADMAP.md in one batched set of tool calls (no narration, no "let me read…" between them — see the silent-orchestrator rule at the top) to derive the active slice/task and any open (blocking) fork; don't replan from scratch. The first text the user sees is the RESUME readout (not INIT, and not a "this is a resume" sentence) — emit it right after those silent reads so the user sees where it picked up. If a fork is open, resolve it (FORK readout → AskUserQuestion) first. Immediately after the RESUME readout, emit the BOARD (built from ROADMAP status) so the returning user sees the whole slice landscape — done, active, remaining — at a glance. Otherwise re-hydrate only the relevant S<NN>-SUMMARY.md/T<NN>-SUMMARY.md by path (not the repo), rebuild the todo list from ROADMAP status, and continue at the first not-done task — resuming the autonomous loop with the normal protocol blocks.

How gsd-pi concepts map here

gsd-pi	Here
milestone → slice → task	Phase-0 goal → ROADMAP slices → tasks (todos + S/T files)
auto-mode (runs unattended)	continuity: autonomous — runs to completion, stops only for forks
research-codebase session	Phase-1a Explore/Plan subagent → RESEARCH.md (its own visible task)
plan-milestone session	Phase-1b Plan subagent → ROADMAP.md (its own visible task)
execute-task session (fresh context)	per-task build Agent (orchestrated), or inline for small work
verify-gate (mechanical)	separate per-task verify Agent, fresh context → T<NN>-VERIFY.md
human-decision / escalation	design fork → FORKS.md + AskUserQuestion
SQLite state authority	.gsd/STATE.md + .gsd/ROADMAP.md + the harness todo list
reassess-roadmap	Phase-4 between-slice reassessment (silent in autonomous mode)
UAT + validate-milestone	Phase-4 validation pass → VALIDATION.md
HTML report	Final diff review + SUMMARY.md message

Commit guidance

Only commit when the user asks — or on the cadence they opted into in Phase 0.