Claude-Code-Workflow/.claude/skills/workflow-plan/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
workflow-plan	Unified planning skill - 4-phase planning workflow, plan verification, and interactive replanning. Triggers on "workflow:plan", "workflow:plan-verify", "workflow:replan".	Skill, Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep

Workflow Plan

Unified planning skill combining 4-phase planning workflow, plan quality verification, and interactive replanning. Produces IMPL_PLAN.md, task JSONs, verification reports, and manages plan lifecycle through session-level artifact updates.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│  Workflow Plan Orchestrator (SKILL.md)                            │
│  → Route by mode: plan | verify | replan                         │
│  → Pure coordinator: Execute phases, parse outputs, pass context │
└──────────────────────────────┬───────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ↓                       ↓                       ↓
  ┌───────────┐          ┌───────────┐           ┌───────────┐
  │ Plan Mode │          │  Verify   │           │  Replan   │
  │ (default) │          │   Mode    │           │   Mode    │
  │ Phase 1-4 │          │  Phase 5  │           │  Phase 6  │
  └─────┬─────┘          └───────────┘           └───────────┘
        │
    ┌───┼───┬───┐
    ↓   ↓   ↓   ↓
  ┌───┐┌───┐┌───┐┌───┐
  │ 1 ││ 2 ││ 3 ││ 4 │
  │Ses││Ctx││Con││Gen│
  └───┘└───┘└───┘└─┬─┘
                    ↓
              ┌───────────┐
              │ Confirm   │─── Verify ──→ Phase 5
              │ (choice)  │─── Execute ─→ Skill("workflow-execute")
              └───────────┘─── Review ──→ /workflow:status

Key Design Principles

1. Pure Orchestrator: SKILL.md routes and coordinates only; execution detail lives in phase files
2. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
3. Multi-Mode Routing: Single skill handles plan/verify/replan via mode detection
4. Task Attachment Model: Sub-command tasks are ATTACHED, executed sequentially, then COLLAPSED
5. Auto-Continue: After each phase completes, automatically execute next pending phase
6. Accumulated State: planning-notes.md carries context across phases for N+1 decisions

Auto Mode

When --yes or -y: Auto-continue all phases (skip confirmations), use recommended conflict resolutions, use safe defaults for replan.

Mode Detection

const args = $ARGUMENTS
const mode = detectMode(args)

function detectMode(args) {
  // Skill trigger determines mode
  if (skillName === 'workflow:plan-verify') return 'verify'
  if (skillName === 'workflow:replan') return 'replan'
  return 'plan'  // default: workflow:plan
}

Execution Flow

Plan Mode (default)

Input Parsing:
   └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT)

Phase 1: Session Discovery
   └─ Ref: phases/01-session-discovery.md
      └─ Output: sessionId (WFS-xxx), planning-notes.md

Phase 2: Context Gathering
   └─ Ref: phases/02-context-gathering.md
      ├─ Tasks attached: Analyze structure → Identify integration → Generate package
      └─ Output: contextPath + conflictRisk

Phase 3: Conflict Resolution (conditional: conflictRisk ≥ medium)
   └─ Decision (conflictRisk check):
      ├─ conflictRisk ≥ medium → Ref: phases/03-conflict-resolution.md
      │   ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies
      │   └─ Output: Modified brainstorm artifacts
      └─ conflictRisk < medium → Skip to Phase 4

Phase 4: Task Generation
   └─ Ref: phases/04-task-generation.md
      └─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md

Plan Confirmation (User Decision Gate):
   └─ Decision (user choice):
      ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5 (plan-verify)
      ├─ "Start Execution" → Skill(skill="workflow-execute")
      └─ "Review Status Only" → Route to /workflow:status

Verify Mode

Phase 5: Plan Verification
   └─ Ref: phases/05-plan-verify.md
      └─ Output: PLAN_VERIFICATION.md with quality gate recommendation

Replan Mode

