Commands

Commands

Both tools expose the same eight /sdd-* commands, because both execute the same body file under .claude/commands/. Claude Code runs those files directly; GitHub Copilot reaches them through a one-line loader in .github/prompts/.

Command	Purpose
/sdd-overview	Workflow overview, current spec status, command list
/sdd-setup	Onboarding wizard: DocLanguage, Memory Bank, first architecture snapshot
/sdd-specify	Adaptive product-owner interview → lean spec with testable acceptance criteria
/sdd-plan	Spec → persisted baby-step plan file (research, resume, impact analysis)
/sdd-compile	Readiness check: tests, acceptance criteria, docs sync
/sdd-architecture-update	Detect drift, update snapshot + Memory Bank (confirmation gate)
/sdd-lifecycle	Spec status and moves between backlog/, active/, done/
/sdd-style-update	Capture coding style preferences into AGENTS.md

Recommended flow: /sdd-specify → /sdd-plan → implement → /sdd-compile → /sdd-lifecycle. Run /sdd-architecture-update whenever the structure changes.

Why the sdd- prefix

It keeps the commands from shadowing Claude Code's built-in commands and groups them into one autocomplete namespace: type /sdd and you see the whole workflow set.

Why they never trigger on their own

Every body carries disable-model-invocation: true. A Claude Code command is otherwise model-invocable, and these are workflows with side effects — they create files, move files and delete files — so they run only when you invoke them. Copilot prompt files are user-invoked by design, so the loaders need no equivalent flag.

Passing arguments

Both tools append whatever you typed after the command to the invocation, so this works everywhere:

/sdd-plan .specs/active/0007-user-login.md

The bodies deliberately do not use $ARGUMENTS, $0/$1 or !`shell` injection — Copilot supports none of them. Instead each body says something like "the user may name a spec path after the command; if none is given, list the candidates and ask." See Design Decisions.

---

/sdd-overview

Argument hint: (none)

Your "where am I" command. It greets you as the repository's SDD assistant and reports the current state:

• the DocLanguage value from AGENTS.md
• which specs sit in .specs/backlog/, .specs/active/ and .specs/done/
• whether the working tree is clean (git status --short)

If DocLanguage is still the default and the Memory Bank looks unseeded, it suggests /sdd-setup. It then prints the operating protocol and the command list.

Run it at the start of a session, or whenever you have lost the thread.

---

/sdd-setup

Argument hint: [docLanguage] [projectName] [stack] — or just answer the wizard

One-time onboarding. On first invocation it gives a short introduction to Spec-Driven Development, then runs the wizard.

Step 0 is always the same question: "In which language should the project documentation Markdown files be written?" If you do not answer, it infers the language from the conversation. The answer is written to DocLanguage in AGENTS.md — the only place it lives.

Then, in order: project name and one-liner · primary users · tech stack · architecture style · repo entrypoints · quality gates · coding preferences.

What it writes:

• .memory-bank/projectbrief.md — mission and success criteria
• .memory-bank/techContext.md — stack, build/run/test
• .memory-bank/activeContext.md — the compact dashboard structure (see Memory Bank)
• .memory-bank/systemPatterns.md — initial patterns and decisions
• the architecture: snapshot in AGENTS.md, inferred from the real folder layout
• Style & Output Preferences in AGENTS.md, from what you stated

Anything it had to assume is written down and confirmed with you.

---

/sdd-specify

Argument hint: [idea or title] [area/module]

An adaptive interview, not a form. The assistant acts as product owner, requirements engineer and architect, and asks only the questions your particular idea actually needs.

The interview rules are non-negotiable:

• exactly one question per message — never a batch, never a checklist
• always shows progress: Question 3 of 9 — Data
• never asks what the conversation, .specs/ or the Memory Bank already answers
• one short confirmation per answer, then the next question
• thin answers are accepted; gaps become assumptions or open points, never invented facts
• what you said is the scope — everything else goes to Out of Scope

Before asking anything it reads the ground it already stands on: existing spec filenames (for the next number and to avoid duplicates), .memory-bank/techContext.md, systemPatterns.md, and the architecture: snapshot. Stack and boundaries are known, so it does not ask for them.

Question budget scales with complexity:

Complexity	Questions
Small change	5–7
Normal feature	8–12
Complex feature	12–16
Critical enterprise / compliance / AI feature	14–20

Additional blocks are triggered by what is in the idea — screens and forms pull in UI/UX and error states; login and personal data pull in security and privacy; payment, law or medicine pull in compliance and auditability; LLMs and agents pull in guardrails and human-in-the-loop.

Output: .specs/backlog/NNNN-slug.md, always in backlog/, with **Status:** Draft under the H1 and acceptance criteria in the form AC-001: Given <start>, when <action>, then <expected>.

Say "done", "that's enough" or "write the spec" at any point and it stops asking and writes with what it has. Full document structure: Specs and Plans.

---

/sdd-plan

Argument hint: [path to spec or plan]

Planning produces a file, not a chat answer. A plan that lives only in the chat is gone when the session ends.

