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 which register you want (technical or with analogies), 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 — or its frontmatter says status: draft (the one rsc onboard writes)? → 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 — unless it is still status: draft: then complete it first.
• 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 in the orient voice: name each phase as it passes and show its artifact, one line each. 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.