am2rican5:sdd-workflow

What this skill does

# SDD Workflow

## Critical Rules

- ALWAYS start with Phase 1 (Specify) — never skip to implementation without a spec
- NEVER proceed to the next phase until the current phase's artifact exists and is confirmed
- ALWAYS persist phase artifacts to files — memory is files, not conversation
- WHEN resuming an interrupted workflow, detect existing artifacts and resume from the correct phase
- NEVER let Phase 3 (Implement) start without both a spec AND a plan (unless in lightweight mode)
- WHEN the user wants to skip phases, explain the value of each phase but respect their decision if they insist

## Instructions

### Step 0: Detect Existing Workflow State

Before starting, check for existing artifacts from a previous session:

1. Look for `specs/<feature-name>.md` — if exists, Phase 1 is done
2. Look for `specs/<feature-name>.plan.md` — if exists, Phase 2 is done
3. Look for `specs/<feature-name>.validation.md` — if exists, Phase 4 is done

IF existing artifacts found:
- Show the user what exists and which phase to resume from
- Ask: "Found existing artifacts. Resume from Phase N, or start fresh?"

IF no artifacts found → proceed to Step 1.

### Step 1: Determine Rigor Level and Mode

Analyze the user's feature description to select the workflow mode:

**Lightweight Mode** (auto-detected for small changes):
- Change affects 1-2 files with clear scope
- User describes a bug fix, small tweak, or minor addition
- Workflow: Write acceptance criteria → Implement → Validate (skip formal plan)

**Full Mode** (default for everything else):
- Workflow: Specify → Plan → Implement → Validate

**Rigor Level** (see `references/rigor-levels.md` for details):
- **spec-first** (default): Spec guides initial development, may not be maintained
- **spec-anchored**: Spec maintained alongside code, both evolve together
- **spec-as-source**: Spec IS the source, code generated from it

Announce the selected mode and rigor level. If the user mentioned "API", "contract", "long-term", "team", or "shared", recommend spec-anchored and explain why.

If the user explicitly requests a specific rigor level, use it.

### Step 2: Phase 1 — Specify

**Goal:** Produce a spec file at `specs/<feature-name>.md`

**Option A: Delegate to spec-writer skill**
If the feature needs deep elicitation (complex, unclear, many stakeholders):
> "This feature would benefit from a detailed specification. I'll use the spec-writer skill to guide you through it."

Use the Skill tool to invoke `spec-writer` with the feature description.

**Option B: Inline spec creation**
For straightforward features where the user has already described clear requirements:
1. Draft a spec directly using the spec-writer format (Purpose, Rigor Level, Acceptance Criteria, Edge Cases, Constraints)
2. Present it for confirmation
3. Write to `specs/<feature-name>.md`

**Phase 1 is complete when** `specs/<feature-name>.md` exists and the user has confirmed it.

### Step 3: Phase 2 — Plan

**Goal:** Produce an implementation plan at `specs/<feature-name>.plan.md`

Invoke the spec-planner agent using the Task tool:

```
Task tool call:
  subagent_type: "spec-planner"
  prompt: "Read the spec at specs/<feature-name>.md and produce an implementation plan. Scan the codebase for existing patterns and relevant code. Output the plan to specs/<feature-name>.plan.md"
```

Wait for the agent to complete and read the generated plan.

Present the plan to the user:
> "Here's the implementation plan. Review the architecture decisions and task breakdown. Should we proceed, or adjust anything?"

**Phase 2 is complete when** the plan file exists and the user approves it.

**In lightweight mode:** Skip this phase. The acceptance criteria from the spec serve as the implementation guide.

### Step 4: Phase 3 — Implement

**Goal:** Build the feature according to the plan (or spec in lightweight mode)

This phase is user-driven. The skill provides structure, not automation:

1. Display the task list from the plan (or acceptance criteria in lightweight mode)
2. For each task:
   - Announce which task is being worked on
   - Implement the required changes
   - Mark the task complete
   - Briefly verify the change works