It picks one of three modes automatically:

Situation	Mode
The spec has no plan file yet	A — plan from scratch
A plan exists and work is unfinished	B — resume
A plan exists but the spec changed	C — re-plan the delta

Mode A reads the spec, AGENTS.md and the Memory Bank; surveys the code the spec actually touches (entrypoints, modules, the existing test setup); researches anything it would otherwise guess; decomposes the work into baby steps; writes the plan file — then stops. Planning does not change code.

Research is mandatory, not optional. Whenever the spec involves a library, framework or API that cannot be verified from the repo, version-specific behaviour, a protocol or regulation, or a pattern where the model's knowledge may be stale, it uses its web search or fetch capability and records every source under ## Research with a link and a retrieval date. No link, no claim. If no web access is available it says so plainly and marks the affected steps as assumptions.

Baby steps have a fixed shape: one concern each, small enough to read in one diff, ordered so the repo keeps working after every step, tied to the acceptance criteria they serve — and every one carries a Verify: line. If a step has no verifiable outcome, it is too big and gets split.

Mode B reads the plan first, checks Current step and Session handoff against git status --short and the real code, and reports in three lines: what is done, what is next, what blocks it. After each finished step it updates the plan in the same change set as the code — tick the box, fill Notes, write real paths into the traceability table, move Current step.

Mode C is the impact analysis. It reads the traceability table in reverse: for every changed acceptance criterion it lists the steps and the code paths already built from it, and reports that before editing anything. New steps are appended, existing IDs are never renumbered (they are references), obsolete steps are struck with a one-line reason rather than deleted.

---

/sdd-compile

Argument hint: [path-to-spec.md] [runTests:true|false]

The readiness brief. It gathers git status --short and git log --oneline -10, reads the spec, its .plan.md sibling and AGENTS.md, then reports:

• Current goal — from the spec
• Constraints — from AGENTS.md and the spec
• Architecture snapshot highlights — the relevant parts
• Acceptance criteria — each one marked satisfied or pending, with evidence
• Plan state — open vs. finished steps, whether the traceability table names real code paths, any criterion no step covers, any step whose Verify: was never run
• Do / Don't — including your Style & Output Preferences
• Docs sync — is the Memory Bank current, do spec and plan statuses match reality
• Next 3 steps — concrete and actionable

Tests run as part of it when the project has a test command.

---

/sdd-architecture-update

Argument hint: [focus: module|folder|area] (optional)

Reconciles the architecture: snapshot in AGENTS.md with the repository as it actually is.

It inspects the real directory tree (top two levels), compares it with the snapshot, and identifies what matters architecturally: new, moved or removed top-level folders; new entrypoints, apps, services, packages or modules; changed boundaries or shared components.

Then it presents a delta report — what changed, why it matters, what it proposes to update.

There is a confirmation gate. Before writing anything it asks "Is this the change you expected?" and "Anything else I should include?". Only after you confirm does it update the snapshot, .memory-bank/systemPatterns.md and .memory-bank/activeContext.md.

Obvious drift (a brand-new top-level folder) is picked up automatically by the constitution's drift rule during normal work. This command is for the cases that need interpretation.

---

/sdd-lifecycle

Argument hint: [spec path] [newStatus: Draft|In Progress|Implemented|Deprecated]

Moves specs between backlog/, active/ and done/ and keeps their status honest.

The safety rules it enforces:

• No duplicates. A spec exists in exactly one lifecycle folder. Moving means writing to the destination and deleting the original.
• Duplicate check first. Before moving, all three folders are scanned for the same filename. Copies in less-advanced folders are deleted (done > active > backlog).
• Plans travel with their spec. If NNNN-slug.plan.md sits next to NNNN-slug.md, both move and de-duplicate together. A plan must never end up in a different folder than its spec.
• Separate status vocabularies. A spec uses Draft | In Progress | Implemented | Deprecated; a plan uses Not started | In Progress | Blocked | Done. One never overwrites the other.
• Before done/: the plan is checked too — every step ticked, the traceability table filled with real code paths. If steps are still open, it says so and lets you decide.

It always updates .memory-bank/activeContext.md when a spec becomes active or is completed: ## Active Spec is set or cleared, Current phase and ## Next are refreshed.

These rules are deliberately restated inside the command body — see Design Decisions.

---

/sdd-style-update

Argument hint: [preference] (or list several)

Captures coding-style preferences into the Style & Output Preferences section of AGENTS.md — the only place they live. It normalises each preference into a short bullet, groups it by category (Comments, Naming, Formatting, Framework Conventions, Testing, …), applies it immediately, and shows you the updated bullets.

/sdd-style-update no comments in generated code, prefer file-scoped namespaces, avoid LINQ in hot paths

You rarely need to run this explicitly: the constitution already instructs the assistant to capture any style preference you state in passing — "no comments", "rewrite this without LINQ", "use expression-bodied members" — and append it here on its own. Use the command when you want to state several at once, or reorganise what is already there.