From sdd
Breaks down specifications into grouped epics and 3-4 story-sized issues with task checklists for traceability in issue trackers. Use for sprint planning, scrum ceremonies, or team reviews.
npx claudepluginhub joestump/claude-plugin-sdd --plugin sddThis skill uses the workspace's default tool permissions.
<!-- Governing: ADR-0017 (Parallel Agent Coordination), SPEC-0015 REQ "Foundation Story Detection", SPEC-0015 REQ "Hotspot Analysis" -->
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
You are breaking down an existing specification into trackable work items (epics and story-sized issues) in the user's issue tracker. Instead of creating one issue per requirement, you group related requirements into 3-4 story-sized issues by functional area, with task checklists in the issue body for requirement traceability. See ADR-0011 and SPEC-0010.
Resolve artifact paths: Follow the Artifact Path Resolution pattern from references/shared-patterns.md to determine the ADR and spec directories. If $ARGUMENTS contains --module <name>, resolve paths relative to that module. The resolved ADR directory is {adr-dir} and spec directory is {spec-dir}.
Identify the target spec and parse flags: Parse $ARGUMENTS.
Spec resolution: Follow the standard flow in the plugin's references/shared-patterns.md § "Spec Resolution" (which uses {spec-dir} from the Artifact Path Resolution pattern).
Flag parsing:
--scrum: Enable scrum ceremony mode (see Scrum Mode section below). Default: off. Mutually exclusive with: --review.--review: Enable team review mode (see step 3). Default: off. Mutually exclusive with: --scrum.--project <name>: Use a single combined project for all issues. Default: per-epic. Mutually exclusive with: --no-projects.--no-projects: Skip project creation entirely. Default: off. Mutually exclusive with: --project.--branch-prefix <prefix>: Custom branch prefix instead of the default feature/epic prefixes. Default: feature.--no-branches: Omit ### Branch and ### PR Convention sections from issue bodies. Default: off.--module <name>: Resolve artifact paths relative to the named module (see step 0). Default: none.--scrum and --review are mutually exclusive. When both are provided, --scrum takes precedence and --review is silently ignored. The scrum ceremony includes its own review process.
If both --project and --no-projects are provided, warn the user and use --no-projects.
If --scrum is set, skip to the Scrum Mode section after completing step 1. Do not proceed through steps 2–8 in sequence — scrum mode orchestrates them internally.
Read the spec: Read both {spec-dir}/{capability-name}/spec.md and {spec-dir}/{capability-name}/design.md to understand the full scope of requirements, scenarios, and architecture. Validate spec pairing per references/shared-patterns.md § "Spec Pairing Validation". If either spec.md or design.md is missing, error and suggest /sdd:spec.
Choose drafting mode: Check if $ARGUMENTS contains --review.
Default (no --review): Single-agent mode. Analyze the spec, detect the tracker, and create all issues directly.
With --review: Team review mode.
TeamCreate:
general-purpose) to analyze the spec and create the issue breakdowngeneral-purpose) to review the breakdown for completeness, proper acceptance criteria, and correct dependency orderingTeamCreate fails, fall back to single-agent mode--scrum)When --scrum is set, execute the full ceremony below instead of the standard steps 2–8. Steps 2–8 are still used internally within the ceremony phases as described. Governing: SPEC-0012, ADR-0013.
Tell the user: "Starting scrum ceremony. This will audit spec completeness, decompose requirements into stories, run a grooming team review, organize projects, and enrich issue bodies. Give me a few minutes."
$ARGUMENTS: use steps 2 and the spec identification from step 1 to resolve the target spec.Before spawning the grooming team, audit every spec referenced by any in-scope issue:
{spec-dir}/{name}/design.md exists alongside spec.md.design.md is missing, generate a draft design.md co-located with spec.md. Use the design.md template from /sdd:spec. Set frontmatter status: draft. Log: "Generated draft design.md for {spec-name}."{spec-dir}/{issue-slug}/spec.md and design.md as drafts (status: draft), deriving the capability name from the issue title. Log: "Generated draft spec proposal for issue #{n}: {title}."Follow the standard story-sizing logic (steps 2, 4–5.5) to produce 3-4 story-sized issues per spec. If running in full-backlog mode (no spec arg), decompose each spec independently and collect all stories into a single grooming list. After decomposition, proceed to the grooming ceremony without yet running organize or enrich steps (those run after grooming).
Spawn the five specialist agents and distribute all stories for parallel review. Each agent MUST review every story and submit feedback to the lead via task messages.
Spawn the following agents with these exact personas:
Product Owner (PO)
Review each story for user value, priority order, and scope. Assign verdict: APPROVED, REVISE (with specific change), or DEFER (with reason). If deferring a MUST/SHALL violation, provide written justification.
Scrum Master (SM)
Ensure stories are sprint-ready. Assign t-shirt size (XS/S/M/L/XL). Flag ambiguity, incorrect dependencies, or blockers. Tiebreaker when PO and Engineer B disagree.
Engineer A
Assess technical risk, scope correctness, and whether WHEN/THEN scenarios are verifiable. Verdict: APPROVED, REVISE, or DEFER.
Engineer B (Grumpy)
High-bar reviewer. Find problems: vague requirements, hidden scope, incorrect spec/ADR references. APPROVE only with explicit one-sentence justification. Do not soften feedback.
Architect
Verify governing comments (per
references/shared-patterns.md§ "Governing Comment Format"), ADR references in acceptance criteria, design.md existence, and WHEN/THEN alignment with design.md. Verdict: APPROVED, REVISE, or DEFER.
Collecting feedback:
The lead collects all five verdicts per story before proceeding. Stories with all five APPROVED verdicts are finalized immediately. Stories with any REVISE or DEFER verdict enter dissent resolution.
For each story with dissent:
### Grooming Note section explaining the deferral reason.After grooming, automatically run the organize step (equivalent to step 5.6 and 5.7 in standard mode) for all finalized stories. Respect --no-projects and --project flags. Do not prompt the user — this runs automatically. Log each organize action as it happens.
After organize, automatically run the enrich step (equivalent to the branch + PR convention logic in step 5.3) for all finalized story issue bodies. Respect --no-branches flag. Do not prompt the user — this runs automatically.
Output the sprint report to the conversation:
## Sprint Report — {Capability Title or "Full Backlog"} — {date}
### Spec Completeness
- {N} specs audited
- {N} design.md files generated: {paths}
- {N} spec proposals generated for unspec'd issues: {paths}
### Grooming Results
**Accepted ({N} stories)**
- #{issue} {title} — {size} — {branch}
**Revised ({N} stories)**
- #{issue} {title} — Revised: {what changed} — Raised by: {Engineer B / Architect / ...}
**Deferred ({N} stories)**
- #{issue} {title} — Reason: {SM tiebreak / dissent reason}
### Final Sprint Backlog
Ordered for implementation (dependencies respected):
1. #{issue} {title} — {branch} — Sprint {N}
2. #{issue} {title} — {branch} — Sprint {N}
...
### Next Steps
- Run `/sdd:work` to begin parallel implementation
- Run `/sdd:prime` before implementation sessions to load architecture context
references/shared-patterns.md. Read the ### SDD Configuration section from CLAUDE.md for tracker type, tracker-specific config (GitHub/Gitea/GitLab: Owner/Repo, Jira: Project Key, Linear: Team ID, Beads: no extra config), plus Branch Conventions, PR Conventions, and Projects settings used in steps 5–7. When the user selects a tracker for the first time, offer to save the configuration to the ### SDD Configuration section in CLAUDE.md.4a. Tier 4 issues sync (v5.0.0+):
Before grouping requirements into stories (Step 5.2), sync the {repo}-issues qmd collection from the tracker so the planner sees current issue state. Subject to the 5-minute deduplication window in .sdd/issues/_meta.json (per references/tracker-sync.md § "Cursor Management").
Read .sdd/issues/_meta.json. If last_sync is within the last 5 minutes, skip the sync silently.
Otherwise, invoke per-tracker fetch+normalize per references/tracker-sync.md. Print: "Syncing N issues from {tracker}…".
On sync failure, surface a one-line warning per tracker-sync.md § "Failure Modes and Degradation" and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; planning is the user's primary intent.
Create issues in the detected tracker:
5.1: Create an epic. Create an epic (or equivalent) for the specification itself, titled "Implement {Capability Title}" with a body referencing the spec number and linking to the spec/design files. Apply the epic label using the try-then-create pattern (see references/shared-patterns.md). (Governing: SPEC-0011 REQ "Auto-Create Labels")
5.1a: qmd-aware issue duplicate check (v5.0.0+):
Before creating story issues, qmd-search {repo}-issues for existing issues that overlap with the spec's scope. This catches the case where a sprint is being re-planned or where ad-hoc issues already cover part of the spec.
Construct a hybrid query per references/qmd-helpers.md § "Hybrid Retrieval":
lex: spec capability name + key requirement names from the specvec: a one-sentence framing of what the spec coversintent: "/sdd:plan — find existing open issues that already cover part of this spec"collections: ["{repo}-issues"]limit: 10, minScore: 0.4For each result above the threshold, surface to the user via AskUserQuestion: "Issue #{N} ({title}) appears to already cover part of SPEC-{XXXX}. Skip planning the requirements it covers, link the existing issue into the new epic, or proceed and create a new story anyway?" Three options: skip / link / proceed.
If qmd returns zero matches, proceed silently — the sprint is greenfield from the issue tracker's perspective.
5.2: Group requirements into stories. Instead of creating one issue per requirement, group all ### Requirement: sections into 3-4 story-sized issues by functional area. This is governed by SPEC-0010 and ADR-0011.
5.2.0: qmd-aware code awareness (v5.0.0+):
For each functional area identified during grouping, qmd-search {repo}-code to find existing files that already implement related capability. Stories that touch existing code MUST be framed as "extend X in path/to/file" rather than "implement from scratch", and sized accordingly (smaller than greenfield).
Construct a hybrid query per references/qmd-helpers.md:
lex: keywords from the requirement names + functional area namevec: a one-sentence framing of what the requirement doesintent: "/sdd:plan — find existing code that implements related capability"collections: ["{repo}-code"]limit: 8, minScore: 0.3For each result above the threshold, fold the file path and a brief note into the story's body description: "Extend {path/to/file} (currently does {one-line summary})".
Story sizing: stories that extend existing code SHOULD target ~150-300 line PRs (smaller than the greenfield 200-500 target). Stories with no qmd-detected related code use the greenfield target.
Grouping process:
### Requirement: sections in the spec and identify the functional areas they affect (e.g., data model, API endpoints, validation, configuration, setup).5.2a: Foundation Story Detection. After grouping requirements into stories, analyze the grouped stories to identify shared types, packages, and helper functions needed by two or more stories. Follow the "Foundation Story Detection" pattern in references/shared-patterns.md. (Governing: ADR-0017 Layer 1, SPEC-0015 REQ "Foundation Story Detection")
5.2b: Hotspot Analysis. Before making parallelization decisions, analyze recent git history to identify files that are frequent sources of merge conflicts. Follow the "Hotspot Analysis" pattern in references/shared-patterns.md. Stories that modify hotspot files MUST be serialized rather than parallelized. (Governing: ADR-0017 Layer 1, SPEC-0015 REQ "Hotspot Analysis")
Creating story issues:
## Requirements section containing a task checklist (see step 5.3)--no-branches is set, update the issue body to append a ### Branch section:
`feature/{issue-number}-{slug}` (or custom prefix from --branch-prefix or CLAUDE.md Branch Conventions > Prefix)`epic/{issue-number}-{slug}` (or custom prefix from --branch-prefix or CLAUDE.md Branch Conventions > Epic Prefix)Branch Conventions > Slug Max Length)5.2.1: Detect HTTP endpoint stories for security checklist injection.
After grouping requirements into stories, determine which stories involve HTTP endpoints. A story involves HTTP endpoints if ANY of the following are true:
A story does NOT involve HTTP endpoints if it exclusively involves: database migrations, background jobs, CLI commands, library refactoring, configuration setup, CI/CD pipelines, or documentation.
For each story that involves HTTP endpoints, you MUST append a ## Security Checklist section to the issue body, placed after the ## Acceptance Criteria section and before any ### Branch or ### PR Convention sections. Use the canonical Security Checklist template from references/issue-authoring.md § "Security Checklist Template" — five required checkboxes covering auth middleware, input validation, output encoding, rate limiting, and body size limits. Do NOT add the security checklist to stories that do not involve HTTP endpoints.
5.2.2: Detect UI stories and create companion test stories.
After grouping requirements into stories, determine which stories touch UI components. A story touches UI if ANY of the following are true:
A story does NOT touch UI if it exclusively involves: database migrations, background jobs, CLI commands, API-only endpoints with no HTML rendering, library refactoring, configuration setup, CI/CD pipelines, or documentation.
For each story that touches UI, you MUST create a companion test story alongside the feature story. Companion test stories cover:
Companion test story format:
## Test Requirements section listing the specific test types needed:
- [ ] Template render tests: {what to verify}- [ ] JS unit tests: {what to verify} (only if the feature story involves JavaScript)- [ ] HTMX integration tests: {what to verify} (only if the feature story involves HTMX)test label using the try-then-create pattern (see references/shared-patterns.md)Do NOT create companion frontend test stories for backend-only stories (API-only, database, CLI, background jobs, library code).
5.2.3: Detect backend projects and create CI story.
After grouping requirements into stories, determine if the spec targets a backend project. A spec targets a backend project if ANY of the following are true:
go.mod, requirements.txt, Cargo.toml, pom.xml, build.gradle, Gemfile, mix.exs, Package.swift, composer.json, pyproject.toml)When a backend project is detected and no CI story already exists for this spec:
Create a single CI setup story with the following checklist:
## Requirements
- [ ] **Static analysis**: Configure and run static analysis tooling appropriate to the project's language/runtime
- [ ] **Test runner with race detection**: Configure the test runner to enable race detection (or equivalent concurrency safety checks) in CI
- [ ] **Formatting enforcement**: Configure automated formatting checks in CI to enforce consistent code style
- [ ] **CI pipeline integration**: Add the above checks to the project's CI/CD pipeline so they run on every PR
ci and foundation labels using the try-then-create patternDo NOT create a CI story if:
5.2.4: No retroactive governing comment PRs.
When planning stories, MUST NOT create standalone issues or PRs whose sole purpose is to add governing comments to existing code retroactively. Governing comments (per ADR-0020) are added as part of feature implementation — they go in the PR that implements or modifies the governed code, not in a separate cleanup PR.
5.3: Write task checklists. Each story issue body MUST follow the Story Issue template from references/issue-authoring.md § Body Templates. The template defines the canonical ## Requirements (RFC 2119 task checklist) and ## Acceptance Criteria sections; this skill MUST NOT inline its own variant. The template's rules — exact requirement-name match against the spec, SPEC number references, WHEN/THEN pairs derived from scenarios (not invented), every requirement in exactly one story — apply.
Tracker-specific deviation: For Beads, replace the markdown ## Requirements checklist with native subtasks (bd subtask add per requirement, each subtask titled with the requirement name and bodied with the normative statement + WHEN/THEN scenarios + spec reference). All other trackers (GitHub, Gitea, GitLab, Jira, Linear) use the markdown form per the template. See references/issue-authoring.md § Cross-Tracker Considerations for the full deviation table.
After the requirements and acceptance criteria sections, unless --no-branches is set, append a ### PR Convention section:
Closes #{issue-number}Closes #{issue-number} (in MR description)bd resolve{PROJECT-KEY}-{number} reference{TEAM}-{number} referencePR Conventions settings when available (Close Keyword, Ref Keyword, Include Spec Reference)5.4: Set up dependencies between stories. Where stories have logical ordering (e.g., setup before core logic, core before extensions), set up dependency relationships between story issues using the tracker's native features. If using Beads, use bd dep add.
5.5: Gather tracker-specific config. If the tracker requires configuration not already saved (e.g., repo owner/name for GitHub, project key for Jira), use AskUserQuestion to ask the user. Offer to save the config to the ### SDD Configuration section in CLAUDE.md.
5.6: Project grouping. Unless --no-projects is set:
gh project create CLI or MCP tools, then gh project item-add to add issues. After creating the project, MUST link it to the repository using gh project link {project-number} --owner {owner} --repo {owner}/{repo} so it appears in the repository's Projects tab.ToolSearch to discover). MUST ensure the project is associated with the repository.--project <name>: Create a single project with the given name and add all issues to itToolSearch to discover project-creation MCP tools at runtimeProjects > Default Mode and cached project IDs for settings. If a project ID is already cached for this spec, reuse it instead of creating a new one.5.7: Workspace enrichment. After project creation, enrich the project with navigational context and structure. Read CLAUDE.md Projects configuration for custom settings (Views, Columns, Iteration Weeks). All enrichment steps use graceful degradation: if a feature is unavailable for the tracker, skip that step and log "Skipped {step}: {tracker} does not support {feature}". (Governing: SPEC-0011, ADR-0012)
For GitHub Projects V2:
design.md for referenced file paths and architectural components, then use Grep to find the primary implementation files (entry points, config, models, routes) relevant to the spec's domain. Include file paths with line numbers pointing to key symbols (class definitions, function signatures, config blocks).
# {Capability Title}
## Spec
- [spec.md]({spec-dir}/{name}/spec.md)
- [design.md]({spec-dir}/{name}/design.md)
## Governing ADRs
- ADR-XXXX: {title}
## Key Files
- {file}:{line} — {description of what this entry point / class / config does}
## Stories
| # | Title | Branch | Status |
|---|-------|--------|--------|
| #{n} | {title} | {branch} | Open |
## Dependencies
- #{n} → #{m} (prerequisite)
Projects > Iteration Weeks (default: 2 weeks). Assign foundation stories to Sprint 1, dependents to Sprint 2, etc.Projects > Views (default: "All Work" table, "Board" board, "Roadmap" roadmap). If a default "Table" view exists, rename it to the first configured view.For Gitea:
Projects > Columns (default: Todo, In Progress, In Review, Done).POST /repos/{owner}/{repo}/issues/{index}/dependencies (or via MCP tools discovered by ToolSearch).For other trackers: Skip tracker-specific enrichment. Log skipped steps in the report.
Auto-label creation (cross-cutting, all trackers): When applying labels in any step (epic label, story label, spec label), use the try-then-create pattern (see references/shared-patterns.md). (Governing: SPEC-0011 REQ "Auto-Create Labels")
Fallback: Generate tasks.md (when no tracker is available). Governing: SPEC-0006, ADR-0007.
Write {spec-dir}/{capability-name}/tasks.md co-located with spec.md and design.md. MUST NOT generate tasks.md when a tracker is available — tasks live in the tracker OR in tasks.md, never both.
Template format:
# Tasks: {Capability Title}
Spec: SPEC-XXXX
Generated: {date}
## 1. {Section Title}
- [ ] 1.1 {Task description} (REQ "{Requirement Name}", SPEC-XXXX)
- [ ] 1.2 {Task description} (REQ "{Requirement Name}", SPEC-XXXX)
## 2. {Section Title}
- [ ] 2.1 {Task description} (REQ "{Requirement Name}", SPEC-XXXX)
Generation rules:
### Requirement: MUST produce at least one task## N. Section Title sections by functional area, ordered by prerequisites- [ ] X.Y Task description where X is section number, Y is task number within section- [x] (completed) vs - [ ] (pending) linesClean up the team when done (if --review was used).
Report the plan. Summarize what was created:
foundation label and their dependent feature stories--no-projects was set)--no-branches)--no-branches)/sdd:prime before starting implementation so agents have architecture contextExample dependency graph output:
### Dependency Graph
Foundation (merge first):
#281 Extract shared LLM client package [foundation]
#282 Stub config fields and route registration [foundation]
Serialized (hotspot: cmd/server/main.go):
#283 Server wiring → #284 Route handlers (sequential)
Parallel (no conflicts):
#285 CLI tool
#286 Batch processor
Order: #281, #282 (foundation) → #283, #285, #286 (parallel) → #284 (after #283)
--review mode)Follow the standard protocol from the plugin's references/shared-patterns.md § "Team Handoff Protocol". The drafter is the planner; the reviewer checks that every spec requirement appears in exactly one story, groupings are functionally cohesive, task checklists correctly reference specs, and dependency ordering is logical.
### Requirement: section in the spec MUST appear in exactly one story's task checklist## Requirements section with a task checklist referencing the spec number, requirement names, normative statements, and WHEN/THEN scenariosbd subtask add) instead of markdown checklistsToolSearch to discover tracker MCP tools at runtime — never assume specific tools are availablereferences/shared-patterns.md to read configuration from CLAUDE.md### SDD Configuration section in CLAUDE.md when a tracker is selected for the first timegh project link, Gitea). Without linking, projects are invisible from the repository's Projects tab.ToolSearch for project tools at runtime--project and --no-projects are mutually exclusive; if both provided, warn and use --no-projects--no-branches disables both ### Branch AND ### PR Convention sectionsreferences/shared-patterns.md) for all label applications — never fail on missing labels (Governing: SPEC-0011 REQ "Auto-Create Labels")Projects > Views, Projects > Columns, Projects > Iteration Weeks are all optional with sensible defaults — do NOT overwrite existing keys when they are absent/sdd:work and /sdd:review — they use the same ### Branch and ### PR Convention structural sections (Governing: SPEC-0010 REQ "Downstream Compatibility")--scrum is set, organize and enrich MUST run automatically after grooming — NEVER require the user to run /sdd:organize or /sdd:enrich separately (Governing: SPEC-0012 REQ "Automatic Organize and Enrich")## Security Checklist section with authentication, input validation, output encoding, rate limiting, and body size limit items (Governing: ADR-0018, SPEC-0016 REQ "Security Checklist in Issues")## Acceptance Criteria and before ### Branch / ### PR Convention sections--scrum run, even if all stories were deferred (Governing: SPEC-0012 REQ "Sprint Report")--scrum and --review are mutually exclusive; if both are provided, --scrum takes precedence and --review is silently ignoredfoundation-labeled stories (Governing: SPEC-0015 REQ "Foundation Story Detection", ADR-0017 Layer 1)## SDD Configuration if present