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

---
name: plan
description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---

# Workflow Plan Command (/workflow:plan)

## Coordinator Role

**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.

**Execution Model - Auto-Continue Workflow with Quality Gate**:

This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phases 3 and 4 are delegated to specialized agents for complex analysis and task generation.

1. **User triggers**: `/workflow:plan "task"`
2. **Phase 1 executes** → Session discovery → Auto-continues
3. **Phase 2 executes** → Context gathering → Auto-continues
4. **Phase 3 executes** (cli-execution-agent) → Intelligent analysis → Auto-continues
5. **Phase 3.5 executes** → **Pauses for user Q&A** → User answers clarification questions → Auto-continues
6. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary

**Auto-Continue Mechanism**:
- TodoList tracks current phase status
- After each phase completion, automatically executes next pending phase
- **Phase 3.5 requires user interaction** - answers clarification questions (up to 5)
- If no ambiguities found, Phase 3.5 auto-skips and continues to Phase 4
- Progress updates shown at each phase for visibility

**Execution Modes**:
- **Manual Mode** (default): Use `/workflow:tools:task-generate`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands

## Core Rules

1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
3. **Parse Every Output**: Extract required data from each command/agent output for next phase
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite after every phase completion
6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis

## 5-Phase Execution

### Phase 1: Session Discovery
**Command**: `SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")`

**Task Description Structure**:
```
GOAL: [Clear, concise objective]
SCOPE: [What's included/excluded]
CONTEXT: [Relevant background or constraints]
```

**Example**:
```
GOAL: Build JWT-based authentication system
SCOPE: User registration, login, token validation
CONTEXT: Existing user database schema, REST API endpoints
```

**Parse Output**:
- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`)

**Validation**:
- Session ID successfully extracted
- Session directory `.workflow/[sessionId]/` exists

**TodoWrite**: Mark phase 1 completed, phase 2 in_progress

**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2

---

### Phase 2: Context Gathering
**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[structured-task-description]\"")`

**Use Same Structured Description**: Pass the same structured format from Phase 1

**Input**: `sessionId` from Phase 1

**Parse Output**:
- Extract: context-package.json path (store as `contextPath`)
- Typical pattern: `.workflow/[sessionId]/.context/context-package.json`

**Validation**:
- Context package path extracted
- File exists and is valid JSON

**TodoWrite**: Mark phase 2 completed, phase 3 in_progress

**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3

---

### Phase 3: Intelligent Analysis (Agent-Delegated)

**Command**: `Task(subagent_type="cli-execution-agent", description="Intelligent Analysis", prompt="...")`

**Agent Task Prompt**:
```
Analyze project requirements and generate comprehensive solution blueprint for session [sessionId].

Context: Load context package from [contextPath]
Output: Generate ANALYSIS_RESULTS.md in .workflow/[sessionId]/.process/

Requirements:
- Review context-package.json and discover additional relevant files
- Analyze architecture patterns, data models, and dependencies
- Identify technical constraints and risks
- Generate comprehensive solution blueprint
- Include task breakdown recommendations

Session: [sessionId]
Mode: analysis (read-only during discovery, write for ANALYSIS_RESULTS.md)
```

**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2

**Agent Execution**:
- Phase 1: Understands analysis intent, extracts keywords
- Phase 2: Discovers additional context via MCP code-index
- Phase 3: Enhances prompt with discovered patterns
- Phase 4: Executes with Gemini (analysis mode), generates ANALYSIS_RESULTS.md
- Phase 5: Routes output to session directory

**Parse Output**:
- Agent returns execution log path
- Verify ANALYSIS_RESULTS.md created by agent

**Validation**:
- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
- Contains task recommendations section
- Agent execution log saved to `.workflow/[sessionId]/.chat/`

**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress

**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.5

**Memory State Check**:
- Evaluate current context window usage and memory state
- If memory usage is high (>110K tokens or approaching context limits):
  - **Command**: `SlashCommand(command="/compact")`
  - This optimizes memory before proceeding to Phase 3.5
- Memory compaction is particularly important after analysis phase which may generate extensive documentation
- Ensures optimal performance and prevents context overflow

---

### Phase 3.5: Concept Clarification (Quality Gate)

**Command**: `SlashCommand(command="/workflow:concept-clarify --session [sessionId]")`

**Purpose**: Quality gate to verify and clarify analysis results before task generation

**Input**: `sessionId` from Phase 1

**Behavior**:
- Auto-detects plan mode (ANALYSIS_RESULTS.md exists)
- Interactively asks up to 5 targeted questions to resolve ambiguities
- Updates ANALYSIS_RESULTS.md with clarifications
- Pauses workflow for user input (breaks auto-continue temporarily)

**Parse Output**:
- Verify clarifications added to ANALYSIS_RESULTS.md
- Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING"

**Validation**:
- ANALYSIS_RESULTS.md updated with `## Clarifications` section
- All critical ambiguities resolved or documented as outstanding

**TodoWrite**: Mark phase 3.5 completed, phase 4 in_progress

**After Phase 3.5**: Return to user showing clarification summary, then auto-continue to Phase 4

**Skip Conditions**:
- If `/workflow:concept-clarify` reports "No critical ambiguities detected", automatically proceed to Phase 4
- User can skip by responding "skip" or "proceed" immediately

---

### Phase 4: Task Generation

**Relationship with Brainstorm Phase**:
- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input
- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features
- **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
- Task generation translates high-level specifications into concrete, actionable work items

