plan

What this skill does

<!-- Governing: ADR-0017 (Parallel Agent Coordination), SPEC-0015 REQ "Foundation Story Detection", SPEC-0015 REQ "Hotspot Analysis" -->
<!-- Governing: ADR-0015 (Markdown-Native Configuration), SPEC-0014 REQ "Config Resolution Pattern" -->

# Plan Sprint from Specification

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.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **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}`.

1. **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.**

2. **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`.

3. **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.
   - Tell the user: "Creating a planning team to break down the spec and review the issue plan. This takes a minute or two."
   - Create a Claude Team with `TeamCreate`:
     - Spawn a **planner** agent (`general-purpose`) to analyze the spec and create the issue breakdown
     - Spawn a **reviewer** agent (`general-purpose`) to review the breakdown for completeness, proper acceptance criteria, and correct dependency ordering
     - The reviewer MUST verify that every spec requirement has at least one corresponding issue
     - If `TeamCreate` fails, fall back to single-agent mode
   - Maximum 2 revision rounds. After that, the reviewer approves with noted concerns.

---

## Scrum Mode Ceremony (`--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."

### Phase 1: Target Resolution

- If a spec was provided in `$ARGUMENTS`: use steps 2 and the spec identification from step 1 to resolve the target spec.
- If no spec was provided: scan all issues currently open in the tracker (detected per step 4) and collect them as the grooming scope. All issues in scope that reference a spec will be cross-checked; issues with no spec reference are flagged for spec proposal.

### Phase 2: Spec Completeness Audit

Before spawning the grooming team, audit every spec referenced by any in-scope issue:

1. For each referenced spec, check if `{spec-dir}/{name}/design.md` exists alongside `spec.md`.
2. If `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}."
3. If a tracker issue has **no backing spec**, generate both `{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}."
4. After all drafts are generated, report the audit results: pass count, missing design.md count, unspec'd issue count, and file paths of generated drafts.

### Phase 3: Issue Decomposition

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).

### Phase 4: Backlog Grooming Ceremony

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.

### Phase 5: Dissent Resolution

For each story with dissent:

1. **Identify the dissenting agent(s)** and extract their specific objection.
2. **One negotiation round**: The lead presents the dissent to the PO and the dissenting agent. Each states their position once. The lead synthesizes a proposed resolution.
3. **Outcome**:
   - If the PO accepts the dissenting agent's revision → apply the revision, finalize the story.
   - If the dissenting agent accepts the PO's justification → finalize the sto