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

/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 and PRD Template.

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 and ADR Template.

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
6. Architecture review (unless --skip-review): Validate against quality criteria.
7. Generate ADRs: For significant decisions, create docs/decisions/ADR-XXXX-*.md using docs/decisions/_adr-template.md.
8. 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:

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

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:

{
  "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

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