--- description: Lightweight interactive planning workflow with single-agent merged mode for explore → clarify → plan full flow. Supports depth control and auto-clarification. argument-hint: "TASK=\"\" [--depth=standard|deep] [--auto-clarify] [--max-rounds=] [--verbose]" --- # Workflow Lite-Plan-A (Merged Mode) ## Overview Single-agent merged mode for lightweight planning. One agent handles exploration, clarification, and planning in a continuous conversation, maximizing context retention and minimizing agent creation overhead. **Core capabilities:** - **Single agent dual-role execution** (explorer + planner in one conversation) - Context automatically preserved across phases (no serialization loss) - Reduced user interaction rounds (1-2 vs 3-4) - Best for Low/Medium complexity tasks with single exploration angle ## Applicable Scenarios - **Low/Medium complexity tasks** - Single exploration angle sufficient - Prioritize minimal agent creation and coherent context - Clear, well-defined tasks within single module ## Core Advantages | Metric | Traditional Separated Mode | Plan-A Merged Mode | |--------|---------------------------|-------------------| | Agent creation count | 2-5 | **1** | | Context transfer | Serialized, lossy | **Automatic retention** | | User interaction rounds | 3-4 | **1-2** | | Execution time | Multiple spawn/close | **30-50%↓** | ## Task Description **Target task**: $TASK - `--depth`: Exploration depth (standard|deep) - `--auto-clarify`: Auto clarify, skip confirmation - `--max-rounds`: Max interaction rounds ## Execution Process ``` ┌─────────────────────────────────────────────────────────────┐ │ spawn_agent (dual role: explorer + planner) │ │ ↓ │ │ Phase 1: Exploration → output findings + clarification_needs│ │ ↓ │ │ wait() → get exploration results │ │ ↓ │ │ [If clarification needed] Main process collects user answers│ │ ↓ │ │ send_input(clarification_answers + "generate plan") │ │ ↓ │ │ Phase 2: Planning → output plan.json │ │ ↓ │ │ wait() → get planning results │ │ ↓ │ │ close_agent() │ └─────────────────────────────────────────────────────────────┘ ``` ## Implementation ### Session Setup **Session Setup** (MANDATORY - follow exactly): ```javascript // Helper: Get UTC+8 (China Standard Time) ISO string const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() const taskSlug = "$TASK".toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 const sessionId = `${taskSlug}-${dateStr}` // e.g., "implement-jwt-refresh-2025-11-29" const sessionFolder = `.workflow/.lite-plan/${sessionId}` // Create session folder mkdir -p ${sessionFolder} ``` ### Complexity Assessment & Angle Selection ```javascript const complexity = analyzeTaskComplexity("$TASK") // Plan-A is suitable for Low/Medium; High complexity should use Plan-B const ANGLE_PRESETS = { architecture: ['architecture', 'dependencies'], security: ['security', 'auth-patterns'], performance: ['performance', 'bottlenecks'], bugfix: ['error-handling', 'dataflow'], feature: ['patterns', 'integration-points'] } // Plan-A selects only 1-2 most relevant angles const primaryAngle = selectPrimaryAngle("$TASK") ``` --- ### Phase 1 & 2: Single Agent Dual-Role Execution (Codex Pattern) ```javascript // ==================== PLAN-A: SINGLE AGENT MERGED MODE ==================== // Step 1: Create dual-role agent (role files read by agent itself) const agent = spawn_agent({ message: ` ## TASK ASSIGNMENT ### Overview You will complete this task in TWO phases using a SINGLE conversation: 1. **Phase 1**: Explore codebase, output findings and clarification questions 2. **Phase 2**: After receiving clarification answers, generate implementation plan ### Task Description ${task_description} ### Session Info - Session ID: ${sessionId} - Session Folder: ${sessionFolder} - Primary Angle: ${primaryAngle} --- ## PHASE 1: EXPLORATION ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read explorer role**: ~/.codex/agents/cli-explore-agent.md (MUST read first) 2. **Read planner role**: ~/.codex/agents/cli-lite-planning-agent.md (for Phase 2) 3. Run: ccw tool exec get_modules_by_depth '{}' 4. Run: rg -l "{keyword_from_task}" --type ts 5. Read: .workflow/project-tech.json 6. Read: .workflow/project-guidelines.json ### Exploration Focus: ${primaryAngle} - Identify relevant files and modules - Discover existing patterns and conventions - Map dependencies and integration points - Note constraints and limitations ### Phase 1 Output Format \`\`\` ## EXPLORATION COMPLETE ### Findings Summary - [Key finding 1] - [Key finding 2] - [Key finding 3] ### Relevant Files | File | Relevance | Rationale | |------|-----------|-----------| | path/to/file1.ts | 0.9 | [reason] | | path/to/file2.ts | 0.8 | [reason] | ### Patterns to Follow - [Pattern 1 with code example] - [Pattern 2 with code example] ### Integration Points - [file:line] - [description] ### Constraints - [Constraint 1] - [Constraint 2] CLARIFICATION_NEEDED: Q1: [question] | Options: [A, B, C] | Recommended: [B] Q2: [question] | Options: [A, B] | Recommended: [A] \`\`\` **If no clarification needed**, output: \`\`\` CLARIFICATION_NEEDED: NONE Ready for Phase 2. Send "PROCEED_TO_PLANNING" to continue. \`\`\` ### Write Exploration File Write findings to: ${sessionFolder}/exploration.json ` }) // Step 2: Wait for Phase 1 to complete const phase1Result = wait({ ids: [agent], timeout_ms: 600000 }) const phase1Output = phase1Result.status[agent].completed // Step 3: Handle clarification (if needed) let clarificationAnswers = null if (phase1Output.includes('CLARIFICATION_NEEDED:') && !phase1Output.includes('CLARIFICATION_NEEDED: NONE')) { // Parse questions, collect user answers const questions = parseClarificationQuestions(phase1Output) // Display questions to user, collect answers console.log(` ## Clarification Needed ${questions.map((q, i) => ` ### Q${i+1}: ${q.question} Options: ${q.options.join(', ')} Recommended: ${q.recommended} `).join('\n')} **Please provide your answers...** `) // Wait for user input... clarificationAnswers = collectUserAnswers(questions) } // Step 4: Send Phase 2 instruction (continue with same agent) send_input({ id: agent, message: ` ## PHASE 2: GENERATE PLAN ${clarificationAnswers ? ` ### Clarification Answers ${clarificationAnswers.map(a => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')} ` : '### No clarification needed - proceeding with exploration findings'} ### Planning Instructions 1. **Read Schema** Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json 2. **Generate Plan** based on your exploration findings - Summary: 2-3 sentence overview - Approach: High-level strategy - Tasks: 2-7 tasks grouped by feature (NOT by file) - Each task needs: id, title, scope, action, description, modification_points, implementation, acceptance, depends_on 3. **Task Grouping Rules** - Group by feature: All changes for one feature = one task - Substantial tasks: 15-60 minutes of work each - True dependencies only: Use depends_on sparingly - Prefer parallel: Most tasks should be independent 4. **Write Output** Write: ${sessionFolder}/plan.json ### Output Format Return brief completion summary after writing plan.json ` }) // Step 5: Wait for Phase 2 to complete const phase2Result = wait({ ids: [agent], timeout_ms: 600000 }) // Step 6: Cleanup close_agent({ id: agent }) ``` --- ### Phase 3: Confirmation ```javascript const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) console.log(` ## Implementation Plan **Summary**: ${plan.summary} **Approach**: ${plan.approach} **Complexity**: ${plan.complexity} **Tasks** (${plan.tasks.length}): ${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')} **Estimated Time**: ${plan.estimated_time} --- ## Confirmation Required Please review the plan above and reply with one of the following: - **"Allow"** - Proceed with this plan, output plan.json - **"Modify"** - Describe what changes you want to make - **"Cancel"** - Abort the planning workflow **WAITING FOR USER CONFIRMATION...** `) ``` --- ## Codex vs Claude Comparison (for merged mode) | Aspect | Claude Code Task | Codex Subagent (Plan-A) | |--------|------------------|------------------------| | **Creation** | `Task({ subagent_type, prompt })` | `spawn_agent({ message: role + task })` | | **Role Loading** | Auto via `subagent_type` | Manual: Agent reads `~/.codex/agents/*.md` | | **Multi-phase** | Separate agents or resume | **Single agent + send_input** | | **Context Retention** | Lossy (serialization) | **Automatic (same conversation)** | | **Follow-up** | `resume` parameter | `send_input({ id, message })` | | **Cleanup** | Automatic | **Explicit `close_agent({ id })`** | **Plan-A Advantages**: - Zero context loss between phases - Single agent lifecycle to manage - Minimal overhead for simple tasks --- ## Session Folder Structure ``` .workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/ ├── exploration.json # Phase 1 output └── plan.json # Phase 2 output (after confirmation) ``` ## Workflow States | State | Action | Next | |-------|--------|------| | Phase 1 Output | Exploration complete | → Wait for clarification or Phase 2 | | Clarification Output | Questions displayed | → Wait for user reply | | User Replied | Answers received | → send_input to Phase 2 | | Phase 2 Output | Plan generated | → Phase 3 (Confirmation) | | User: "Allow" | Confirmed | → Output complete | | User: "Modify" | Changes requested | → send_input with revisions | | User: "Cancel" | Aborted | → close_agent, end workflow | ## Error Handling | Error | Resolution | |-------|------------| | Phase 1 timeout | Continue wait or send_input to request convergence | | Phase 2 timeout | send_input requesting current progress output | | Agent unexpectedly closed | Re-spawn, paste previous output in message | | User cancels | close_agent, preserve generated files | **Execute task**: $TASK