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

name: plan description: Create implementation plans by orchestrating intelligent context gathering and analysis modules usage: /workflow:plan 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 (/workflow:plan)

Overview

Creates implementation plans by orchestrating intelligent context gathering and analysis modules.

Core Principles

Task Decomposition Standards

Core Principle: Task Merging Over Decomposition

• Merge Rule: Tasks that can be executed together should not be separated - avoid unnecessary decomposition
• Decomposition Criteria: Only decompose tasks in the following situations:
  • Excessive Workload: Code exceeds 2500 lines or modifies more than 6 files
  • Context Separation: Involves completely different tech stacks or business domains
  • Dependency Blocking: Subsequent tasks must wait for prerequisite task completion
  • Parallel Execution: Independent features that can be developed simultaneously by different developers

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)

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

Task JSON Creation Process

Task JSON Generation Philosophy:

1. Analysis-Driven: Task definitions generated from intelligent analysis results
2. Context-Rich: Each task includes comprehensive context for autonomous execution
3. Flow-Control Ready: Pre-analysis steps and implementation approach pre-defined
4. Agent-Optimized: Complete context provided for specialized agent execution
5. Artifacts-Integrated: Automatically detect and reference brainstorming artifacts
6. Design-Context-Aware: Ensure design documents are loaded in pre_analysis steps

Automatic Task Generation Workflow:

1. Parse Analysis Results: Extract task recommendations from ANALYSIS_RESULTS.md
2. Extract Task Details: Parse task ID, title, scope, complexity from structured analysis
3. Detect Brainstorming Artifacts: Scan for ui-designer, system-architect, and other role outputs
4. Generate Context: Create requirements, focus_paths, acceptance criteria, and artifacts references
5. Build Enhanced Flow Control: Define pre_analysis steps with artifact loading and implementation approach
6. Create Artifact-Aware JSON Files: Generate individual .task/IMPL-*.json files with enhanced schema

Session Management ⚠️ CRITICAL

• Command: Uses /workflow:session:start command for intelligent session discovery and creation
• ⚡ FIRST ACTION: Check for all .workflow/.active-* markers before any planning
• Relevance Analysis: Automatically analyzes task relevance with existing sessions
• Auto-session creation: WFS-[topic-slug] only if no active session exists or task is unrelated
• 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

Session ID Transmission Guidelines ⚠️ CRITICAL

• Format: WFS-[topic-slug] from active session markers
• Usage: /workflow:tools:context-gather --session WFS-[id] and /workflow:tools:plan-enchanced --session WFS-[id]
• Rule: ALL modular commands MUST receive current session ID for context continuity

Brainstorming Artifacts Integration ⚠️ NEW FEATURE

• Artifact Detection: Automatically scan .brainstorming/ directory for role outputs
• Role-Task Mapping: Map brainstorming roles to task types (ui-designer → UI tasks)
• Artifact References: Create structured references to design documents and specifications
• Context Enhancement: Load artifacts in pre_analysis steps to provide complete design context

Execution Lifecycle

Phase 1: Session Management

1. Session Discovery: Use /workflow:session:start command for intelligent session discovery
2. Relevance Analysis: Automatically analyze task relevance with existing sessions
3. Session Selection: Auto-select or create session based on relevance analysis
4. Context Preparation: Load session state and prepare for planning

Phase 2: Context Gathering

1. Context Collection: Execute /workflow:tools:context-gather with task description and session ID
2. Asset Discovery: Gather relevant documentation, code, and configuration files
3. Context Packaging: Generate standardized context-package.json
4. Validation: Ensure context package contains sufficient information

Phase 3: Intelligent Analysis

1. Analysis Execution: Run /workflow:tools:plan-enchanced with context package and session ID
2. Tool Selection: Automatically select optimal analysis tools (Gemini/Qwen/Codex)
3. Result Generation: Produce structured ANALYSIS_RESULTS.md
4. Validation: Verify analysis completeness and task recommendations

Phase 4: Plan Assembly & Document Generation

