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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
plan	Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases	[--agent] [--cli-execute] "text description"|file.md	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]/.process/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

Command: SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")

Input: sessionId from Phase 1, contextPath from Phase 2

Parse Output:

• Extract: Execution status (success/failed)
• Verify: ANALYSIS_RESULTS.md file path

Validation:

• File .workflow/[sessionId]/.process/ANALYSIS_RESULTS.md exists

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
• ⚠️ User's original intent is ALWAYS primary: New or refined user goals override synthesis recommendations
• 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
• Intent priority: Current user prompt > synthesis-specification.md > topic-framework.md

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:

# 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

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

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