# Plan

> Entry point for feature planning workflow. Guides users through PRD creation, spec generation, and swarm design with automatic context management.

- Skill: `l3wi/plan` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add l3wi/plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/plan

---


# Plan Skill

Unified entry point for the complete feature planning workflow. Progressively guides through product requirements, technical specification, and implementation task design. First step in the three-prong development workflow: **Plan → Implement → Validate**.

## Workflow

```
/skill:plan [feature-name]
    ↓
Phase 1: PRD (requirements gathering via interview)
    ↓
Phase 2: Spec (technical architecture with research validation)
    ↓
Phase 3: Tasks (implementation plan generation)
    ↓
HANDOFF → /skill:swarm for execution
```

## Usage

```bash
/skill:plan [feature-name]               # Interactive — auto-detects phase
/skill:plan [feature-name] --prd         # Force PRD creation
/skill:plan [feature-name] --spec        # Force spec creation (requires PRD)
/skill:plan [feature-name] --resume      # Resume interrupted workflow
/skill:plan [feature-name] --quick       # Quick mode PRD (5 questions)
```

## Prerequisites

- **Initialized project** with agents-workflow system (see `/skill:init`)
- **For --spec**: PRD must exist at `docs/prds/{feature-name}.md`
- **For task generation**: Spec must exist at `docs/specs/{feature-name}-spec.md`

## Phase Detection

Analyze existing files to determine the starting phase:

| Files Found | Action |
|-------------|--------|
| No PRD, no spec | Start at Phase 1 (PRD) |
| PRD exists, no spec | Start at Phase 2 (Spec) |
| Both PRD and spec | Start at Phase 3 (Tasks via design-swarm) |
| Spec but no PRD | Warn — offer to create PRD retroactively or proceed |

Display what was found and the recommendation. Wait for user confirmation before proceeding.

## Phase 1: Product Requirements (PRD)

> **Before starting this phase**, read the [PRD Interview Guide](references/prd-interview-guide.md) and [PRD Template](references/prd-template.md).

**Goal**: Capture "what" and "why" — never "how".

### Steps

1. **Initialize**: Use feature-name or ask for one. Check if `docs/prds/{feature-name}.md` exists.
2. **Interview**: Conduct structured interview using the interview guide.
   - Quick mode (`--quick`): 5-7 questions covering problem, users, capabilities, success, risks
   - Comprehensive mode: 8 topic areas with adversarial probing
3. **Generate PRD**: Read `docs/prds/_template.md`, populate from interview, write to `docs/prds/{feature-name}.md`
4. **Review**: Present summary. Offer: refine, approve, or stop.

### Quality Gate

Before proceeding, verify the PRD has:
- [ ] Specific problem statement with quantified impact
- [ ] Defined target users with use cases
- [ ] Measurable goals tied to business objectives
- [ ] Explicit scope boundaries (in/out)
- [ ] Testable user stories
- [ ] Success metrics with baselines and targets

### Transition

```
✅ PRD created: docs/prds/{feature-name}.md

Continue with technical specification? [Y/n]
  Yes → Save context summary to .plan-{feature}.json, proceed to Phase 2
  No  → End here (resume later with /skill:plan {feature-name})
```

## Phase 2: Technical Specification

> **Before starting this phase**, read the [Spec Template](references/spec-template.md) and [ADR Template](references/adr-template.md).

**Goal**: Create implementation blueprint with research-validated technical decisions.

### Steps

1. **Load context**: Read PRD from `docs/prds/{feature-name}.md`. Check `docs/reviews/` for related reviews.
2. **Research phase**: Validate technical decisions using available tools:
   - `context7_resolve-library-id` + `context7_query-docs`: Library resolution, API docs, version compatibility
   - `exa_web_search_exa`: Implementation patterns, benchmarks, competitive analysis
   - `exa_get_code_context_exa`: Code examples (fallback when Context7 insufficient)
3. **Codebase analysis**: Understand existing patterns, dependencies, pain points.
4. **Enrich project AGENTS.md**: If `.pi/AGENTS.md` is a stub (has unfilled placeholders), populate it from the codebase analysis:
   - Detect tech stack from config files (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.)
   - Extract commands (dev, test, lint, build) from scripts/taskfile
   - Map project structure (key directories and their purpose)
   - Note conventions discovered during codebase analysis
   - This ensures all future agents spawned on the project have project-specific context
