Sdd

sdd — the rsc Spec-Driven Development dispatcher

The front door for building software the rsc way: intent in, shipped-and-verified software out, with the spec, plan and decisions recorded into the project's living knowledge model as you go.

sdd is the engineering counterpart of the harness. The harness runs the chaos → knowledge loop (inbox → 02-DOCS wiki). sdd runs the intent → shipped software loop, and it writes the artifacts of that loop — constitution, specs, plans, decisions — into the same 02-DOCS/wiki/sdd/ so the project's knowledge grows with every feature instead of leaking into chat history.

This skill does not do a phase itself. It is the dispatcher: it names the method, reads how much accompaniment you want, tells you which phase you are in, and hands off to the phase skill that owns the work. Each phase skill, when it finishes, points you at the next one — so once you enter the chain you rarely come back here.

The method in one breath

Spec-Driven Development (SDD, GitHub Spec Kit lineage) says: decide what and why before how, write it down, and let each written artifact gate the next step. You do not jump from a sentence in chat to a pull request. You move through ordered phases, each producing a durable artifact that the next phase reads. The payoff is that the intent is reviewable before any code exists, drift is caught at a gate instead of in production, and the whole thing is legible to the next person (or the next session) because it lives in 02-DOCS, not in a scrollback.

If you only remember one rule: the artifact is the contract. Code is checked against the plan, the plan against the spec, the spec against the constitution. When they disagree, you fix the disagreement before writing more code — you do not let the code silently win.

Step zero: calibrate the SDD runtime

Before the first non-trivial feature in a repo, run ../sdd-init/SKILL.md. It detects the stack, package manager, test runners, scripts, monorepo signals and review budget, refreshes .rsc/skill-registry.json, and writes:

02-DOCS/wiki/sdd/config.yaml

If config.yaml is missing and the request is more than a tiny one-line change, route to sdd-init before specify. This is not the same as init: init profiles the user/workspace; sdd-init calibrates the technical SDD runtime.

The chained phase map

The canonical chain runs left to right. Solid arrows are the default path; you move forward when the current phase's exit gate passes.

constitution ─(once per project)─┐
                                 ▼
   sdd-init ─(once per repo/runtime)─┐
                                     ▼
   proposal? ─► specify ─► clarify ─► plan ─► tasks ─► analyze ─► implement ─► verify ─► review ─► ship ─► archive
                                                         ▲
                                          on demand ─────┴─────────────────────
                                          debug · worktrees · parallel

The Tier column is the default model tier each phase routes to when per-phase model routing is enabled — see "Per-phase model routing" below. It is off by default and changes nothing about the chain or the gates; it only decides which model does the work.

If a phase skill above does not yet exist in this repo, the chain still holds — do that phase's work inline following the method here, and skip the broken handoff. Never invent a sibling that is not installed.

The invoke rule — route to the phase that fits

When a request lands, do not start typing code. Place it on the map first, then invoke the phase skill that owns it.

The new-feature gate (hard). The moment the user is thinking about a new feature or change — "add…", "build…", "it should also…", "quiero añadir…" — it goes to specify first, even if a stack skill (nextjs/fastapi/flutter/react…) also fired and could just build it. No feature code is written — by any skill — until a spec AND a plan exist and the user has approved them. A stack skill about to build an unspec'd, non-trivial feature must stop and route here. The only exception is a genuinely one-line, low-risk change; name it and skip.

1. No 02-DOCS/wiki/sdd/config.yaml and this is non-trivial? → sdd-init.
2. No constitution yet AND this project will grow? → constitution once, then come back to the chain.
3. Ambiguous / architectural / risky change before spec? → optional proposal artifact via specify.
4. A new idea, fuzzy, no spec on disk? → specify.
5. A spec exists but feels risky / has open questions? → clarify.
6. A clarified spec, no technical plan? → plan.
7. A plan with no task breakdown? → tasks.
8. Tasks exist, about to code, want a safety check? → analyze.
9. Green light to build? → implement (it embeds strict TDD from config and calls parallel/worktrees when useful).
10. Code written, claiming it works? → verify, then review, then ship/archive.
11. Something is broken mid-flight? → debug, then resume where you were.

If you genuinely cannot tell which phase you are in, ask the user one question: "Do we have a written spec for this yet?" The answer puts you before or after specify, and the rest follows.

Skip rules (be honest about them)

• A one-line, low-risk change (typo, copy tweak, config bump) does not need the full chain. Say so, do it, and verify. The method serves shipping, not ceremony.
• constitution runs once per project, not per feature. If 02-DOCS/wiki/sdd/constitution.md exists, read it as guardrails and move on.
• clarify and analyze are gates, not paperwork. If a spec is genuinely unambiguous and tiny, name that out loud and pass through — but the bias is to run them, because skipped gates are where drift hides.

Autopilot mode — run the whole chain on one up-front yes

By default the chain pauses at its gates (spec approval, plan approval). Autopilot trades those per-phase stops for a single up-front consent: the user says "take it all the way" once, and the chain runs specify → clarify → plan → tasks → analyze → implement → verify → review end to end without asking to continue between phases — still writing every artifact (spec, plan, decisions) to 02-DOCS/wiki/sdd/ as it goes, so the work stays reviewable after the fact.

How it turns on:

• specify offers it at the brainstorm boundary ("¿lo llevo hasta el final yo solo, o paramos en cada fase?"). A yes engages autopilot for this feature.
• Or set sdd.autopilot: true in 02-DOCS/wiki/sdd/config.yaml to default it on (still surfaced once per feature).

The up-front yes IS the gate. It satisfies the new-feature gate's "spec + plan approved before code" — approval was granted in advance, for the whole run. Do not re-ask phase by phase.

