workflow-plan

## Auto Mode When `--yes` or `-y`: Skip all confirmations, use defaults, auto-verify. **This skill is planning-only — it NEVER executes implementation. Output is the plan for user review.** # Workflow Plan ## Usage ```bash # Plan mode (default) $workflow-plan "Build authentication system with JWT and OAuth" $workflow-plan -y "Add rate limiting to API endpoints" $workflow-plan --session WFS-auth "Extend with 2FA support" # Verify mode $workflow-plan verify --session WFS-auth $workflow-plan verify # Replan mode $workflow-plan replan --session WFS-auth "Change from JWT to session-based auth" $workflow-plan replan --session WFS-auth IMPL-3 "Split into two smaller tasks" ``` **Flags**: - `-y, --yes`: Skip all confirmations (auto mode) - `--session ID`: Use specific session --- ## Overview Multi-mode planning pipeline using subagent coordination. Plan mode runs 4 sequential phases with conditional branching; verify and replan modes operate on existing plans. ``` ┌──────────────────────────────────────────────────────────────────┐ │ WORKFLOW PLAN PIPELINE │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Mode Detection: plan | verify | replan │ │ │ │ ═══ Plan Mode (default) ═══ │ │ │ │ Phase 1: Session Discovery │ │ ├─ Create or find workflow session │ │ └─ Initialize planning-notes.md │ │ │ │ Phase 2: Context Gathering (spawn_agent: context-search-agent) │ │ ├─ Codebase analysis → context-package.json │ │ └─ Conflict risk assessment │ │ │ │ Phase 3: Conflict Resolution (conditional: risk ≥ medium) │ │ ├─ CLI-driven conflict analysis │ │ └─ User-selected resolution strategies │ │ │ │ Phase 4: Task Generation (spawn_agent: action-planning-agent) │ │ ├─ Single module → 1 agent │ │ ├─ Multi-module → N+1 parallel agents │ │ └─ Output: IMPL_PLAN.md + task JSONs + TODO_LIST.md │ │ │ │ Plan Confirmation Gate (PLANNING ENDS HERE) │ │ ├─ "Verify Plan" → Phase 5 │ │ ├─ "Done" → Display next-step command for user │ │ └─ "Review Status" → Display inline │ │ │ │ ═══ Verify Mode ═══ │ │ Phase 5: Plan Verification (spawn_agent: cli-explore-agent) │ │ └─ 10-dimension analysis → PLAN_VERIFICATION.md │ │ │ │ ═══ Replan Mode ═══ │ │ Phase 6: Interactive Replan │ │ └─ Clarification → Impact → Backup → Apply → Verify │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## Data Flow ``` User Input (task description) │ ↓ [Convert to GOAL/SCOPE/CONTEXT] │ Phase 1 ──→ sessionId, planning-notes.md │ Phase 2 ──→ context-package.json, conflictRisk │ ├── conflictRisk ≥ medium ──→ Phase 3 ──→ modified artifacts └── conflictRisk < medium ──→ skip Phase 3 │ Phase 4 ──→ IMPL_PLAN.md, plan.json, task JSONs, TODO_LIST.md │ ├── Verify → Phase 5 → PLAN_VERIFICATION.md ├── Execute → workflow-execute skill └── Review → inline display ``` --- ## Session Structure ``` .workflow/active/WFS-{session}/ ├── workflow-session.json # Session metadata ├── planning-notes.md # Accumulated context across phases ├── IMPL_PLAN.md # Implementation plan (human-readable) ├── plan.json # Structured plan overview (machine-readable) ├── TODO_LIST.md # Task checklist ├── .task/ # Task definitions │ ├── IMPL-1.json │ └── IMPL-N.json └── .process/ ├── context-package.json # Phase 2 output ├── conflict-resolution.json # Phase 3 output (conditional) ├── PLAN_VERIFICATION.md # Phase 5 output └── backup/ # Phase 6 backups ``` --- ## Implementation ### Session Initialization ```javascript const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() // Parse flags const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') const sessionMatch = $ARGUMENTS.match(/--session\s+(\S+)/) const existingSessionId = sessionMatch ? sessionMatch[1] : null // Mode detection const cleanArgs = $ARGUMENTS .replace(/--yes|-y|--session\s+\S+/g, '').trim() let mode = 'plan' if (cleanArgs.startsWith('verify')) mode = 'verify' else if (cleanArgs.startsWith('replan')) mode = 'replan' const taskDescription = cleanArgs .replace(/^(verify|replan)\s*/, '') .replace(/^["']|["']$/g, '') .trim() // Extract replan task ID if present const replanTaskMatch = taskDescription.match(/^(IMPL-\d+(?:\.\d+)?)\s+(.+)/) const replanTaskId = replanTaskMatch ? replanTaskMatch[1] : null const replanDescription = replanTaskMatch ? replanTaskMatch[2] : taskDescription ``` --- ### Phase 1: Session Discovery (Plan Mode) **Objective**: Create or find workflow session, initialize planning notes. ```javascript if (mode !== 'plan') { // verify/replan: locate existing session // → Jump to Phase 5 or Phase 6 } let sessionId, sessionFolder if (existingSessionId) { sessionId = existingSessionId sessionFolder = `.workflow/active/${sessionId}` if (!Bash(`test -d "${sessionFolder}" && echo yes`).trim()) { console.log(`ERROR: Session ${sessionId} not found`) return } } else { // Auto-detect from .workflow/active/ or create new const sessions = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null`).trim().split('\n').filter(Boolean) if (sessions.length === 0 || taskDescription) { // Create new session const slug = taskDescription.toLowerCase() .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40) sessionId = `WFS-${slug}` sessionFolder = `.workflow/active/${sessionId}` Bash(`mkdir -p "${sessionFolder}/.task" "${sessionFolder}/.process" "${sessionFolder}/.summaries"`) Write(`${sessionFolder}/workflow-session.json`, JSON.stringify({ session_id: sessionId, status: 'planning', created_at: getUtc8ISOString(), task_description: taskDescription }, null, 2)) } else if (sessions.length === 1) { sessionId = sessions[0].split('/').pop() sessionFolder = sessions[0] } else { // Multiple sessions — ask user if (AUTO_YES) { sessionFolder = sessions[0] sessionId = sessions[0].split('/').pop() } else { const answer = functions.request_user_input({ questions: [{ question: "Multiple sessions found. Select one:", header: "Session", options: sessions.slice(0, 4).map(s => ({ label: s.split('/').pop(), description: s })) }] }) sessionId = answer.Session sessionFolder = `.workflow/active/${sessionId}` } } } // Initialize planning-notes.md const structuredDesc = `GOAL: ${taskDescription}\nSCOPE: Core implementation\nCONTEXT: New development` Write(`${sessionFolder}/planning-notes.md`, `# Planning Notes\n\n## User Intent\n${structuredDesc}\n`) console.log(`Session: ${sessionId}`) ``` --- ### Phase 2: Context Gathering (spawn_agent) **Objective**: Gather project context, assess conflict risk. ```javascript console.log(`\n## Phase 2: Context Gathering\n`) const ctxAgent = spawn_agent({ agent_type: "context_search_agent", instruction: ` Gather implementation context for planning. **Session**: ${sessionFolder} **Task**: ${taskDescription} **Mode**: PLAN ### Steps 1. Analyze project structure (package.json, tsconfig, etc.) 2. Search for existing similar implementations 3. Identify integration points and dependencies 4. Assess conflict risk with existing code 5. Generate context package ### Output Write context package to: ${sessionFolder}/.process/context-package.json Format: { "critical_files": [...], "patterns": [...], "dependencies": [...], "integration_points": [...], "conflict_risk": "none" | "low" | "medium" | "high", "conflict_areas": [...], "constraints": [...] } ` }) wait_agent({ timeout_ms: 1800000 }) // 30 minutes close_agent({ target: ctxAgent }) // Parse outputs const contextPkg = JSON.parse(Read(`${sessionFolder}/.process/context-package.json`) || '{}') const conflictRisk = contextPkg.conflict_risk || 'none' const contextPath = `${sessionFolder}/.process/context-package.json` // Update planning-notes.md Edit(`${sessionFolder}/planning-notes.md`, { oldText: '## User Intent', newText: `## Context Findings - Critical files: ${(contextPkg.critical_files || []).join(', ')} - Conflict risk: ${conflictRisk} - Constraints: ${(contextPkg.constraints || []).join('; ')} ## User Intent` }) console.log(` Context gathered. Conflict risk: ${conflictRisk}`) ``` --- ### Phase 3: Conflict Resolution (Conditional) **Objective**: Detect and resolve conflicts when risk ≥ medium. ```javascript if (['medium', 'high'].includes(conflictRisk)) { console.log(`\n## Phase 3: Conflict Resolution (risk: ${conflictRisk})\n`) Bash({ command: `ccw cli -p "PURPOSE: Analyze and resolve conflicts between planned changes and existing codebase. TASK: • Read context package for conflict areas • Analyze each conflict area in detail • Propose resolution strategies (refactor, adapt, isolate, defer) • For each conflict: assess impact and recommend approach MODE: analysis CONTEXT: @**/* EXPECTED: JSON: {conflicts: [{area, severity, description, strategy, impact}], summary: string} CONSTRAINTS: Focus on ${(contextPkg.conflict_areas || []).join(', ')} TASK DESCRIPTION: ${taskDescription}" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause`, run_in_background: true }) // Wait for CLI → conflicts[] if (!AUTO_YES && conflicts.length > 0) { // Present conflicts and let user select strategies console.log(`\n### Conflicts Found: ${conflicts.length}\n`) conflicts.forEach((c, i) => { console.log(`${i + 1}. [${c.severity}] ${c.area}: ${c.description}`) console.log(` Strategy: ${c.strategy} | Impact: ${c.impact}`) }) const answer = functions.request_user_input({ questions: [{ question: "Accept conflict resolution strategies?", header: "Conflicts", options: [ { label: "Accept All", description: "Apply all recommended strategies" }, { label: "Review Each", description: "Approve strategies individually" }, { label: "Skip", description: "Proceed without resolving" } ] }] }) } // Write resolution Write(`${sessionFolder}/.process/conflict-resolution.json`, JSON.stringify({ conflicts, resolved_at: getUtc8ISOString() }, null, 2)) // Update planning-notes // Append conflict decisions to planning-notes.md } else { console.log(` Conflict risk: ${conflictRisk} — skipping Phase 3`) } ``` --- ### Phase 4: Task Generation (spawn_agent) **Objective**: Generate IMPL_PLAN.md, task JSONs, TODO_LIST.md. **Steps**: 1. **Determine Planning Strategy** ```javascript console.log(`\n## Phase 4: Task Generation\n`) // Detect module count from context const modules = contextPkg.integration_points?.map(p => p.module).filter(Boolean) || [] const uniqueModules = [...new Set(modules)] const isMultiModule = uniqueModules.length >= 2 ``` 2. **Single Module → One Agent** ```javascript if (!isMultiModule) { const planAgent = spawn_agent({ agent_type: "action_planning_agent", instruction: ` Generate implementation plan and task JSONs. **Session**: ${sessionFolder} **Task**: ${taskDescription} **Context**: ${contextPath} **Planning Notes**: ${sessionFolder}/planning-notes.md ${contextPkg.conflict_risk === 'medium' || contextPkg.conflict_risk === 'high'