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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
ccw-plan	Planning coordinator - analyze requirements, select planning strategy, execute planning workflow in main process	[--mode lite|multi-cli|full|plan-verify|replan|cli|issue|rapid-to-issue|brainstorm-with-file|analyze-with-file] [--yes|-y] "task description"	Skill(*), TodoWrite(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*)

CCW-Plan Command - Planning Coordinator

Planning orchestrator: requirement analysis → strategy selection → planning execution.

Core Concept: Planning Units (规划单元)

Definition: Planning commands are grouped into logical units based on verification requirements and collaboration strategies.

Planning Units:

Unit Type	Pattern	Example
Quick Planning	plan-cmd (no verify)	lite-plan
Verified Planning	plan-cmd → verify-cmd	plan → plan-verify
Collaborative Planning	multi-cli-plan (implicit verify)	multi-cli-plan
With-File Planning	brainstorm-with-file or analyze-with-file	brainstorm + plan options
CLI-Assisted Planning	ccw cli (analysis) → recommendations	quick analysis + decision
Issue Workflow Planning	plan → issue workflow (discover/queue/execute)	rapid-to-issue bridge

Atomic Rules:

1. Lite mode: No verification (fast iteration)
2. Plan-verify mode: Mandatory quality gate
3. Multi-cli/Full mode: Optional verification (via --skip-verify flag)
4. With-File modes: Self-contained iteration with built-in post-completion options
5. CLI mode: Quick analysis, user-driven decisions
6. Issue modes: Planning integrated into issue workflow lifecycle

Execution Model

Synchronous (Main Process): Planning commands execute via Skill, blocking until complete.

User Input → Analyze Requirements → Select Strategy → [Confirm] → Execute Planning
                                                                    ↓
                                                          Skill (blocking)
                                                                    ↓
                                                          Update TodoWrite
                                                                    ↓
                                                          Generate Artifacts

5-Phase Workflow

Phase 1: Analyze Requirements

Input → Extract (goal, scope, constraints) → Assess (complexity, clarity, criticality) → Analysis

Field	Values
complexity	low | medium | high
clarity	0-3 (≥2 = clear)
criticality	normal | high | critical
scope	single-module | cross-module | system | batch-issues

Output: Type: [task_type] | Goal: [goal] | Complexity: [complexity] | Clarity: [clarity]/3 | Criticality: [criticality]

---

Phase 1.5: Requirement Clarification (if clarity < 2)

Analysis → Check clarity ≥ 2?
           ↓
       YES → Continue to Phase 2
           ↓
        NO → Ask Questions → Update Analysis

Questions Asked: Goal (Create/Fix/Optimize/Analyze), Scope (Single file/Module/Cross-module/System), Constraints (Backward compat/Skip tests/Urgent hotfix)

---

Phase 2: Select Planning Strategy & Build Command Chain

Analysis → Detect Mode (keywords) → Build Command Chain → Planning Workflow

Mode Detection (Priority Order)

Input Keywords                                              → Mode
───────────────────────────────────────────────────────────────────────────────
quick|fast|immediate|recommendation|suggest                → cli
issues?|batch|issue workflow|structured workflow|queue     → issue
issue transition|rapid.*issue|plan.*issue|convert.*issue   → rapid-to-issue
brainstorm|ideation|头脑风暴|创意|发散思维|multi-perspective  → brainstorm-with-file
analyze.*document|explore.*concept|collaborative analysis  → analyze-with-file
production|critical|payment|auth                           → plan-verify
adjust|modify|change plan                                  → replan
uncertain|explore                                          → full
complex|multiple module|integrate                          → multi-cli
(default)                                                  → lite

Command Chain Mapping

Mode	Command Chain	Verification	Use Case
cli	ccw cli --mode analysis --rule planning-*	None	Quick planning recommendation
issue	/issue:discover → /issue:plan → /issue:queue → /issue:execute	Optional	Batch issue planning & execution
rapid-to-issue	lite-plan → /issue:convert-to-plan → queue → execute	Optional	Quick planning → Issue workflow bridge
brainstorm-with-file	/workflow:brainstorm-with-file → (plan/issue options)	Self-contained	Multi-perspective ideation
analyze-with-file	/workflow:analyze-with-file → (plan/issue options)	Self-contained	Collaborative architecture analysis
lite	lite-plan	None	Fast simple planning
multi-cli	multi-cli-plan → [plan-verify]	Optional	Multi-model collaborative planning
full	brainstorm → plan → [plan-verify]	Optional	Comprehensive brainstorm + planning
plan-verify	plan → plan-verify	Mandatory	Production/critical features
replan	replan	None	Plan refinement/adjustment