Autopilot still STOPS for these — not "continue?" nags, real forks:

• Genuine ambiguity that would change scope, a goal, or an acceptance criterion (never guess the product).
• A hard failure it can't resolve (a red test it can't green → debug; an analyze contradiction).
• Destructive / irreversible / outward-facing actions — push, merge, delete, secrets. ship (PR/merge) still confirms: autopilot drives the build, not the release.

Run the fan-out on the developer subagent as usual, and narrate at the accompaniment dial's volume (L0: near-silent, just show artifacts; L3: explain each phase as it passes). Autopilot changes when you ask, never what gets written — every artifact and gate-check still happens; you just don't block on a human between them.

Read the accompaniment dial first

Before dispatching, read 02-DOCS/wiki/harness/user-profile.md and adapt — exactly as every rsc skill does. The dial sets how much you explain and how many questions you ask at each gate, not whether the gates exist.

If there is no profile yet, default to non-technical + ask the two harness gauging questions (technical level, accompaniment level) before dispatching, and persist them — that is the harness's job and sdd honors it.

Per-phase model routing (opt-in)

Different phases reward different models: architecture and adversarial review want the strongest one; scaffolding and git plumbing don't. SDD can route each phase to a tier — heavy (deep reasoning), balanced (execution), light (mechanical) — that resolves to a concrete model in 02-DOCS/wiki/sdd/config.yaml under models. The default mapping is the Tier column above (quality-biased: heavy on constitution/plan/analyze/review/debug, balanced on execution, light on ship/worktrees/sdd-init).

It is off by default (models.enabled: false). When the user opts in, each phase applies it two ways: programmatically — dispatching Task/parallel subagents on the tier's model (real routing, e.g. Claude Code) — and advisorily — announcing the recommended switch at the phase boundary, gated by the accompaniment dial, for inline work and assistants that can't switch programmatically. Never switch unasked, never claim a switch a tool can't make, and skip routing on trivial one-line changes. The sdd dispatcher itself never routes (staying on the session model); parallel has no fixed tier (each unit inherits the tier of its work). Full protocol, per-assistant mechanism, and the provider→model table: references/model-routing.md.

Where the artifacts live (and why it matters)

Every phase writes under 02-DOCS/wiki/sdd/ so the feature's reasoning outlives the chat:

02-DOCS/wiki/sdd/
├── config.yaml              ← repo runtime calibration from sdd-init
├── constitution.md          ← project non-negotiables (once)
├── proposals/<slug>.md      ← optional pre-execution briefing
├── specs/<slug>.md          ← one spec per feature
├── plans/<slug>.md          ← one plan per feature (tasks live inside)
├── progress/<slug>.md       ← append-only apply progress
├── verifications/<slug>-YYYY-MM-DD.md
├── archive/<slug>/          ← final report, state, verify/review/ship records
├── sessions/<date>-<slug>.md
└── decisions.md             ← append-only log of decisions taken while building

Index these in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a short pointer) under an sdd/ topic, so every other skill reads them before working in the area. The harness maintains and improves these files just like any other wiki topic — sdd produces them, the harness keeps them honest.

# 02-DOCS/wiki/index.md
## Knowledge map
| Topic | Where | What |
| --- | --- | --- |
| sdd/ | 02-DOCS/wiki/sdd/ | Constitution, specs, plans, decisions for spec-driven feature work |

Stack handoff

sdd and its phases are process, not stack. Concrete tooling — test runners, lint/type/build, framework idioms — belongs to the stack skills. plan defers stack specifics, implement borrows the stack skill's testing approach, and verify runs the stack skill's checks. Route to the stack that matches the work: ../fastapi/SKILL.md, ../nextjs/SKILL.md, ../go/SKILL.md, ../postgresdb/SKILL.md, ../flutter/SKILL.md. Visual/UX work routes to ../design/SKILL.md and copy to ../marketing/SKILL.md.

Skill registry and compact skill rules

The registry is the cheap index:

.rsc/skill-registry.json
.rsc/skill-registry.md

Use it to choose the few relevant skill paths for the current phase/stack. Do not load the whole catalog. Before dispatching subagents, digest selected skills into 4-5 compact rules and include them in the brief. Each phase reports skill_resolution: which skills were used, which were missing, fallback behavior, and the compact rules handed to subagents.

Standard result envelope

Every SDD phase ends with the same parseable block so the dispatcher can chain phases without interpreting a novel:

{
  "status": "complete|blocked|failed",
  "executive_summary": "one short paragraph",
  "artifact": "path/to/artifact-or-none",
  "next_recommended": "sdd-init|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
  "risk": "low|medium|high",
  "model": { "tier": "heavy|balanced|light", "resolved": "model-id", "routing": "on|off" },
  "skill_resolution": {
    "used": [],
    "missing": [],
    "fallback": [],
    "compact_rules": []
  },
  "evidence": []
}

If a phase cannot produce the envelope because the user stopped it mid-flight, write a session summary instead.

Session summary / compaction recovery

When a session is long, about to pause, or context is at risk, write:

02-DOCS/wiki/sdd/sessions/<date>-<slug>.md

Include current phase, active artifacts, last verdict, completed tasks, next steps, risks, useful commands, and the current skill_resolution. This lets the next agent resume from artifacts instead of scrollback.

Anti-patterns → STOP

Start here

• New project, nothing on disk yet → ../sdd-init/SKILL.md for runtime calibration, ../constitution/SKILL.md for non-negotiables, then ../specify/SKILL.md.
• Existing project, no SDD config → ../sdd-init/SKILL.md, then route by phase.
• Existing project, new feature → ../specify/SKILL.md (or proposal first if risky/architectural).

Then follow the arrows: each phase ends by pointing at the next, all the way to ship.