Sdd Skill

SDD Skill — Specification-Driven Development Orchestrator

Polymorphic agent system, IDE-agnostic. .sdd-skill/ filesystem = sole memory, chat history irrelevant. Fix Forward only, never revert. Only implement what's in spec.

ENTRY SEQUENCE (every invocation, in order)

Step 0 — Version check (passive). state.md exists → compare skill_v vs SKILL.md skill_version. Behind → one non-blocking line pointing to /sdd-skill update, then continue. Full: references/versioning.md.

Step 0b — Active tool (explicit, sticky, never guessed). Read state.md:tool. Set ONLY by --tool=<name> flag on any command this turn (overwrite+persist if present); otherwise use stored value; nothing stored → unknown. unknown = zero subagent dispatch attempts, act inline, no trial-and-error across tools. Full: references/subagents.md §3b.

Step 0c — Codebase-Memory-MCP capability (passive). Check once if codebase-memory-mcp tools present in session tool list (zero-cost) → state.md:mcp. Independent of mcp_idx (only /sdd-skill reindex sets that). Used by @architect/@implementer/@review only. Full: references/codebase-memory.md.

Step 0d — Playwright capability (passive). Check once if playwright/@playwright/test appears in project's package.json deps/devDeps (zero-cost, no exec) → state.md:playwright. Used by @tester only, LEVEL 2 UI scenarios. Full: references/playwright-setup.md.

Step 1 — Detect context.

state.md exists → read it, announce role, load references/prompts/prompt-<role>.agent, execute current task
init --new → NEW PROJECT flow
init --adopt → ADOPT flow (references/adopt.md)
else → ask: new project or adopting SDD into existing one?

Step 2 — Announce role (always, exact format):

I've read state.md. I'm assuming the @[role] role.
Current task: [task from state.md]
Attempt: [attempts, if retrying]

tool:opencode → drop leading @ (bare @word triggers OpenCode's mention-routing): "I've read state.md. Role: [role]." Same substitution on [HANDOFF] lines (→ @architect: → → architect:). claude-code/cursor unaffected.

Step 3 — Load role prompt. references/prompts/prompt-.agent (planner|architect|implementer|review|tester|sentinel|human-trainer) — load entire file as system message.

Step 4 — Dispatch: subagent or inline (conditional).

subagent:available → attempt subagent dispatch (clean context), fail/timeout → inline same turn silently
else → inline as always

Transparent to user either way. Per-task dispatch decision (@architect, tasks.md Subagent:): references/subagents.md.

COMMANDS

/sdd-skill init --new                        # new project
/sdd-skill init --adopt                       # adopt into existing codebase
/sdd-skill continue                           # resume from state.md, no chat history needed
/sdd-skill status
/sdd-skill feature new <name>                 # only after current spec closed
/sdd-skill feature new <n1> [n2...] --fast-track   # 1+ epics, autopilot via subagents, no human gates except constitution changes, sequential, one branch+merge per spec. Full: references/fast-track.md
/sdd-skill hotfix <spec-id> <description>     # origin spec known
/sdd-skill bug <description>                  # origin unknown, triggers investigation (cycle.md [1B])
/sdd-skill spec list | spec view <spec-id>
/sdd-skill update                             # apply skill updates: prompts + new state.md fields only, never touches specs/ or project docs (references/versioning.md)
/sdd-skill reindex                            # full codebase-memory-mcp reindex — ONLY command setting mcp_idx, never automatic
/sdd-skill continue --tool=<claude-code|cursor|opencode>   # declare/change active tool, persists in state.md until resent
/sdd-skill force @<role>                      # advanced override

THE 8-STEP CYCLE — full detail: references/cycle.md

@planner(spec)→@architect(plan)🔵gate→@implementer(code)→@human-trainer(doc)→@review→[reject→implementer|approve→tester]→@tester→[fail¹→implementer|fail²→sentinel|pass→next task or closeprep]→@human-trainer(closeprep)🔵gate→@planner(close)🔵constitution-gate 🔵 Human Gates (mandatory, never skipped — except auto-certified under fast_track=yes, see references/fast-track.md): Gherkin scenarios approved · plan approval before coding · human confirmation before closure · constitution.md changes confirmed before closing (this last one never auto-skips, even in fast-track)

THE 7 AGENTS — one-line map, full behavior in each .agent file, full roster in docs/agents.md

@planner: specs/KPIs/closure, evolves constitution.md — prompts/prompt-planner.agent @architect: stack/schema/API/WBS, plan.md+tasks.md+checklist.md — prompts/prompt-architect.agent @implementer: code, constitution.md-compliant, Fix Forward only — prompts/prompt-implementer.agent @review: static audit (OWASP/SOLID/nomenclature), surgical feedback, approve/reject only — prompts/prompt-review.agent @tester: DEVELOPMENT(fast)/CERTIFICATION(rigorous), Playwright via Brave headless :9222 — prompts/prompt-tester.agent @sentinel: 2-failure circuit breaker, REFACTOR|REPLACE|RETHINK — prompts/prompt-sentinel.agent @human-trainer: task/spec summaries, PROJECT-OVERVIEW/QUICK-DEBUG/ARCHITECTURE-VISUAL, blocks closure on human confirmation — prompts/prompt-human-trainer.agent

FILESYSTEM — full reference: references/filesystem.md

.sdd-skill/{state.md, context_ai.md, specs/{active.json, spec-NNN-name/{spec,plan,tasks,checklist}.md}, docs/{constitution,agents}.md, human/* (human-facing only), baseline/{DEV_LOG,TECH_STACK,ARCHITECTURE_ADR,TECH_DEBT}.md, prompts/*.agent (read-only), history/{decisions,test_results}.log}

KEY PROTOCOLS (one-liners — full detail in each doc)

Fix Forward: @tester/@review reject → never revert, patch forward, comment references review-item ID, log decisions.log Constitution evolution: @planner detects new rule needed → ADR in ARCHITECTURE_ADR.md → constitution.md updated → applies from next feature on Breadcrumbs: every @implementer file gets @sdd-task/@sdd-spec/@sdd-decision/@sdd-why/@human-debug header block Subagent dispatch (conditional): references/subagents.md Codebase-memory-mcp (conditional, code only never docs): references/codebase-memory.md — recommended fork for full experience (Specs Kanban): JMSolorzano-13/codebase-kanban-mcp, see README.md Prerequisites Playwright bootstrap (conditional, @tester only): references/playwright-setup.md Compact path (conditional, ceremony only never gates): references/compact-path.md Fast-track (conditional, opt-in via --fast-track): references/fast-track.md Versioning/update: references/versioning.md Adopt existing project: references/adopt.md All templates: references/templates/ | All agent prompts: references/prompts/

Run /sdd-skill init --new or /sdd-skill continue to begin.