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.4
-
For 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.3
-
For 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:
- Scan all
### Requirement: sections in the spec and identify the functional areas they affect (e.g., data model, API endpoints, validation, configuration, setup).
- Cluster requirements by functional area cohesion — requirements that affect the same part of the system belong in the same story.
- Apply coupling analysis — requirements that modify the same files or share data structures MUST be placed in the same story.
- Apply dependency ordering — prerequisites go in earlier stories, dependents in later stories.
- Target 3-4 stories for a spec with 10-15 requirements (3-5 requirements per story). For specs with 4 or fewer requirements, create 1-2 stories. For a single-requirement spec, create 1 story.
- Each story SHOULD target a PR in the 200-500 line range. This is a heuristic — functional cohesion takes priority over line-count targets. Do NOT split functionally cohesive requirements across stories solely to meet the line-count target.
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:
- Title: a descriptive name reflecting the story's functional area (e.g., "Setup & Configuration", "Core Auth Flow", "Validation & Error Handling")
- Body MUST include:
- A short description of what this story implements and its governing spec/ADR references
- A
## Requirements section containing a task checklist (see step 5.3)
- Acceptance criteria summarized at the end
- After creating the issue (to obtain the issue number), unless
--no-branches is set, update the issue body to append a ### Branch section:
- Stories:
`feature/{issue-number}-{slug}` (or custom prefix from --branch-prefix or CLAUDE.md Branch Conventions > Prefix)
- Epics:
`epic/{issue-number}-{slug}` (or custom prefix from --branch-prefix or CLAUDE.md Branch Conventions > Epic Prefix)
- The slug MUST be derived from the story title using kebab-case, max 50 chars (or CLAUDE.md
Branch Conventions > Slug Max Length)
- This requires a two-pass approach: create the issue first to get the number, then update the body
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:
- The story implements, modifies, or tests HTTP endpoint handlers or route registrations
- The grouped requirements reference endpoints, routes, middleware, request/response handling, or API paths
- The spec's Security Requirements section (if present) applies to the story's functional area
- The story title or description references: API, endpoint, route, handler, middleware, controller, HTTP, REST, webhook
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:
- The story implements, modifies, or tests HTML templates or server-rendered pages
- The grouped requirements reference templates, browser UI, frontend components, forms, modals, dashboards, or interactive elements
- The story involves JavaScript (inline or external), CSS, or HTMX interactions
- The story title or description references: UI, template, page, form, modal, dialog, dashboard, frontend, component, widget
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:
- Template render tests: Verify that templates produce correct HTML structure for given input data
- JavaScript unit tests: Test inline or external JS functions for correctness
- HTMX integration tests: Verify that HTMX swap targets, triggers, and server responses produce the expected DOM state
Companion test story format:
- Title: "Tests: {Feature Story Title}" (e.g., "Tests: Dashboard Layout and Navigation")
- Body MUST include:
- A reference to the feature story it covers (e.g., "Covers #{feature-issue-number}")
- A
## 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)
- Acceptance criteria for test coverage
- Apply the
test label using the try-then-create pattern (see references/shared-patterns.md)
- The companion test story SHOULD be estimated at no more than half the effort of the feature story
- The companion test story MUST depend on (be blocked by) its corresponding feature story
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:
- The project root (or module root) contains a backend manifest (
go.mod, requirements.txt, Cargo.toml, pom.xml, build.gradle, Gemfile, mix.exs, Package.swift, composer.json, pyproject.toml)
- The spec requirements reference server-side concerns: API endpoints, database operations, background workers, message queues, service boundaries
- The grouped stories involve concurrency, error handling across service boundaries, or database interactions
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
- Title: "CI: Static Analysis, Race Detection, and Formatting for {Capability Title}"
- Apply the
ci and foundation labels using the try-then-create pattern
- The CI story SHOULD be a foundation story (merged before feature stories)
- All language-agnostic: use "static analysis" not "go vet", "race detection" not "-race flag", "formatting" not "gofmt"
Do NOT create a CI story if:
- The spec is purely frontend, documentation, or configuration
- A CI story already exists for this spec (check existing issues)
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:
- Include the tracker-specific close keyword referencing the story issue number
- Include a reference to the parent epic and governing spec
- Tracker-specific close keywords:
- GitHub/Gitea:
Closes #{issue-number}
- GitLab:
Closes #{issue-number} (in MR description)
- Beads:
bd resolve
- Jira:
{PROJECT-KEY}-{number} reference
- Linear:
{TEAM}-{number} reference
- Use CLAUDE.md
PR 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:
- Default (per-epic): For each epic, create a tracker-native project and add the epic and its child stories:
- GitHub: Projects V2 via
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.
- Gitea: Project via MCP tools (use
ToolSearch to discover). MUST ensure the project is associated with the repository.
- GitLab: Milestone or board
- Jira: Use existing project scope (no new project needed)
- Linear: Project or cycle
- Beads: No-op (the epic IS the grouping)
--project <name>: Create a single project with the given name and add all issues to it- Use
ToolSearch to discover project-creation MCP tools at runtime
- Read CLAUDE.md
Projects > 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.
- Repository linking is critical: For trackers that support project-repository associations (GitHub Projects V2, Gitea), the project MUST be linked to the repository after creation. Without this step, the project exists but is invisible from the repository's Projects tab.
- Graceful failure: If project creation fails, warn the user but do not block issue creation. Report the failure in the final summary.
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:
- Set project description: A short summary referencing the spec number and capability title.
- Write project README: Use the GitHub Projects V2 GraphQL API to set the project README field. The README serves as agent-navigable context and SHALL follow this template. To populate the Key Files section, read the spec's
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)
- Add iteration field: Create a "Sprint" iteration field via GraphQL with cycle length from CLAUDE.md
Projects > Iteration Weeks (default: 2 weeks). Assign foundation stories to Sprint 1, dependents to Sprint 2, etc.
- Create named views: Create three views via GraphQL using names from CLAUDE.md
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:
- Create milestones: One milestone per epic. Assign stories to the milestone corresponding to their epic.
- Configure board columns: Create columns from CLAUDE.md
Projects > Columns (default: Todo, In Progress, In Review, Done).
- Create native dependency links: For each story that depends on another, create a native dependency via
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")