Phase 6: Interactive Replan
   └─ Ref: phases/06-replan.md
      └─ Output: Updated IMPL_PLAN.md, task JSONs, TODO_LIST.md

Phase Reference Documents (read on-demand when phase executes):

Phase	Document	Purpose	Mode
1	phases/01-session-discovery.md	Create or discover workflow session	plan
2	phases/02-context-gathering.md	Gather project context and analyze codebase	plan
3	phases/03-conflict-resolution.md	Detect and resolve conflicts (conditional)	plan
4	phases/04-task-generation.md	Generate implementation plan and task JSONs	plan
5	phases/05-plan-verify.md	Read-only verification with quality gate	verify
6	phases/06-replan.md	Interactive replanning with boundary clarification	replan

Core Rules

1. Start Immediately: First action is mode detection + TodoWrite initialization, second action is phase 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 phase output for next phase
4. Auto-Continue via TodoList: Check TodoList status to execute next pending phase automatically
5. Track Progress: Update TodoWrite dynamically with task attachment/collapse pattern
6. Task Attachment Model: Skill execute attaches sub-tasks to current workflow. Orchestrator executes these attached tasks itself, then collapses them after completion
7. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
8. DO NOT STOP: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase

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

Plan Mode

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
    ↓ Write: planning-notes.md (User Intent section)
    ↓
Phase 2: context-gather --session sessionId "structured-description"
    ↓ Input: sessionId + structured description
    ↓ Output: contextPath (context-package.json) + conflictRisk
    ↓ Update: planning-notes.md (Context Findings + Consolidated Constraints)
    ↓
Phase 3: conflict-resolution [conditional: conflictRisk ≥ medium]
    ↓ Input: sessionId + contextPath + conflictRisk
    ↓ Output: Modified brainstorm artifacts
    ↓ Update: planning-notes.md (Conflict Decisions + Consolidated Constraints)
    ↓ Skip if conflictRisk is none/low → proceed directly to Phase 4
    ↓
Phase 4: task-generate-agent --session sessionId
    ↓ Input: sessionId + planning-notes.md + context-package.json + brainstorm artifacts
    ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
    ↓
Plan Confirmation (User Decision Gate):
    ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5
    ├─ "Start Execution" → Skill(skill="workflow-execute")
    └─ "Review Status Only" → Route to /workflow:status

Session Memory Flow: Each phase receives session ID, which provides access to:

• Previous task summaries
• Existing context and analysis
• Brainstorming artifacts (potentially modified by Phase 3)
• Session-specific configuration

Verify Mode

Input: --session sessionId (or auto-detect)
    ↓
Phase 5: Load artifacts → Agent-driven verification → Generate report
    ↓ Output: PLAN_VERIFICATION.md with quality gate

Replan Mode

Input: [--session sessionId] [task-id] "requirements"
    ↓
Phase 6: Mode detection → Clarification → Impact analysis → Backup → Apply → Verify
    ↓ Output: Updated artifacts + change summary

TodoWrite Pattern

Core Concept: Dynamic task attachment and collapse for real-time visibility into workflow execution.

Key Principles

1. Task Attachment (when phase executed):

   • Sub-tasks are attached to orchestrator's TodoWrite
   • Phase 2, 3: Multiple sub-tasks attached
   • Phase 1, 4: Single task (atomic)
   • First attached task marked as in_progress, others as pending
   • Orchestrator executes these attached tasks sequentially

2. Task Collapse (after sub-tasks complete):

   • Applies to Phase 2, 3: Remove detailed sub-tasks from TodoWrite
   • Collapse to high-level phase summary
   • Phase 1, 4: No collapse needed (single task, just mark completed)
   • Maintains clean orchestrator-level view

3. Continuous Execution: After completion, automatically proceed to next pending phase

Lifecycle: Initial pending → Phase executed (tasks ATTACHED) → Sub-tasks executed → Phase completed (tasks COLLAPSED for 2/3, marked completed for 1/4) → Next phase → Repeat

