s-plan

name	s-plan
description	Create implementation roadmap with phases, tasks, and dependencies from requirements

/s:plan - Implementation Roadmap

You are creating a detailed implementation roadmap from the gathered requirements. This skill transforms REQUIREMENTS.md into a phased ROADMAP.md with actionable tasks.

Prerequisites

Before starting, read and verify:

1. .planning/REQUIREMENTS.md exists and has content. If not: "No requirements found. Run /s:discuss first."
2. Read .planning/PROJECT.md for project vision and constraints.
3. Read .planning/STATE.md for current state.
4. Read the TDD protocol at ${CLAUDE_PLUGIN_ROOT}/lib/tdd-protocol.md for task structure guidance.

If any docs/brainstorms/ files exist, read the most recent ones for additional context.

Step 1: Architecture Brainstorm

Before creating the roadmap, brainstorm 2-3 architecture approaches. For each approach:

1. Name the approach (e.g., "Monolith-first", "Microservices", "Serverless")
2. Describe the high-level architecture in 3-5 sentences
3. List pros (2-3 bullet points)
4. List cons (2-3 bullet points)
5. Complexity estimate (Low / Medium / High)
6. Best for (what scenarios favor this approach)

Present all approaches to the user and recommend one with a clear rationale. Wait for user confirmation before proceeding.

If the tech stack is already decided (from PROJECT.md or REQUIREMENTS.md), focus the brainstorm on architectural patterns within that stack rather than stack selection.

Step 2: Break Requirements into Phases

Group requirements into implementation phases following these principles:

1. Dependencies first: foundational requirements before dependent ones
2. Vertical slices: each phase should deliver visible, testable value
3. Risk frontloading: tackle uncertain/complex requirements early
4. 3-7 phases typical: most projects have 3-7 phases for v1
5. Each phase: 1-5 tasks: keep phases manageable

For each phase, define:

• Phase number and name (e.g., "Phase 1: Foundation")
• Goal: one sentence describing what this phase achieves
• Success criteria: measurable conditions for phase completion
• Requirements covered: which R{N} and NF{N} IDs are addressed
• Dependencies: which phases must complete first
• Tasks: numbered list of implementation tasks

Task Structure

Each task should follow TDD-compatible structure:

Task {N}: {title}
  - What: {what to implement}
  - Test: {what test to write first}
  - Files: {which files will be created/modified}
  - Acceptance: {how to verify it works}
  - Estimate: S/M/L (Small: <1hr, Medium: 1-4hr, Large: 4hr+)

Step 3: Write ROADMAP.md

Write .planning/ROADMAP.md with this structure:

# Roadmap

## Architecture
**Approach:** {chosen approach name}
**Rationale:** {why this approach was chosen}
**Key decisions:**
- {decision 1}
- {decision 2}

## Phase Overview

| Phase | Name | Goal | Tasks | Dependencies | Status |
|-------|------|------|-------|--------------|--------|
| 1 | {name} | {goal} | {count} | - | pending |
| 2 | {name} | {goal} | {count} | Phase 1 | pending |
| ... | ... | ... | ... | ... | ... |

---

## Phase 1: {Name}

**Goal:** {one sentence}
**Success Criteria:**
- [ ] {criterion 1}
- [ ] {criterion 2}

**Requirements:** R1, R2, NF1

### Tasks

#### Task 1.1: {Title}
- **What:** {description}
- **Test first:** {what test to write}
- **Files:** {file list}
- **Acceptance:** {verification method}
- **Estimate:** {S/M/L}

#### Task 1.2: {Title}
...

---

## Phase 2: {Name}
...

Step 4: Create Phase 1 Plan

Create the directory and detailed plan for the first phase:

1. Create .planning/phases/1/ directory
2. Write .planning/phases/1/PLAN.md:

# Phase 1: {Name}

**Status:** pending
**Started:** -
**Completed:** -

## Goal
{expanded goal description}

## Tasks

### Task 1.1: {Title}
**Status:** pending

**Description:**
{detailed description of what to implement}

**TDD Approach:**
1. Write test: {describe the test}
2. Run test (should FAIL - RED)
3. Implement: {describe minimal implementation}
4. Run test (should PASS - GREEN)
5. Refactor: {what to clean up}

**Files to create/modify:**
- {file 1}: {what goes here}
- {file 2}: {what goes here}

**Acceptance Criteria:**
- [ ] {criterion}
- [ ] {criterion}

---

### Task 1.2: {Title}
...

3. Write .planning/phases/1/CONTEXT.md:

# Phase 1 Context

## What this phase is about
{2-3 sentences}

## Key decisions made
- {decision from brainstorm}

## Dependencies
- {what must exist before this phase starts}

## Reference
- Architecture approach: {name} (see ROADMAP.md)
- Requirements: {list of R/NF IDs}

Step 5: Update STATE.md

Update .planning/STATE.md:

• Status: planned
• Active Phase: 1
• Current Focus: "Phase 1: {name} - Ready to implement. {N} tasks."
• Add decision entry: {DATE} | Architecture: {approach} | {rationale summary}
• Add decision entry: {DATE} | Roadmap created | {N} phases, {M} total tasks

Step 6: Suggest Next Step

Output to the user:

Roadmap created with {N} phases and {M} total tasks.

Architecture: {approach name}
Phase 1: {phase name} ({task count} tasks)

Saved to:
  .planning/ROADMAP.md           - Full roadmap
  .planning/phases/1/PLAN.md     - Phase 1 detailed plan
  .planning/phases/1/CONTEXT.md  - Phase 1 context

Next step: Run `/s:build` to start implementing Phase 1 with TDD.

Optional:
  - Run `/s:ceo-review` for product perspective review of the plan
  - Run `/s:eng-review` for technical review of the architecture
  - Run `/s:brainstorm` to explore a specific aspect deeper before building

Planning Principles

• Prefer smaller phases over larger ones. A phase with 2 tasks is better than one with 8.
• Every task must be testable. If you cannot describe a test for it, the task is too vague.
• Infrastructure tasks go in Phase 1. Project setup, DB schema, auth scaffold, CI pipeline.
• User-facing features start in Phase 2. Phase 1 is the skeleton; Phase 2+ adds flesh.
• Each phase should produce a runnable state. No phase should leave the project broken.
• Include refactoring phases. If Phase 1-3 are rapid feature work, Phase 4 can be cleanup.
• Do not over-plan. Later phases can be less detailed. Phase 1 needs full detail. Phase N can be "TBD based on learnings from Phase N-1."
• Cross-reference requirement IDs. Every R{N} and NF{N} should appear in at least one phase. If a requirement is not covered, flag it.