Note:

• [ ] = optional verification
• bold = mandatory quality gate
• With-File modes include built-in post-completion options to create plans/issues

Output: Mode: [mode] | Strategy: [strategy] | Commands: [1. /cmd1 2. /cmd2]

---

Phase 3: User Confirmation

Planning Chain → Show Strategy → Ask User → User Decision:
- ✓ Confirm → Continue to Phase 4
- ⚙ Adjust → Change Mode (back to Phase 2)
- ✗ Cancel → Abort

---

Phase 4: Setup TODO Tracking & Status File

Planning Chain → Create Session Dir → Initialize Tracking → Tracking State

Session Structure:

Session ID: CCWP-{goal-slug}-{date}
Session Dir: .workflow/.ccw-plan/{session_id}/

TodoWrite:
  CCWP:{mode}: [1/n] /command1  [in_progress]
  CCWP:{mode}: [2/n] /command2  [pending]
  ...

status.json:
  {
    "session_id": "CCWP-...",
    "mode": "plan-verify",
    "status": "running",
    "command_chain": [...],
    "quality_gate": "pending"  // plan-verify mode only
  }

Output:

• TODO: -> CCWP:plan-verify: [1/2] /workflow:plan | ...
• Status File: .workflow/.ccw-plan/{session_id}/status.json

---

Phase 5: Execute Planning Chain

Start Command → Update status (running) → Execute via Skill → Result

For Plan-Verify Mode (Quality Gate)

Quality Gate → PASS → Mark completed → Next command
             ↓ FAIL (plan-verify mode)
             Ask User → Refine: replan + re-verify
                     → Override: continue anyway
                     → Abort: stop planning

Error Handling Pattern

Command Error → Update status (failed) → Ask User:
  - Retry → Re-execute (same index)
  - Skip → Continue next command
  - Abort → Stop execution

---

Planning Pipeline Examples

Input	Mode	Pipeline	Use Case
"Quick: should we use OAuth2?"	cli	ccw cli --mode analysis → recommendation	Immediate planning advice
"Plan user login system"	lite	lite-plan	Fast simple planning
"Implement OAuth2 auth"	multi-cli	multi-cli-plan → [plan-verify]	Multi-model collaborative planning
"Design notification system"	full	brainstorm → plan → [plan-verify]	Comprehensive brainstorm + planning
"Payment processing (prod)"	plan-verify	plan → plan-verify	Production critical (mandatory gate)
"头脑风暴: 用户通知系统重新设计"	brainstorm-with-file	brainstorm-with-file → (plan/issue options)	Multi-perspective ideation
"协作分析: 认证架构设计决策"	analyze-with-file	analyze-with-file → (plan/issue options)	Collaborative analysis
"Batch plan: handle 10 pending issues"	issue	/issue:discover → plan → queue → execute	Batch issue planning
"Plan and create issues"	rapid-to-issue	lite-plan → convert-to-plan → queue → execute	Quick plan → Issue workflow
"Update existing plan"	replan	replan	Plan refinement/adjustment

Legend:

• [ ] = optional verification
• bold = mandatory quality gate
• With-File modes include built-in post-completion options to create plans/issues

---

State Management

Dual Tracking System

1. TodoWrite-Based Tracking (UI Display):

// Plan-verify mode (mandatory quality gate)
CCWP:plan-verify: [1/2] /workflow:plan          [in_progress]
CCWP:plan-verify: [2/2] /workflow:plan-verify   [pending]

// CLI mode (quick recommendations)
CCWP:cli: [1/1] ccw cli --mode analysis         [in_progress]

// Issue mode (batch planning)
CCWP:issue: [1/4] /issue:discover               [in_progress]
CCWP:issue: [2/4] /issue:plan                   [pending]
CCWP:issue: [3/4] /issue:queue                  [pending]
CCWP:issue: [4/4] /issue:execute                [pending]