1. Artifact Detection: Scan session for brainstorming outputs (.brainstorming/ directory)
2. Plan Generation: Create IMPL_PLAN.md from analysis results and artifacts
3. Enhanced Task JSON Creation: Generate task JSON files with artifacts integration
4. TODO List Creation: Generate TODO_LIST.md with artifact references
5. Session Update: Mark session as ready for execution with artifact context

TodoWrite Progress Tracking

Comprehensive planning tracking with real-time status updates throughout entire planning lifecycle:

TodoWrite Planning Rules

1. Initial Creation: Generate TodoWrite from planning phases
2. Single In-Progress: Mark ONLY ONE phase as in_progress at a time
3. Immediate Updates: Update status after each phase completion
4. Continuous Tracking: Maintain TodoWrite throughout entire planning workflow

TodoWrite Tool Usage

Core Rule: Monitor slash command completion before proceeding to next step

// Initialize planning workflow tracking
TodoWrite({
  todos: [
    {"content": "Initialize session management", "status": "pending", "activeForm": "Initializing session management"},
    {"content": "Detect and analyze brainstorming artifacts", "status": "pending", "activeForm": "Detecting and analyzing brainstorming artifacts"},
    {"content": "Gather intelligent context", "status": "pending", "activeForm": "Gathering intelligent context"},
    {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
    {"content": "Generate artifact-enhanced implementation plan and tasks", "status": "pending", "activeForm": "Generating artifact-enhanced implementation plan and tasks"}
  ]
})

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

Enhanced Task JSON Schema (5-Field + Artifacts)

Each task.json uses the workflow-architecture.md 5-field schema enhanced with artifacts:

• 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, artifacts }
• flow_control: { pre_analysis[] (with artifact loading), implementation_approach, target_files[] }

Streamlined Artifacts Field with Single Synthesis Document:

"artifacts": [
  {
    "type": "synthesis_specification",
    "source": "brainstorm_synthesis",
    "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
    "priority": "highest",
    "contains": "complete_integrated_specification"
  },
  {
    "type": "topic_framework",
    "source": "brainstorm_framework",
    "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md",
    "priority": "medium",
    "contains": "discussion_framework_structure"
  },
  {
    "type": "individual_role_analysis",
    "source": "brainstorm_roles",
    "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
    "priority": "low",
    "contains": "role_specific_analysis_fallback"
  }
]

MCP Tools Integration: Enhanced with optional MCP servers for advanced analysis:

• Code Index MCP: mcp__code-index__find_files(), mcp__code-index__search_code_advanced()
• Exa MCP: mcp__exa__get_code_context_exa() for external patterns

Context Management & Agent Execution

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