3. Track progress: "Completed N/M tasks"

**During implementation, watch for:**
- Requirements that don't match the plan → pause and suggest updating artifacts
- Missing acceptance criteria discovered during coding → note them for the validate phase
- Blockers or unclear requirements → pause and ask the user

**Phase 3 is complete when** all plan tasks (or acceptance criteria) are addressed.

### Step 5: Phase 4 — Validate

**Goal:** Verify implementation matches the spec. Produce a validation report.

Invoke the spec-validator agent using the Task tool:

```
Task tool call:
  subagent_type: "spec-validator"
  prompt: "Read the spec at specs/<feature-name>.md. Validate the implementation against all acceptance criteria and edge cases. Write the report to specs/<feature-name>.validation.md"
```

Wait for the agent to complete and read the validation report.

Present the report to the user with a summary:

**If PASS:** "All acceptance criteria met. Implementation is complete."

**If PARTIAL:** "N/M criteria met. Here's what's missing: [list]. Would you like to address these now?"

**If FAIL:** "Significant gaps found. Here are the issues: [list]. Let's fix these before considering this done."

For spec-anchored rigor: remind the user that the spec should be updated if implementation legitimately diverged from the original spec.

### Step 6: Completion

When all four phases are done:
1. Summarize what was built
2. List all artifacts created (spec, plan, validation report)
3. Note the rigor level and any maintenance implications
4. If spec-anchored: remind user to update spec when behavior changes in the future

## Examples

### Example 1: Full Workflow

```
User: "I want to add OAuth2 login to my app using spec-driven development"

SDD Workflow:
→ Detected: "login" + "OAuth2" = auth feature, multi-file change
→ Mode: Full workflow
→ Rigor: Recommending spec-anchored (auth is security-critical, shared)

Phase 1 (Specify): Delegating to spec-writer...
  [spec-writer guides user through OAuth2 spec creation]
  ✓ Spec written to specs/oauth2-login.md

Phase 2 (Plan): Invoking spec-planner agent...
  [agent analyzes codebase and generates plan]
  ✓ Plan written to specs/oauth2-login.plan.md
  "Here's the plan with 8 tasks. Review and approve?"

Phase 3 (Implement): Working through tasks...
  Task 1/8: Add OAuth2 client configuration ✓
  Task 2/8: Create callback endpoint ✓
  ...
  Task 8/8: Add session management ✓

Phase 4 (Validate): Invoking spec-validator agent...
  ✓ All 12 acceptance criteria met
  ✓ 5/6 edge cases covered (1 marked UNCLEAR - manual verification needed)
  Report: specs/oauth2-login.validation.md
```

### Example 2: Lightweight Mode

```
User: "Fix the off-by-one error in the pagination component"

SDD Workflow:
→ Detected: 1-2 files, bug fix, clear scope
→ Mode: Lightweight (skip formal plan)
→ Rigor: spec-first

Phase 1: Quick acceptance criteria:
  AC1: Given page 1 with 10 items per page, when requesting page 2, then items 11-20 are shown
  AC2: Given the last page, when displayed, then only remaining items shown (no duplicates)
  ✓ Spec written to specs/pagination-fix.md

Phase 3: Implementing fix...
  ✓ Fixed offset calculation in pagination.ts

Phase 4: Validating...
  ✓ Both acceptance criteria met
```

## Troubleshooting

### User wants to skip Specify phase
**Cause:** They feel it's overhead for a "simple" change.
**Solution:** Explain value: "Specs prevent rework by clarifying requirements upfront. Even 2-3 acceptance criteria help." If they insist, let them proceed but note the risk of rework.

### Plan doesn't match spec
**Cause:** The spec-planner agent missed acceptance criteria or misinterpreted constraints.
**Solution:** Phase 2 should be re-run. The plan must address every acceptance criterion in the spec.