// Rapid-to-issue mode (planning → issue bridge)
CCWP:rapid-to-issue: [1/4] /workflow:lite-plan  [in_progress]
CCWP:rapid-to-issue: [2/4] /issue:convert-to-plan [pending]
CCWP:rapid-to-issue: [3/4] /issue:queue         [pending]
CCWP:rapid-to-issue: [4/4] /issue:execute       [pending]

// Brainstorm-with-file mode (self-contained)
CCWP:brainstorm-with-file: [1/1] /workflow:brainstorm-with-file [in_progress]

// Analyze-with-file mode (self-contained)
CCWP:analyze-with-file: [1/1] /workflow:analyze-with-file [in_progress]

// Lite mode (fast simple planning)
CCWP:lite: [1/1] /workflow:lite-plan            [in_progress]

// Multi-CLI mode (collaborative planning)
CCWP:multi-cli: [1/1] /workflow:multi-cli-plan  [in_progress]

// Full mode (brainstorm + planning with optional verification)
CCWP:full: [1/2] /workflow:brainstorm           [in_progress]
CCWP:full: [2/2] /workflow:plan                 [pending]

2. Status.json Tracking: Persistent state for planning monitoring.

Location: .workflow/.ccw-plan/{session_id}/status.json

Structure:

{
  "session_id": "CCWP-oauth-auth-2025-02-02",
  "mode": "plan-verify",
  "status": "running|completed|failed",
  "created_at": "2025-02-02T10:00:00Z",
  "updated_at": "2025-02-02T10:05:00Z",
  "analysis": {
    "goal": "Implement OAuth2 authentication",
    "complexity": "high",
    "clarity_score": 2,
    "criticality": "high"
  },
  "command_chain": [
    { "index": 0, "command": "/workflow:plan", "mandatory": false, "status": "completed" },
    { "index": 1, "command": "/workflow:plan-verify", "mandatory": true, "status": "running" }
  ],
  "current_index": 1,
  "quality_gate": "pending|PASS|FAIL"
}

Status Values:

• running: Planning in progress
• completed: Planning finished successfully
• failed: Planning aborted or quality gate failed

Quality Gate Values (plan-verify mode only):

• pending: Verification not started
• PASS: Plan meets quality standards
• FAIL: Plan needs refinement

Mode-Specific Fields:

• plan-verify: quality_gate field (pending|PASS|FAIL)
• cli: No command_chain, stores CLI recommendations and user decision
• issue: includes issue discovery results and queue configuration
• rapid-to-issue: includes plan output and conversion to issue
• with-file modes: stores session artifacts and post-completion options
• other modes: basic command_chain tracking

---

Extended Planning Modes

CLI-Assisted Planning (cli mode)

Quick Input → ccw cli --mode analysis --rule planning-* → Recommendations → User Decision:
- ✓ Accept → Create lite-plan from recommendations
- ↗ Escalate → Switch to multi-cli or full mode
- ✗ Done → Stop (recommendation only)

Use Cases:

• Quick architecture decision questions
• Planning approach recommendations
• Pattern/library selection advice

CLI Rules (auto-selected based on context):

• planning-plan-architecture-design - Architecture decisions
• planning-breakdown-task-steps - Task decomposition
• planning-design-component-spec - Component specifications

---

With-File Planning Workflows

With-File workflows provide documented exploration with multi-CLI collaboration, generating comprehensive session artifacts.

Mode	Purpose	Key Features	Output Folder
brainstorm-with-file	Multi-perspective ideation	Gemini/Codex/Claude perspectives, diverge-converge	.workflow/.brainstorm/
analyze-with-file	Collaborative architecture analysis	Multi-round Q&A, CLI exploration, documented discussions	.workflow/.analysis/

Detection Keywords:

• brainstorm-with-file: 头脑风暴, 创意, 发散思维, multi-perspective, ideation
• analyze-with-file: 协作分析, 深度理解, collaborative analysis, explore concept

Characteristics:

