Claude-Code-Workflow/.claude/commands/workflow/plan.md

---
name: plan
description: Create implementation plans with intelligent input detection
usage: /workflow:plan <input>
argument-hint: "text description"|file.md|ISS-001
examples:
  - /workflow:plan "Build authentication system"
  - /workflow:plan requirements.md
  - /workflow:plan ISS-001
---

# Workflow Plan Command

## Usage
```bash
/workflow:plan [--AM gemini|codex] [--analyze|--deep] <input>
```

## Input Detection
- **Files**: `.md/.txt/.json/.yaml/.yml` → Reads content and extracts requirements
- **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and acceptance criteria
- **Text**: Everything else → Parses natural language requirements

## Analysis Levels
- **Quick** (default): Structure only (5s)
- **--analyze**: Structure + context analysis (30s)
- **--deep**: Structure + comprehensive parallel analysis (1-2m)

## Core Rules

### File Structure Reference
**Architecture**: @~/.claude/workflows/workflow-architecture.md

### Task Limits & Decomposition
- **Maximum 10 tasks**: Hard enforced limit - projects exceeding must be re-scoped
- **Function-based decomposition**: By complete functional units, not files/steps
- **File cohesion**: Group related files (UI + logic + tests + config) in same task
- **Task saturation**: Merge "analyze + implement" by default (0.5 count for complex prep tasks)

### Core Task Decomposition Standards
1. **Functional Completeness Principle** - Each task must deliver a complete, independently runnable functional unit including all related files (logic, UI, tests, config)

2. **Minimum Size Threshold** - A single task must contain at least 3 related files or 200 lines of code; content below this threshold must be merged with adjacent features

3. **Dependency Cohesion Principle** - Tightly coupled components must be completed in the same task, including shared data models, same API endpoints, and all parts of a single user flow

4. **Hierarchy Control Rule** - Use flat structure for ≤5 tasks, two-level structure for 6-10 tasks, and mandatory re-scoping into multiple iterations for >10 tasks

### Pre-Planning Analysis (CRITICAL)
⚠️ **Must complete BEFORE generating any plan documents**
1. **Complexity assessment**: Count total saturated tasks
2. **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
3. **File grouping**: Identify cohesive file sets
4. **Quantity prediction**: Estimate main tasks, subtasks, container vs leaf ratio

### Session Management
- **Active session check**: Check for `.workflow/.active-*` marker first
- Auto-creates new session: `WFS-[topic-slug]`
- Uses existing active session if available
- **Dependency context**: MUST read previous task summary documents before planning

### Project Structure Analysis
**Always First**: Run project hierarchy analysis before planning
```bash
# Get project structure with depth analysis
~/.claude/scripts/get_modules_by_depth.sh

# Results populate task paths automatically
# Used for focus_paths and target_files generation
```

**Structure Integration**:
- Identifies module boundaries and relationships
- Maps file dependencies and cohesion groups
- Populates task.context.focus_paths automatically
- Enables precise target_files generation

## Task Patterns

### ✅ Correct (Function-based)
- `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- `IMPL-002: Data export functionality` (service + routes + UI + utils + tests)

### ❌ Wrong (File/step-based)
- `IMPL-001: Create database model`
- `IMPL-002: Create API endpoint`
- `IMPL-003: Create frontend component`

## Output Documents

### Always Created
- **IMPL_PLAN.md**: Requirements, task breakdown, success criteria
- **Session state**: Task references and paths

### Auto-Created (complexity > simple)
- **TODO_LIST.md**: Hierarchical progress tracking
- **.task/*.json**: Individual task definitions with flow_control

### Document Structure
```
.workflow/WFS-[topic]/
├── IMPL_PLAN.md          # Main planning document
├── TODO_LIST.md          # Progress tracking (if complex)
└── .task/
    ├── IMPL-001.json     # Task definitions
    └── IMPL-002.json
```

## Task Saturation Assessment
**Default Merge** (cohesive files together):
- Functional modules with UI + logic + tests + config
- Features with their tests and documentation
- Files sharing common interfaces/data structures

**Only Separate When**:
- Completely independent functional modules
- Different tech stacks or deployment units
- Would exceed 10-task limit otherwise

## Task JSON Schema (5-Field Architecture)
Each task.json uses the workflow-architecture.md 5-field schema:
- **id**: IMPL-N[.M] format (max 2 levels)
- **title**: Descriptive task name
- **status**: pending|active|completed|blocked|container
- **meta**: { type, agent }
- **context**: { requirements, focus_paths, acceptance, parent, depends_on, inherited, shared_context }
- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }

## Execution Integration
Documents created for `/workflow:execute`:
- **IMPL_PLAN.md**: Context loading and requirements
- **.task/*.json**: Agent implementation context
- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes)

## Error Handling
- **Vague input**: Auto-reject ("fix it", "make better", etc.)
- **File not found**: Clear suggestions
- **>10 tasks**: Force re-scoping into iterations

## Context Acquisition Strategy

### Analysis Method Selection (--AM)
- **gemini** (default): Pattern analysis, architectural understanding
- **codex**: Autonomous development, intelligent file discovery

### Detailed Context Gathering Commands

#### Gemini Analysis Templates
```bash
# Module pattern analysis
cd [module] && ~/.claude/scripts/gemini-wrapper -p "Analyze patterns, conventions, and file organization in this module"

# Architectural analysis
cd [module] && ~/.claude/scripts/gemini-wrapper -p "Analyze [scope] architecture, relationships, and integration points"

# Cross-module dependencies
~/.claude/scripts/gemini-wrapper -p "@{src/**/*} @{CLAUDE.md} analyze module relationships and dependencies"

# Similar feature analysis
cd [module] && ~/.claude/scripts/gemini-wrapper -p "Find 3+ similar [feature_type] implementations and their patterns"
```

#### Codex Analysis Templates
```bash
# Architectural analysis
codex -s workspace-write --full-auto exec "analyze [scope] architecture and identify optimization opportunities"

# Pattern-based development
codex -s workspace-write --full-auto exec "analyze existing patterns for [feature] implementation with concrete examples"

# Project understanding
codex -s workspace-write --full-auto exec "analyze project structure, conventions, and development requirements"

# Modernization analysis
codex -s workspace-write --full-auto exec "identify modernization opportunities and refactoring priorities"
```

### Context Accumulation & Inheritance
**Context Flow Process**:
1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
2. **Pattern Analysis**: Tool-specific commands → existing patterns
3. **Dependency Mapping**: Previous task summaries → inheritance context
4. **Task Context Generation**: Combined analysis → task.context fields

**Context Inheritance Rules**:
- **Parent → Child**: Container tasks pass context to subtasks via `context.inherited`
- **Dependency → Dependent**: Previous task summaries loaded via `context.depends_on`
- **Session → Task**: Global session context included in all tasks
- **Module → Feature**: Module patterns inform feature implementation context

### Variable System & Path Rules
**Flow Control Variables**: Use `[variable_name]` format (see workflow-architecture.md)
- **Step outputs**: `[dependency_context]`, `[pattern_analysis]`
- **Task properties**: `[depends_on]`, `[focus_paths]`, `[parent]`
- **Commands**: Wrapped in `bash()` with error handling strategies

**Focus Paths**: Concrete paths only (no wildcards)
- Use `get_modules_by_depth.sh` results for actual directory names
- Include both directories and specific files from requirements
- Format: `["src/auth", "tests/auth", "config/auth.json"]`