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

## 🚀 MCP Tools Integration (NEW!)

**Enhanced with MCP (Model Context Protocol) tools for advanced codebase analysis:**

### Required MCP Servers
1. **Exa MCP Server** - External API patterns and examples
   - Repository: https://github.com/exa-labs/exa-mcp-server
   - Function: `mcp__exa__get_code_context_exa()` - Get external best practices

2. **Code Index MCP** - Internal codebase exploration
   - Repository: https://github.com/johnhuang316/code-index-mcp
   - Functions:
     - `mcp__code-index__find_files()` - File pattern matching
     - `mcp__code-index__search_code_advanced()` - Advanced code search

### Installation & Setup
Please install these MCP servers to enable enhanced codebase analysis. The workflow will automatically use them when available.

## Usage
```bash
/workflow:plan <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

## Core Workflow

### Analysis & Planning Process
The command performs comprehensive analysis through:

**0. Pre-Analysis Documentation Check** ⚠️ FIRST STEP
- **Selective documentation loading based on task requirements**:
  - **Always check**: `.workflow/docs/README.md` - System navigation and module index
  - **For architecture tasks**: `.workflow/docs/architecture/system-design.md`, `module-map.md`
  - **For specific modules**: `.workflow/docs/modules/[relevant-module]/overview.md`
  - **For API tasks**: `.workflow/docs/api/unified-api.md`
- **Context-driven selection**: Only load documentation relevant to the specific task scope
- **Foundation for analysis**: Use relevant docs to understand affected components and dependencies

**1. Context Gathering & Intelligence Selection**
- Reading relevant CLAUDE.md documentation based on task requirements
- Automatic tool assignment based on complexity:
  - **Simple tasks** (≤3 modules): Direct CLI tools with intelligent path navigation and multi-round analysis
    ```bash
    # Analyze specific directory
    cd "src/auth" && ~/.claude/scripts/gemini-wrapper -p "
    PURPOSE: Analyze authentication patterns
    TASK: Review auth implementation for security patterns
    CONTEXT: Focus on JWT handling and user validation
    EXPECTED: Security assessment and recommendations
    RULES: Focus on security vulnerabilities and best practices
    "

    # Implement in specific directory
    codex -C src/components --full-auto exec "
    PURPOSE: Create user profile component
    TASK: Build responsive profile component with form validation
    CONTEXT: Use existing component patterns
    EXPECTED: Complete component with tests
    RULES: Follow existing component architecture
    " -s danger-full-access
    ```
  - **Complex tasks** (>3 modules): Specialized task agents with autonomous CLI tool orchestration and cross-module coordination
- Flow control integration with automatic tool selection

**2. Project Structure Analysis** ⚠️ CRITICAL PRE-PLANNING STEP
- **Documentation Context First**: Reference `.workflow/docs/` content from `/workflow:docs` command if available
- **Complexity assessment**: Count total saturated tasks
- **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
- **Module boundaries**: Identify relationships and dependencies using existing documentation
- **File grouping**: Cohesive file sets and target_files generation
- **Pattern recognition**: Existing implementations and conventions

**3. Analysis Artifacts Generated**
- **ANALYSIS_RESULTS.md**: Context analysis, codebase structure, pattern identification, task decomposition
- **Context mapping**: Project structure, dependencies, cohesion groups
- **Implementation strategy**: Tool selection and execution approach

## Implementation Standards

### Context Management & Agent Execution

**Agent Context Loading** ⚠️ CRITICAL
The following pre_analysis steps are generated for agent execution:

```json
// Example pre_analysis steps generated by /workflow:plan for agent execution
"flow_control": {
  "pre_analysis": [
    {
      "step": "load_planning_context",
      "action": "Load plan-generated analysis and context",
      "command": "bash(cat .workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md 2>/dev/null || echo 'planning analysis not found')",
      "output_to": "planning_context"
    },
    {
      "step": "mcp_codebase_exploration",
      "action": "Explore codebase structure and patterns using MCP tools",
      "command": "mcp__code-index__find_files(pattern=\"[task_focus_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\", file_pattern=\"[target_extensions]\")",
      "output_to": "codebase_structure"
    },
    {
      "step": "mcp_external_context",
      "action": "Get external API examples and best practices",
      "command": "mcp__exa__get_code_context_exa(query=\"[task_technology] [task_patterns]\", tokensNum=\"dynamic\")",
      "output_to": "external_context"
    },
    {
      "step": "load_dependencies",
      "action": "Retrieve dependency task summaries",
      "command": "bash(cat .workflow/WFS-[session]/.summaries/IMPL-[dependency_id]-summary.md 2>/dev/null || echo 'dependency summary not found')",
      "output_to": "dependency_context"
    },
    {
      "step": "load_documentation",
      "action": "Retrieve relevant documentation based on task scope and requirements",
      "command": "bash(cat .workflow/docs/README.md $(if [[ \"$TASK_TYPE\" == *\"architecture\"* ]]; then echo .workflow/docs/architecture/*.md; fi) $(if [[ \"$TASK_MODULES\" ]]; then for module in $TASK_MODULES; do echo .workflow/docs/modules/$module/*.md; done; fi) $(if [[ \"$TASK_TYPE\" == *\"api\"* ]]; then echo .workflow/docs/api/*.md; fi) CLAUDE.md README.md 2>/dev/null || echo 'documentation not found')",
      "output_to": "doc_context"
    },
    {
      "step": "gather_task_context",
      "action": "Analyze task context and dependencies without implementation",
      "command": "bash(cd \"[task_focus_paths]\" && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze task context and patterns TASK: Review existing patterns and dependencies for '[task_title]' CONTEXT: Task ID [task_id], Focus paths: [task_focus_paths], MCP findings: [codebase_structure] [external_context] EXPECTED: Pattern analysis, dependency mapping, and architectural insights RULES: Focus on understanding existing code patterns, no implementation\")",
      "output_to": "task_context",
      "on_error": "fail"
    }
  ]
}
```

**Context Accumulation Guidelines**:
Flow_control design should follow these principles:
1. **Structure Analysis**: Project hierarchy and patterns
2. **Dependency Mapping**: Previous task summaries → inheritance context
3. **Task Context Generation**: Combined analysis → task.context fields
4. **CLI Tool Analysis**: Use Gemini/Codex appropriately for pattern analysis when needed

**MCP Integration Principles**:
- **Code Index First**: Use `mcp__code-index__` for internal codebase exploration before external tools
- **Exa for Context**: Use `mcp__exa__get_code_context_exa` to supplement with external API patterns and examples
- **Automatic Fallback**: If MCP tools unavailable, workflow uses traditional bash/CLI tools
- **Enhanced Analysis**: MCP tools provide deeper codebase understanding and external best practices

**Benefits of MCP Integration**:
- **Faster Analysis**: Direct codebase indexing vs. manual file searching
- **External Context**: Real-world API patterns and implementation examples
- **Pattern Recognition**: Advanced code pattern matching and similarity detection
- **Comprehensive Coverage**: Both internal code exploration and external best practice lookup

**Implementation Approach Planning**:
Each task's `flow_control.implementation_approach` defines execution strategy (planning phase):

1. **task_description**: Implementation strategy definition:
   - Clear implementation goal to be executed later
   - Planned reference to patterns from pre_analysis results
   - Integration strategy with existing codebase

2. **modification_points**: Planned code modification targets:
   - Specific code changes to be made during execution
   - Planned use of parent task patterns via `[parent]` context
   - Integration points with existing components via `[context]` from dependencies

3. **logic_flow**: Business logic execution plan:
   - Step-by-step workflow to be implemented
   - Planned data flow between components
   - Integration points using `[inherited]` and `[shared]` context

4. **target_files**: Target file specifications for execution:
   - `src/auth/login.ts:handleLogin:75-120` (planned function and line range)
   - `src/middleware/auth.ts:validateToken` (planned function target)
   - Must align with task's `context.focus_paths`

**Variable Reference System**:
- `[design]` - Results from pre_analysis steps
- `[parent]` - Context inherited from parent tasks
- `[context]` - Dependencies from related tasks
- `[inherited]` - Shared context from session
- `[shared]` - Global rules and patterns 

**Content Sources**:
- Task summaries: `.workflow/WFS-[session]/.summaries/`
- Documentation: `.workflow/docs/`, `CLAUDE.md`, `README.md`, config files
- Analysis artifacts: `.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md`
- Dependency contexts: `.workflow/WFS-[session]/.task/IMPL-*.json`

### Task Decomposition Standards

**Rules**:
- **Maximum 10 tasks**: Hard limit - exceeding requires re-scoping
- **Function-based**: Complete functional units with related files (logic + UI + tests + config)
- **File cohesion**: Group tightly coupled components in same task
- **Hierarchy**: Flat (≤5 tasks) | Two-level (6-10 tasks) | Re-scope (>10 tasks)


### Session Management ⚠️ CRITICAL
- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before any planning
- **Multiple sessions support**: Different Claude instances can have different active sessions
- **User selection**: If multiple active sessions found, prompt user to select which one to work with
- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
- **Session continuity**: MUST use selected active session to maintain context
- **⚠️ Dependency context**: MUST read ALL previous task summary documents from selected session before planning
- **Session isolation**: Each session maintains independent context and state


**Task Patterns**:
- ✅ **Correct (Function-based)**: `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- ❌ **Wrong (File/step-based)**: `IMPL-001: Create database model`, `IMPL-002: Create API endpoint`


