Claude-Code-Workflow/.codex/prompts/lite-plan-a.md

description, argument-hint

description	argument-hint
Lightweight interactive planning workflow with single-agent merged mode for explore → clarify → plan full flow. Supports depth control and auto-clarification.	TASK="<task description or file.md path>" [--depth=standard|deep] [--auto-clarify] [--max-rounds=<n>] [--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):

// 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

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)

// ==================== 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

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