BriarForge/dev-grill-spec-driven

Grill, then spec-driven development

Two workflows, run back to back, with one hand-off between them:

1. Grill (Matt Pocock, grill-me → to-spec): interview the user as a design tree, round by round, until nothing is silently assumed. Then synthesise the agreed understanding into a spec without asking anything new.
2. Build (DeepLearning.AI + JetBrains, Spec-Driven Development with Coding Agents): the spec lands in the repo as requirements.md, plan.md and validation.md under a dated directory, is implemented task group by task group on its own branch, validated against validation.md, recorded in the changelog, merged, and the roadmap is replanned.

The grill replaces the SDD course's fixed three-question interview (Scope / Decisions / Context) with a full design-tree interview. The SDD course replaces to-spec's "publish to the issue tracker" with spec files that live beside the code and change with it.

Overview

Use when a change is big enough that writing it down first is cheaper than rework: a new feature, a roadmap phase, an MVP sprint, or adding SDD to a legacy codebase. Skip it for one-line fixes, and for pure bug hunts (use pstack-engineering for root causes).

Trigger phrases: "grill me then spec it", "grill to spec", "spec-driven", "SDD", "feature spec", "work on the next phase", "start the next feature".

Hard gates (never skip):

• No spec file is written until the user confirms the grill reached shared understanding (Gate A).
• No code is written until the user has approved the spec files (Gate B).
• Nothing is merged until every item in validation.md passes (Gate C).

Execution Instructions

Resolve SPECS=${SDD_SPECS_DIR:-specs} and BASE=${SDD_BASE_BRANCH:-<repo default branch>} at the start. Paths below are relative to the project root.

Stage 0 — Orient (facts are your job)

1. Read the project's AGENTS.md / CLAUDE.md, README.md, and any glossary or ADRs. Follow the repo's own git rules (wrappers, branch naming, no force-push).
2. Check for a constitution: $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
   • All present → go to Stage 1 for the next feature.
   • Missing, new project → the first grill is about the constitution itself (mission, target audience, tech stack gaps). Its output is the three files, with roadmap.md split into very small phases, each independently shippable.
   • Missing, existing codebase (legacy) → explore the code first and draft the constitution from what is actually there (stack, conventions, shipped features as completed phases), then grill only the gaps and the future roadmap.
3. If the user did not name a feature, the target is the next phase: the first roadmap section whose items are all unchecked ([ ]).
4. Explore the code that the feature will touch. Never ask the user a question the repo, tools or docs can answer. Delegate wide exploration to a fresh sub-agent if the harness has one, and don't block unrelated questions on it.

Stage 1 — Grill (design-tree interview)

Interview the user relentlessly until shared understanding. Treat the plan as a design tree: every decision branches into the decisions that depend on it.

• Work in rounds. The frontier is every open decision whose prerequisites are already settled. Ask the whole frontier in one round, then wait.
• Number each question and give your recommended answer. Word it so "yes" accepts the recommendation.
• A question that depends on another question still open this round belongs to a later round.
• Cover, across rounds, at least the SDD axes: Scope (what it collects, exposes, does; data shape), Decisions (storage, visibility, validation, UX pattern, architecture), Context (tone, constraints, stack limits, open questions), and Testing seams: where the feature will be tested. Prefer existing seams and the highest seam possible; the ideal is one.
• New dependencies, schema changes and public API changes are always explicit questions, never assumptions (tech-stack.md is the authority).

Round format:

❓ **Q1** - **<title>**: <question, options if any>

➡️ <recommended answer>

---

❓ **Q2** - ...

If the harness has a structured question tool (Claude Code AskUserQuestion), you may use it for rounds of up to four multiple-choice questions; otherwise use the text format above.

The grill ends when the frontier is empty. Summarise the settled decisions in a short list and ask the user to confirm.

Gate A: do not continue until the user confirms the summary.

Stage 2 — To spec (synthesis, no new questions)

Turn the conversation into the spec. Do not interview again; if a real gap appears, it means the grill missed a branch: ask only that one question, then resume.

