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 ──→ Display session status inline

Key Design Principles

• Pure Orchestrator: SKILL.md routes and coordinates only; execution detail lives in phase files

• Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute

• Multi-Mode Routing: Single skill handles plan/verify/replan via mode detection

• Task Attachment Model: Sub-command tasks are ATTACHED, executed sequentially, then COLLAPSED

• Auto-Continue: After each phase completes, automatically execute next pending phase

• Accumulated State: planning-notes.md carries context across phases for N+1 decisions

Interactive Preference Collection

Before dispatching to phase execution, collect workflow preferences via AskUserQuestion:

// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播 const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) { // 自动模式：跳过所有询问，使用默认值 workflowPreferences = { autoYes: true, interactive: false } } else { const prefResponse = AskUserQuestion({ questions: [ { question: "是否跳过所有确认步骤（自动模式）？", header: "Auto Mode", multiSelect: false, options: [ { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" }, { label: "Auto", description: "跳过所有确认，自动执行" } ] } ] })

workflowPreferences = { autoYes: prefResponse.autoMode === 'Auto' }

// For replan mode, also collect interactive preference if (mode === 'replan') { const replanPref = AskUserQuestion({ questions: [ { question: "是否使用交互式澄清模式？", header: "Replan Mode", multiSelect: false, options: [ { label: "Standard (Recommended)", description: "使用安全默认值" }, { label: "Interactive", description: "通过提问交互式澄清修改范围" } ] } ] }) workflowPreferences.interactive = replanPref.replanMode === 'Interactive' } }

workflowPreferences is passed to phase execution as context variable, referenced as workflowPreferences.autoYes , workflowPreferences.interactive within phases.

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 }

Compact Recovery (Phase Persistence)

Multi-phase planning (Phase 1-4/5/6) spans long conversations. Uses 双重保险: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底。

⚠️ COMPACT DIRECTIVE: Context compression MUST check TodoWrite phase status. The phase currently marked in_progress is the active execution phase — preserve its FULL content. Only compress phases marked completed or pending .

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" → Display session status inline

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 Compact

1 phases/01-session-discovery.md Create or discover workflow session plan TodoWrite 驱动

2 phases/02-context-gathering.md Gather project context and analyze codebase plan TodoWrite 驱动

3 phases/03-conflict-resolution.md Detect and resolve conflicts (conditional) plan TodoWrite 驱动

4 phases/04-task-generation.md Generate implementation plan and task JSONs plan TodoWrite 驱动 + 🔄 sentinel

5 phases/05-plan-verify.md Read-only verification with quality gate verify TodoWrite 驱动

6 phases/06-replan.md Interactive replanning with boundary clarification replan TodoWrite 驱动

Compact Rules:

• TodoWrite in_progress → 保留完整内容，禁止压缩

• TodoWrite completed → 可压缩为摘要

• 🔄 sentinel fallback → Phase 4 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，必须立即 Read("phases/04-task-generation.md") 恢复

Core Rules

• Start Immediately: First action is mode detection + TodoWrite initialization, second action is phase execution

• No Preliminary Analysis: Do not read files, analyze structure, or gather context before Phase 1

• Parse Every Output: Extract required data from each phase output for next phase

• Auto-Continue via TodoList: Check TodoList status to execute next pending phase automatically

• Track Progress: Update TodoWrite dynamically with task attachment/collapse pattern

• Task Attachment Model: Skill execute attaches sub-tasks to current workflow. Orchestrator executes these attached tasks itself, then collapses them after completion

• Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute

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

Simple Text → Structure it:

User: "Build authentication system"

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

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

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" → Display session status inline

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

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

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

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: Display session status inline

• Auto mode (workflowPreferences.autoYes): 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 (auto-detect from active sessions)

• Initialize TodoWrite with single verification task

• Execute Phase 5 verification agent

• Present quality gate result and next step options

Replan Mode

• Parse task ID from $ARGUMENTS (IMPL-N format, if present)

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

• brainstorm skill - Optional: Generate role-based analyses before planning

• brainstorm skill - Optional: Refine brainstorm analyses with clarifications

Called by Plan Mode (4 phases):

• /workflow:session:start

• Phase 1: Create or discover workflow session

• phases/02-context-gathering.md

• Phase 2: Gather project context and analyze codebase (inline)

• phases/03-conflict-resolution.md

• Phase 3: Detect and resolve conflicts (inline, conditional)

• memory-capture skill - Phase 3: Memory optimization (if context approaching limits)

• phases/04-task-generation.md

• Phase 4: Generate task JSON files (inline)

Follow-up Skills:

• workflow-plan skill (plan-verify phase) - Verify plan quality (can also invoke via verify mode)

• Display session status inline - Review task breakdown and current progress

• Skill(skill="workflow-execute")

• Begin implementation of generated tasks (skill: workflow-execute)

• workflow-plan skill (replan phase) - Modify plan (can also invoke via replan mode)