// Example pre_analysis steps generated by /workflow:plan for agent execution
"flow_control": {
  "pre_analysis": [
    {
      "step": "load_synthesis_specification",
      "action": "Load consolidated synthesis specification from brainstorming",
      "commands": [
        "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'synthesis specification not found')",
        "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
      ],
      "output_to": "synthesis_specification",
      "on_error": "skip_optional"
    },
    {
      "step": "load_individual_role_artifacts",
      "action": "Load individual role analyses as fallback",
      "commands": [
        "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis.md' 2>/dev/null | head -8)",
        "Read(.workflow/WFS-[session]/.brainstorming/ui-designer/analysis.md)",
        "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)",
        "Read(.workflow/WFS-[session]/.brainstorming/topic-framework.md)"
      ],
      "output_to": "individual_artifacts",
      "on_error": "skip_optional"
    },
    {
      "step": "load_planning_context",
      "action": "Load plan-generated analysis and context",
      "commands": [
        "Read(.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md)",
        "Read(.workflow/WFS-[session]/.process/context-package.json)"
      ],
      "output_to": "planning_context"
    },
    {
      "step": "load_context_assets",
      "action": "Load structured assets from context package",
      "command": "Read(.workflow/WFS-[session]/.process/context-package.json)",
      "output_to": "context_assets"
    },
    {
      "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_base_documentation",
      "action": "Load core documentation files",
      "commands": [
        "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'base docs not found')",
        "bash(cat CLAUDE.md README.md 2>/dev/null || echo 'project docs not found')"
      ],
      "output_to": "base_docs"
    },
    {
      "step": "load_task_specific_docs",
      "action": "Load documentation relevant to task type",
      "commands": [
        "bash(cat .workflow/docs/architecture/*.md 2>/dev/null || echo 'architecture docs not found')",
        "bash(cat .workflow/docs/api/*.md 2>/dev/null || echo 'api docs not found')"
      ],
      "output_to": "task_docs"
    },
    {
      "step": "analyze_task_patterns",
      "action": "Analyze existing code patterns for task context",
      "commands": [
        "bash(cd \"[task_focus_paths]\")",
        "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze task patterns TASK: Review '[task_title]' patterns CONTEXT: Task [task_id] in [task_focus_paths], synthesis spec: [synthesis_specification], fallback artifacts: [individual_artifacts] EXPECTED: Pattern analysis integrating consolidated design specification RULES: Prioritize synthesis-specification.md over individual artifacts, align with consolidated requirements and design\")"
      ],
      "output_to": "task_context",
      "on_error": "fail"
    }
  ],
  "implementation_approach": {
    "task_description": "Implement '[task_title]' following consolidated synthesis specification from [synthesis_specification] with fallback to [individual_artifacts]",
    "modification_points": [
      "Apply consolidated requirements and design patterns from synthesis-specification.md",
      "Follow technical guidelines and implementation roadmap from synthesis specification",
      "Integrate with existing patterns while maintaining design integrity from consolidated specification"
    ],
    "logic_flow": [
      "Load consolidated synthesis specification as primary context",
      "Extract specific requirements, design patterns, and technical guidelines",
      "Analyze existing code patterns for integration with synthesized design",
      "Implement feature following consolidated specification",
      "Validate implementation against synthesized acceptance criteria"
    ]
  }
}

Artifact Detection & Integration ⚠️ ENHANCED FEATURE

Artifact Detection Logic

Automatic Brainstorming Artifact Scanning:

1. Session Scan: Check .workflow/WFS-[session]/.brainstorming/ directory
2. Role Detection: Identify completed role analyses (ui-designer, system-architect, etc.)
3. Artifact Mapping: Map artifacts to relevant task types
4. Relevance Scoring: Assign relevance scores based on task-artifact alignment

Role-Task Mapping Rules

Artifact-Task Relevance Matrix:

• ui-designer → UI/Frontend/Component tasks (high relevance)
• system-architect → Architecture/Backend/Database tasks (high relevance)
• security-expert → Authentication/Security/Validation tasks (high relevance)
• data-architect → Data/API/Analytics tasks (high relevance)
• product-manager → Feature/Business Logic tasks (medium relevance)
• topic-framework.md → All tasks (low-medium relevance for context)

Enhanced Task Generation

Artifact-Enhanced Task Creation Process:

1. Standard Task Generation: Create base task from analysis results
2. Artifact Detection: Scan for relevant brainstorming outputs
3. Context Enrichment: Add artifacts array to task.context
4. Pre-Analysis Enhancement: Insert artifact loading steps
5. Implementation Update: Reference artifacts in task description and approach

Artifact Loading in Pre-Analysis

Automatic Artifact Integration:

{
  "step": "load_brainstorming_artifacts",
  "action": "Load brainstorming artifacts and design documents",
  "commands": [
    "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis.md' 2>/dev/null | while read file; do echo \"=== $(dirname \"$file\" | xargs basename) ===\"; cat \"$file\"; echo; done)",
    "Read(.workflow/WFS-[session]/.brainstorming/topic-framework.md)"
  ],
  "output_to": "brainstorming_artifacts",
  "on_error": "skip_optional"
}

File Structure Reference

Architecture: @~/.claude/workflows/workflow-architecture.md

Execution Integration

Documents created for /workflow:execute:

• IMPL_PLAN.md: Context loading and requirements with artifact references
• .task/*.json: Agent implementation context with enhanced artifact loading
• TODO_LIST.md: Status tracking (container tasks with ▸, leaf tasks with checkboxes)