## Document Generation

**Workflow**: Identifier Creation → Folder Structure → IMPL_PLAN.md → .task/IMPL-NNN.json → TODO_LIST.md

**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
- **.process/ANALYSIS_RESULTS.md**: Analysis results and planning artifacts

**Document Structure**:
```
.workflow/WFS-[topic]/
├── IMPL_PLAN.md          # Main planning document
├── TODO_LIST.md          # Progress tracking (if complex)
├── .process/
│   └── ANALYSIS_RESULTS.md  # Analysis results and planning artifacts
└── .task/
    ├── IMPL-001.json     # Task definitions with flow_control
    └── IMPL-002.json
```

### IMPL_PLAN.md Structure ⚠️ REQUIRED FORMAT

**File Header** (required)：
- **Identifier**: Unique project identifier and session ID, format WFS-[topic]
- **Source**: Input type, e.g. "User requirements analysis"
- **Analysis**: Analysis document reference

**Summary** (execution overview)：
- Concise description of core requirements and objectives
- Technical direction and implementation approach

**Context Analysis** (context analysis)：
- **Project** - Project type and architectural patterns
- **Modules** - Involved modules and component list
- **Dependencies** - Dependency mapping and constraints
- **Patterns** - Identified code patterns and conventions

**Task Breakdown** (task decomposition)：
- **Task Count** - Total task count and complexity level
- **Hierarchy** - Task organization structure (flat/hierarchical)
- **Dependencies** - Inter-task dependency graph

**Implementation Plan** (implementation plan)：
- **Execution Strategy** - Execution strategy and methodology
- **Resource Requirements** - Required resources and tool selection
- **Success Criteria** - Success criteria and acceptance conditions


## Reference Information

### 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[] }

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

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

## Planning-Only Constraint
This command creates implementation plans but does not execute them.
Use `/workflow:execute` for actual implementation.