plan

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

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)