**Command Selection**:
- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
- CLI Execute: Add `--cli-execute` flag to either command

**Flag Combination**:
- `--cli-execute` alone: Manual task generation with CLI execution
- `--agent --cli-execute`: Agent task generation with CLI execution

**Command Examples**:
```bash
# Manual with CLI execution
/workflow:tools:task-generate --session WFS-auth --cli-execute

# Agent with CLI execution
/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
```

**Input**: `sessionId` from Phase 1

**Validation**:
- `.workflow/[sessionId]/IMPL_PLAN.md` exists
- `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
- `.workflow/[sessionId]/TODO_LIST.md` exists

**TodoWrite**: Mark phase 4 completed

**Return to User**:
```
Planning complete for session: [sessionId]
Tasks generated: [count]
Plan: .workflow/[sessionId]/IMPL_PLAN.md

✅ Recommended Next Steps:
1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
2. /workflow:status  # Review task breakdown
3. /workflow:execute  # Start implementation (after verification)

⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
```

## TodoWrite Pattern

```javascript
// Initialize (before Phase 1)
TodoWrite({todos: [
  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})

// After Phase 1
TodoWrite({todos: [
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})

// Continue pattern for Phase 2, 3, 3.5, 4...
```

## Input Processing

**Convert User Input to Structured Format**:

1. **Simple Text** → Structure it:
   ```
   User: "Build authentication system"

   Structured:
   GOAL: Build authentication system
   SCOPE: Core authentication features
   CONTEXT: New implementation
   ```

2. **Detailed Text** → Extract components:
   ```
   User: "Add JWT authentication with email/password login and token refresh"

   Structured:
   GOAL: Implement JWT-based authentication
   SCOPE: Email/password login, token generation, token refresh endpoints
   CONTEXT: JWT token-based security, refresh token rotation
   ```

3. **File Reference** (e.g., `requirements.md`) → Read and structure:
   - Read file content
   - Extract goal, scope, requirements
   - Format into structured description

## Data Flow

```
User Input (task description)
    ↓
[Convert to Structured Format]
    ↓ Structured Description:
    ↓   GOAL: [objective]
    ↓   SCOPE: [boundaries]
    ↓   CONTEXT: [background]
    ↓
Phase 1: session:start --auto "structured-description"
    ↓ Output: sessionId
    ↓ Session Memory: Previous tasks, context, artifacts
    ↓
Phase 2: context-gather --session sessionId "structured-description"
    ↓ Input: sessionId + session memory + structured description
    ↓ Output: contextPath (context-package.json)
    ↓
Phase 3: cli-execution-agent (Intelligent Analysis)
    ↓ Input: sessionId + contextPath + task description
    ↓ Agent discovers context, enhances prompt, executes with Gemini
    ↓ Output: ANALYSIS_RESULTS.md + execution log
    ↓
Phase 3.5: concept-clarify --session sessionId (Quality Gate)
    ↓ Input: sessionId + ANALYSIS_RESULTS.md (auto-detected)
    ↓ Interactive: User answers clarification questions
    ↓ Output: Updated ANALYSIS_RESULTS.md with clarifications
    ↓
Phase 4: task-generate[--agent] --session sessionId
    ↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory
    ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
    ↓
Return summary to user
```

**Session Memory Flow**: Each phase receives session ID, which provides access to:
- Previous task summaries
- Existing context and analysis
- Brainstorming artifacts
- Session-specific configuration

**Structured Description Benefits**:
- **Clarity**: Clear separation of goal, scope, and context
- **Consistency**: Same format across all phases
- **Traceability**: Easy to track what was requested
- **Precision**: Better context gathering and analysis

## Error Handling

- **Parsing Failure**: If output parsing fails, retry command once, then report error
- **Validation Failure**: If validation fails, report which file/data is missing
- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase

## Coordinator Checklist

✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
✅ Initialize TodoWrite before any command (include Phase 3.5)
✅ Execute Phase 1 immediately with structured description
✅ Parse session ID from Phase 1 output, store in memory
✅ Pass session ID and structured description to Phase 2 command
✅ Parse context path from Phase 2 output, store in memory
✅ **Launch Phase 3 agent**: Build Task prompt with sessionId and contextPath
✅ Wait for agent completion, parse execution log path
✅ Verify ANALYSIS_RESULTS.md created by agent
✅ **Execute Phase 3.5**: Pass session ID to `/workflow:concept-clarify`
✅ Wait for user interaction (clarification Q&A)
✅ Verify ANALYSIS_RESULTS.md updated with clarifications
✅ Check recommendation: proceed if "PROCEED", otherwise alert user
✅ **Build Phase 4 command** based on flags:
  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
  - Add `--session [sessionId]`
  - Add `--cli-execute` if flag present
✅ Pass session ID to Phase 4 command
✅ Verify all Phase 4 outputs
✅ Update TodoWrite after each phase
✅ After each phase, automatically continue to next phase based on TodoList status

## Structure Template Reference

**Minimal Structure**:
```
GOAL: [What to achieve]
SCOPE: [What's included]
CONTEXT: [Relevant info]
```

**Detailed Structure** (optional, when more context available):
```
GOAL: [Primary objective]
SCOPE: [Included features/components]
CONTEXT: [Existing system, constraints, dependencies]
REQUIREMENTS: [Specific technical requirements]
CONSTRAINTS: [Limitations or boundaries]
```

**Usage in Commands**:
```bash
# Phase 1
/workflow:session:start --auto "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"

# Phase 2
/workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
```