1. Self-Contained: Each workflow handles its own iteration loop
2. Documented Process: Creates evolving documents (brainstorm.md, discussion.md)
3. Multi-CLI: Uses Gemini/Codex/Claude for different perspectives
4. Built-in Post-Completion: Offers follow-up options (create plan, create issue, deep dive)

---

Issue Workflow Integration

Mode	Purpose	Command Chain	Typical Use
issue	Batch issue planning	discover → plan → queue → execute	Multiple issues in codebase
rapid-to-issue	Quick plan → Issue workflow	lite-plan → convert-to-plan → queue → execute	Fast iteration → structured execution

Issue Workflow Bridge:

lite-plan (in-memory) → /issue:convert-to-plan → Creates issue JSON
                                                      ↓
                                        /issue:queue → Form execution queue
                                                      ↓
                                        /issue:execute → DAG-based parallel execution

When to use Issue Workflow:

• Need structured multi-stage execution (queue-based)
• Want parallel DAG execution
• Multiple related changes as individual commits
• Converting brainstorm/plan output to executable tasks

---

Key Design Principles

1. Planning-Focused - Pure planning coordination, no execution
2. Mode-Driven - 10 planning modes for different needs (lite/multi-cli/full/plan-verify/replan + cli/issue/rapid-to-issue/brainstorm-with-file/analyze-with-file)
3. CLI Integration - Quick analysis for immediate recommendations
4. With-File Support - Multi-CLI collaboration with documented artifacts
5. Issue Workflow Bridge - Seamless transition from planning to structured execution
6. Quality Gates - Mandatory verification for production features
7. Flexible Verification - Optional for exploration, mandatory for critical features
8. Progressive Clarification - Low clarity triggers requirement questions
9. TODO Tracking - Use CCWP prefix to isolate planning todos
10. Handoff Ready - Generates artifacts ready for execution phase

---

Usage

# Auto-select mode (keyword-based detection)
/ccw-plan "Add user authentication"

# Standard planning modes
/ccw-plan --mode lite "Add logout endpoint"
/ccw-plan --mode multi-cli "Implement OAuth2"
/ccw-plan --mode full "Design notification system"
/ccw-plan --mode plan-verify "Payment processing (production)"
/ccw-plan --mode replan --session WFS-auth-2025-01-28

# CLI-assisted planning (quick recommendations)
/ccw-plan --mode cli "Quick: should we use OAuth2 or JWT?"
/ccw-plan --mode cli "Which state management pattern for React app?"

# With-File workflows (multi-CLI collaboration)
/ccw-plan --mode brainstorm-with-file "头脑风暴: 用户通知系统重新设计"
/ccw-plan --mode analyze-with-file "协作分析: 认证架构的设计决策"

# Issue workflow integration
/ccw-plan --mode issue "Batch plan: handle all pending security issues"
/ccw-plan --mode rapid-to-issue "Plan user profile feature and create issue"

# Auto mode (skip confirmations)
/ccw-plan --yes "Quick feature: user profile endpoint"

---

Mode Selection Decision Tree

User calls: /ccw-plan "task description"

├─ Keywords: "quick", "fast", "recommendation"
│  └─ Mode: CLI (quick analysis → recommendations)
│
├─ Keywords: "issue", "batch", "queue"
│  └─ Mode: Issue (batch planning → execution queue)
│
├─ Keywords: "plan.*issue", "rapid.*issue"
│  └─ Mode: Rapid-to-Issue (lite-plan → issue bridge)
│
├─ Keywords: "头脑风暴", "brainstorm", "ideation"
│  └─ Mode: Brainstorm-with-file (multi-CLI ideation)
│
├─ Keywords: "协作分析", "analyze.*document"
│  └─ Mode: Analyze-with-file (collaborative analysis)
│
├─ Keywords: "production", "critical", "payment"
│  └─ Mode: Plan-Verify (mandatory quality gate)
│
├─ Keywords: "adjust", "modify", "change plan"
│  └─ Mode: Replan (refine existing plan)
│
├─ Keywords: "uncertain", "explore"
│  └─ Mode: Full (brainstorm → plan → [verify])
│
├─ Keywords: "complex", "multiple module"
│  └─ Mode: Multi-CLI (collaborative planning)
│
└─ Default → Lite (fast simple planning)