1. Create the branch from $BASE: phase-<N>-<kebab-name> for a roadmap phase, otherwise feature/<kebab-name> (or the repo's own convention).
2. Re-read $SPECS/mission.md and $SPECS/tech-stack.md, and existing feature specs for house style.
3. Create $SPECS/YYYY-MM-DD-<feature-name>/ with today's date and write the three files from references/spec-templates.md:
   • requirements.md — the to-spec content (problem, solution, an extensive numbered list of user stories, implementation decisions, testing decisions, out of scope) plus the SDD Scope / Decisions / Context sections. No file paths or code snippets, except a trimmed prototype snippet that pins a decision more precisely than prose.
   • plan.md — numbered task groups, each independently implementable and testable, with numbered sub-tasks.
   • validation.md — automated checks (exact commands), manual walkthrough, edge cases, tone check for user-facing copy, and a Definition of Done.
4. Optional, if the user asks or the repo tracks work in issues: also publish the requirements as an issue (gh issue create) and link it from requirements.md.
5. Show the user the three files (paths plus a short digest).

Gate B: wait for approval. Feedback ("add a task group for X", "components go in their own files") is applied to the spec first, and every file kept in sync.

Stage 3 — Implement

1. Implement task groups in order. After each group: run the project's tests and typecheck, commit with a message naming the group, tick its boxes in plan.md.
2. If implementation shows the spec was wrong or incomplete, update the spec in the same commit as the code that departs from it. Specs and code never drift.
3. Groups with no dependency on each other may go to parallel sub-agents (each in its own worktree; follow the host's worktree rules), merged back by you.
4. No new dependencies without the user's approval, even if a group "needs" one.

Stage 4 — Validate

1. Run every automated check in validation.md and paste the real output.
2. Walk the manual checks (for a UI, actually drive it: browser automation or screenshots, not "should work").
3. Optional deep review: spawn reviewers from three perspectives (correctness, spec conformance, maintainability) over the branch diff, then fix what holds up.
4. Ask the user whether the spec needs clarifying in light of what was built.

Gate C: every Definition-of-Done item passes, or the user explicitly waives one (record the waiver in validation.md).

Stage 5 — Close the loop

1. Mark the phase complete in $SPECS/roadmap.md ([x]).
2. Update CHANGELOG.md (# Changelog, ## YYYY-MM-DD headings newest first, one bullet per meaningful change since the last recorded date). Use a project changelog skill if one exists.
3. Commit, switch to $BASE, merge the branch, delete it, push per the repo's rules.
4. Replan: ask whether anything learned changes mission.md, tech-stack.md or the roadmap (merge, split or reorder phases). Cross-cutting decisions (e.g. "use Vitest", "responsive UI") go into tech-stack.md / mission.md and are back-ported to existing specs.
5. Offer the next phase: it starts again at Stage 1.

Environment Variables

Variable	Default	Description
SDD_SPECS_DIR	specs	Constitution and feature-spec directory, relative to the project root
SDD_BASE_BRANCH	repo default branch	Branch features are cut from and merged into

Verification Checklist

• Constitution exists (mission.md, tech-stack.md, roadmap.md) before any feature spec
• Every grill question was asked with a recommended answer; no fact was asked that the repo could answer
• User confirmed the decision summary (Gate A) before any spec file was written
• requirements.md, plan.md, validation.md exist under $SPECS/YYYY-MM-DD-<name>/ on a feature branch
• User approved the spec (Gate B) before code was written
• Every task group committed with tests passing; plan boxes ticked
• Spec updated wherever implementation departed from it
• All validation.md checks run with real output (Gate C)
• Roadmap phase ticked, changelog updated, branch merged and deleted
• Replanning question asked

Known Pitfalls

• Grilling forever. The grill ends when the frontier is empty, not when you run out of curiosity. Don't re-ask settled decisions; don't ask about details that belong in code review.
• Interviewing in to-spec. Stage 2 synthesises; new questions there mean the grill was incomplete. Ask the one missing question, not a second interview.
• Writing before Gate A/B. The SDD course is explicit: nothing goes to disk until the interview is answered. Code before spec approval defeats the method.
• Phases too big. A phase that can't be reviewed in one sitting should be split in the roadmap before speccing.
• Spec drift. A change requested mid-implementation is applied to the spec first, then the code. A spec that no longer matches the code is worse than none.
• File paths in requirements. They rot fast; describe modules and interfaces instead (paths belong in plan.md sub-tasks at most).
• Repo rules win. Branch names, push wrappers, worktree locations and attribution rules from the repo's AGENTS.md override the defaults here.

See references/spec-templates.md for the file templates and references/sources.md for where each part came from.