# Sdd Skill > Specification-Driven Development (SDD) orchestration skill. Use this skill whenever the user mentions .sdd-skill/, state.md, @planner, @architect, @implementer, @review, @tester, @sentinel, SDD, /sdd-skill commands, spec.md in a project context, or wants to continue development across IDEs (Cursor, Claude Code, Antigravity, Open Code). Also trigger when the user wants to start a new project with agentic methodology, adopt SDD in an existing project, manage features/hotfixes with agent roles, or resume work after switching tools. This skill governs a polymorphic agent system where a single AI assumes different roles based on filesystem state — never chat history. Trigger even if the user just says "continue", "resume project", or "what's next" and a .sdd-skill/ folder is likely present. - Skill: `jmsolorzano-13/sdd-skill` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add jmsolorzano-13/sdd-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/jmsolorzano-13/sdd-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: JMSolorzano-13 (https://skillmd.com/u/jmsolorzano-13) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jmsolorzano-13/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=` 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-.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 # only after current spec closed /sdd-skill feature new [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 # origin spec known /sdd-skill bug # origin unknown, triggers investigation (cycle.md [1B]) /sdd-skill spec list | spec view /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= # declare/change active tool, persists in state.md until resent /sdd-skill force @ # 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.