Phase 2 (Tasks Attached):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "in_progress"},
  {"content": "  → Analyze codebase structure", "status": "in_progress"},
  {"content": "  → Identify integration points", "status": "pending"},
  {"content": "  → Generate context package", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

Phase 2 (Collapsed):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

Phase 3 (Tasks Attached, conditional):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Conflict Resolution", "status": "in_progress"},
  {"content": "  → Detect conflicts with CLI analysis", "status": "in_progress"},
  {"content": "  → Present conflicts to user", "status": "pending"},
  {"content": "  → Apply resolution strategies", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

Note: See individual Phase descriptions for detailed TodoWrite Update examples.

Post-Phase Updates

After each phase completes, update planning-notes.md:

• After Phase 1: Initialize with user intent (GOAL, KEY_CONSTRAINTS)
• After Phase 2: Add context findings (CRITICAL_FILES, ARCHITECTURE, CONFLICT_RISK, CONSTRAINTS)
• After Phase 3: Add conflict decisions (RESOLVED, MODIFIED_ARTIFACTS, CONSTRAINTS) if executed
• Memory State Check: After heavy phases (Phase 2-3), evaluate context window usage; if high (>120K tokens), trigger compact

See phase files for detailed update code.

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
• Session Not Found (verify/replan): Report error with available sessions list
• Task Not Found (replan): Report error with available tasks list

Coordinator Checklist

Plan Mode

• Pre-Phase: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
• Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
• 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
• Extract conflictRisk from context-package.json: Determine Phase 3 execution
• If conflictRisk ≥ medium: Launch Phase 3 conflict-resolution with sessionId and contextPath
• Wait for Phase 3 to finish executing (if executed), verify conflict-resolution.json created
• If conflictRisk is none/low: Skip Phase 3, proceed directly to Phase 4
• Pass session ID to Phase 4 command
• Verify all Phase 4 outputs
• Plan Confirmation Gate: Present user with choice (Verify → Phase 5 / Execute / Review Status)
• If user selects Verify: Read phases/05-plan-verify.md, execute Phase 5 in-process
• If user selects Execute: Skill(skill="workflow-execute")
• If user selects Review: Route to /workflow:status
• Auto mode (--yes): Auto-select "Verify Plan Quality", then auto-continue to execute if PROCEED
• Update TodoWrite after each phase
• After each phase, automatically continue to next phase based on TodoList status

Verify Mode

• Detect/validate session (from --session flag or auto-detect)
• Initialize TodoWrite with single verification task
• Execute Phase 5 verification agent
• Present quality gate result and next step options

Replan Mode

• Parse flags (--session, --interactive, task-id)
• Detect operation mode (task vs session)
• Initialize TodoWrite with replan-specific tasks
• Execute Phase 6 through all sub-phases (clarification → impact → backup → apply → verify)

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]

Related Skills

Prerequisite Skills:

• /workflow:brainstorm:artifacts - Optional: Generate role-based analyses before planning
• /workflow:brainstorm:synthesis - Optional: Refine brainstorm analyses with clarifications

Called by Plan Mode (4 phases):

• /workflow:session:start - Phase 1: Create or discover workflow session
• /workflow:tools:context-gather - Phase 2: Gather project context and analyze codebase
• /workflow:tools:conflict-resolution - Phase 3: Detect and resolve conflicts (conditional)
• /compact - Phase 3: Memory optimization (if context approaching limits)
• /workflow:tools:task-generate-agent - Phase 4: Generate task JSON files

Follow-up Skills:

• /workflow:plan-verify - Verify plan quality (can also invoke via verify mode)
• /workflow:status - Review task breakdown and current progress
• Skill(skill="workflow-execute") - Begin implementation of generated tasks (skill: workflow-execute)
• /workflow:replan - Modify plan (can also invoke via replan mode)