5. **Draft spec**: Read `docs/specs/_template.md`, populate all sections including:
   - Architecture overview, data models, API design
   - Alternative approaches (minimum 2)
   - Security, performance, reliability considerations
   - Implementation phases with testing strategy
5. **Architecture review** (unless `--skip-review`): Validate against quality criteria.
6. **Generate ADRs**: For significant decisions, create `docs/decisions/ADR-XXXX-*.md` using `docs/decisions/_adr-template.md`.
7. **Write spec**: Save to `docs/specs/{feature-name}-spec.md`.

### Spec Types

| Input Source | Spec Type | Key Difference |
|-------------|-----------|----------------|
| PRD only | Feature spec | User stories drive design |
| Review findings (`--from-review`) | Improvement spec | Before/after state, migration strategy, rollback plan |
| PRD + review | Enhanced feature spec | Feature + known issues addressed |

### Implementation Details Section

Every spec must include:
```markdown
## Implementation Details
**Feature Branch**: `feat/{feature-name}`
**Base Branch**: `dev`
**Testing**: Unit 80% min coverage, integration for all non-UI components
```

### Quality Gate

Before proceeding, verify the spec has:
- [ ] Every PRD requirement mapped to technical detail
- [ ] Complete data models and API contracts (including error cases)
- [ ] At least 2 alternative approaches considered
- [ ] Security implications addressed
- [ ] Testing strategy with specific coverage targets
- [ ] Work broken into implementable phases

### Transition

```
✅ Spec created: docs/specs/{feature-name}-spec.md

Continue with implementation planning? [Y/n]
  Yes → Proceed to Phase 3
  No  → End here
```

## Phase 3: Task Generation

> **Before starting this phase**, read the [Task Design Guide](references/task-design-guide.md).

**Goal**: Break spec phases into executable tasks with dependency tracking.

### Steps

1. **Load spec phases** from `docs/specs/{feature-name}-spec.md` Implementation Plan section
2. **Extract phases** — identify tasks, file targets, and dependencies
3. **Analyze dependencies** — build graph of sequential vs parallel phases
4. **Validate parallel safety** — ensure no file conflicts between parallel phases
5. **Generate execution batches** — group phases by dependency tiers
6. **Write plan file** to `docs/plans/{feature-name}.md`
7. **Write task files** to `docs/tasks/{feature-name}-phase-{n}.md` (one per phase)

### Planning Complete

```
✅ PLANNING COMPLETE

Generated artifacts:
  - docs/prds/{feature-name}.md
  - docs/specs/{feature-name}-spec.md
  - docs/plans/{feature-name}.md
  - docs/tasks/{feature-name}-phase-*.md
  - docs/decisions/ADR-*.md (if any)

HANDOFF → /skill:swarm {feature-name}
```

**Do not implement directly** — use `/skill:swarm` for proper orchestration.

## Context Management

### State File (`.plan-{feature}.json`)

Saved between phases for resume capability:
```json
{
  "feature": "user-dashboard",
  "phase": "spec",
  "prdFile": "docs/prds/user-dashboard.md",
  "prdSummary": "Key requirements summary...",
  "timestamp": "2024-01-30T22:00:00.000Z"
}
```

### Tree Navigation

Each phase gets a clean context branch:
```
main
├── prd-{feature}    (PRD interview conversation)
└── spec-{feature}   (Clean spec creation context)
```

### Resume

`/skill:plan {feature} --resume` loads `.plan-{feature}.json` and continues from the saved phase.

## Error Handling

| Error | Resolution |
|-------|------------|
| No project setup | Prompt `/skill:init` or `/skill:init --setup` |
| Missing PRD for spec | Prompt to start with Phase 1 |
| Corrupted state file | Prompt user to choose phase manually |
| Spec has no phases | Prompt to add Implementation Plan section |

## Complete Development Lifecycle

```bash
/skill:plan feature-name       # Plan: PRD → Spec → Tasks
/skill:swarm feature-name      # Implement: Parallel agents
/skill:validate-plan feature-name   # Validate: Tests + spec compliance
```

## Related Skills

- `/skill:swarm` — Parallel execution with agents (next step)
- `/skill:validate-plan` — Spec compliance verification (final step)
- `/skill:review-codebase` — Generate review findings (alternative input for Phase 2)