From 407b2e6930566d70b19e9ecab820a9ff0ce6fea7 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 22 Jan 2026 21:40:57 +0800 Subject: [PATCH] Add lightweight interactive planning workflows: Lite-Plan-B and Lite-Plan-C - Introduced Lite-Plan-B for hybrid mode planning with multi-agent parallel exploration and primary agent merge/clarify/plan capabilities. - Added Lite-Plan-C for Codex subagent orchestration, featuring intelligent task analysis, parallel exploration, and adaptive planning based on task complexity. - Both workflows include detailed execution processes, session setup, and structured output formats for exploration and planning results. --- .codex/prompts/lite-execute.md | 774 ++++++++++++++---- .codex/prompts/lite-fix.md | 670 +++++++++++++++ .codex/prompts/lite-plan-a.md | 349 ++++++++ .codex/prompts/lite-plan-b.md | 497 +++++++++++ .../prompts/{lite-plan.md => lite-plan-c.md} | 302 +++++-- codex SUBAGENT 策略补充.md | 367 +++++++-- 6 files changed, 2688 insertions(+), 271 deletions(-) create mode 100644 .codex/prompts/lite-fix.md create mode 100644 .codex/prompts/lite-plan-a.md create mode 100644 .codex/prompts/lite-plan-b.md rename .codex/prompts/{lite-plan.md => lite-plan-c.md} (55%) diff --git a/.codex/prompts/lite-execute.md b/.codex/prompts/lite-execute.md index 71714665..c10c2216 100644 --- a/.codex/prompts/lite-execute.md +++ b/.codex/prompts/lite-execute.md @@ -1,189 +1,683 @@ --- -description: Execute tasks sequentially from plan.json file -argument-hint: FILE= +description: Execute tasks based on in-memory plan, prompt description, or file content (Codex Subagent Version) +argument-hint: "[--in-memory] [\"task description\"|file-path]" --- -# Workflow Lite-Execute (Codex Version) +# Workflow Lite-Execute Command (Codex Subagent Version) -## Core Principle +## Overview -**Serial Execution**: Execute tasks ONE BY ONE in order. Complete current task fully before moving to next. Continue until ALL tasks complete. +Flexible task execution command with **optimized Codex subagent orchestration**. Supports three input modes: in-memory plan (from lite-plan), direct prompt description, or file content. -## Input +**Core Optimizations:** +- **Batch Parallel Execution**: `spawn_agent × N → wait({ ids: [...] })` for independent tasks +- **Context Preservation**: Primary executor retained for follow-ups via `send_input()` +- **Unified Prompt Builder**: Same template for both Agent and CLI executors +- **Explicit Lifecycle**: `spawn_agent → wait → [send_input] → close_agent` -Read plan file at `$FILE` path (e.g., `.workflow/.lite-plan/session-id/plan.json`) +**Core capabilities:** +- Multi-mode input (in-memory plan, prompt description, or file path) +- Execution orchestration via Codex subagents with full context +- Live progress tracking via TodoWrite at batch level +- Optional code review with selected tool (Gemini, Codex, or custom) +- Context continuity across multiple executions +- Intelligent format detection (Enhanced Task JSON vs plain text) -## Autonomous Execution Loop - -``` -WHILE tasks remain: - 1. Read plan.json → Get task list - 2. Find FIRST task with status != "completed" - 3. IF task.depends_on exists: - - Check all dependencies completed - - IF not met → Skip, find next eligible task - 4. Execute current task fully - 5. Mark task completed in plan.json - 6. Output progress: "[X/N] Task completed: {title}" - 7. CONTINUE to next task (DO NOT STOP) - -WHEN all tasks completed: - Output final summary -``` - -## Step-by-Step Execution - -### Step 1: Load Plan +## Usage +### Command Syntax ```bash -cat $FILE +/workflow:lite-execute [FLAGS] + +# Flags +--in-memory Use plan from memory (called by lite-plan) + +# Arguments + Task description string, or path to file (required) ``` -Parse JSON, extract: -- `summary`: Overall goal -- `tasks[]`: Task list with status +## Input Modes -### Step 2: Find Next Task +### Mode 1: In-Memory Plan + +**Trigger**: Called by lite-plan after Phase 4 approval with `--in-memory` flag + +**Input Source**: `executionContext` global variable set by lite-plan + +**Behavior**: +- Skip execution method selection (already set by lite-plan) +- Directly proceed to execution with full context +- All planning artifacts available (exploration, clarifications, plan) + +### Mode 2: Prompt Description + +**Trigger**: User calls with task description string + +**Input**: Simple task description (e.g., "Add unit tests for auth module") + +**Behavior**: +- Store prompt as `originalUserInput` +- Create simple execution plan from prompt +- AskUserQuestion: Select execution method (Agent/Codex/Auto) +- AskUserQuestion: Select code review tool (Skip/Gemini/Codex/Other) +- Proceed to execution with `originalUserInput` included + +### Mode 3: File Content + +**Trigger**: User calls with file path + +**Input**: Path to file containing task description or plan.json + +**Behavior**: +- Read file and detect format (plan.json vs plain text) +- If plan.json: Use `planObject` directly +- If plain text: Treat as prompt (same as Mode 2) + +## Execution Process + +``` +Input Parsing: + └─ Decision (mode detection): + ├─ --in-memory flag → Mode 1: Load executionContext → Skip user selection + ├─ Ends with .md/.json/.txt → Mode 3: Read file → Detect format + │ ├─ Valid plan.json → Use planObject → User selects method + review + │ └─ Not plan.json → Treat as prompt → User selects method + review + └─ Other → Mode 2: Prompt description → User selects method + review + +Execution (Codex Subagent Pattern): + ├─ Step 1: Initialize result tracking (previousExecutionResults = []) + ├─ Step 2: Task grouping & batch creation + │ ├─ Extract explicit depends_on (no inference) + │ ├─ Group: independent tasks → single parallel batch + │ └─ Group: dependent tasks → sequential phases + ├─ Step 3: Launch execution (spawn_agent × N → wait → close) + │ ├─ Phase 1: All independent tasks (spawn_agent × N → batch wait) + │ └─ Phase 2+: Dependent tasks (sequential spawn_agent → wait → close) + ├─ Step 4: Track progress (TodoWrite updates per batch) + └─ Step 5: Code review (if codeReviewTool ≠ "Skip") + +Output: + └─ Execution complete with results in previousExecutionResults[] +``` + +## Implementation + +### Step 1: Initialize Execution Tracking ```javascript -// Find first non-completed task with met dependencies -for (task of tasks) { - if (task.status === "completed") continue - if (task.depends_on?.every(dep => getTask(dep).status === "completed")) { - return task // Execute this one - } +// Initialize result tracking +previousExecutionResults = [] + +// In-Memory Mode: Echo execution strategy +if (executionContext) { + console.log(` +## Execution Strategy (from lite-plan) + +- **Method**: ${executionContext.executionMethod} +- **Review**: ${executionContext.codeReviewTool} +- **Tasks**: ${executionContext.planObject.tasks.length} +- **Complexity**: ${executionContext.planObject.complexity} +${executionContext.executorAssignments ? `- **Assignments**: ${JSON.stringify(executionContext.executorAssignments)}` : ''} + `) } -return null // All done ``` -### Step 3: Execute Task +### Step 2: Task Grouping & Batch Creation -For current task, perform: +```javascript +// Use explicit depends_on from plan.json (no inference) +function extractDependencies(tasks) { + const taskIdToIndex = {} + tasks.forEach((t, i) => { taskIdToIndex[t.id] = i }) -```markdown -## Executing: [task.title] + return tasks.map((task, i) => { + const deps = (task.depends_on || []) + .map(depId => taskIdToIndex[depId]) + .filter(idx => idx !== undefined && idx < i) + return { ...task, taskIndex: i, dependencies: deps } + }) +} -**Scope**: `[task.scope]` (module/feature level) -**Action**: [task.action] +// Group into batches: maximize parallel execution +function createExecutionBatches(tasks, executionMethod) { + const tasksWithDeps = extractDependencies(tasks) + const processed = new Set() + const batches = [] + + // Phase 1: All independent tasks → single parallel batch + const independentTasks = tasksWithDeps.filter(t => t.dependencies.length === 0) + if (independentTasks.length > 0) { + independentTasks.forEach(t => processed.add(t.taskIndex)) + batches.push({ + method: executionMethod, + executionType: "parallel", + groupId: "P1", + taskSummary: independentTasks.map(t => t.title).join(' | '), + tasks: independentTasks + }) + } + + // Phase 2+: Dependent tasks → sequential batches + let remaining = tasksWithDeps.filter(t => !processed.has(t.taskIndex)) + + while (remaining.length > 0) { + const ready = remaining.filter(t => + t.dependencies.every(d => processed.has(d)) + ) + + if (ready.length === 0) { + console.warn('Circular dependency detected, forcing remaining tasks') + ready.push(...remaining) + } + + ready.forEach(t => processed.add(t.taskIndex)) + batches.push({ + method: executionMethod, + executionType: ready.length > 1 ? "parallel" : "sequential", + groupId: `P${batches.length + 1}`, + taskSummary: ready.map(t => t.title).join(' | '), + tasks: ready + }) + + remaining = remaining.filter(t => !processed.has(t.taskIndex)) + } + + return batches +} + +const executionBatches = createExecutionBatches(planObject.tasks, executionMethod) + +TodoWrite({ + todos: executionBatches.map(b => ({ + content: `${b.executionType === "parallel" ? "⚡" : "→"} [${b.groupId}] (${b.tasks.length} tasks)`, + status: "pending", + activeForm: `Executing ${b.groupId}` + })) +}) +``` + +### Step 3: Launch Execution (Codex Subagent Pattern) + +#### Executor Resolution + +```javascript +// Get executor for task (task-level > global) +function getTaskExecutor(task) { + const assignments = executionContext?.executorAssignments || {} + if (assignments[task.id]) { + return assignments[task.id].executor // 'gemini' | 'codex' | 'agent' + } + // Fallback: global executionMethod mapping + const method = executionContext?.executionMethod || 'Auto' + if (method === 'Agent') return 'agent' + if (method === 'Codex') return 'codex' + // Auto: based on complexity + return planObject.complexity === 'Low' ? 'agent' : 'codex' +} +``` + +#### Unified Task Prompt Builder + +```javascript +function buildExecutionPrompt(batch) { + const formatTask = (t) => ` +## ${t.title} + +**Scope**: \`${t.scope}\` | **Action**: ${t.action} ### Modification Points -For each point in task.modification_points: -- **File**: [point.file] -- **Target**: [point.target] (function/class/line range) -- **Change**: [point.change] +${t.modification_points.map(p => `- **${p.file}** → \`${p.target}\`: ${p.change}`).join('\n')} -### Implementation -[Follow task.implementation steps] +${t.rationale ? ` +### Why this approach +${t.rationale.chosen_approach} +${t.rationale.decision_factors?.length > 0 ? `\nKey factors: ${t.rationale.decision_factors.join(', ')}` : ''} +` : ''} -### Reference Pattern -- Pattern: [task.reference.pattern] -- Files: [task.reference.files] -- Examples: [task.reference.examples] +### How to do it +${t.description} -### Acceptance Criteria -- [ ] [criterion 1] -- [ ] [criterion 2] -``` +${t.implementation.map(step => `- ${step}`).join('\n')} -**Execute all modification points. Verify all acceptance criteria.** +### Reference +- Pattern: ${t.reference?.pattern || 'N/A'} +- Files: ${t.reference?.files?.join(', ') || 'N/A'} -### Step 4: Mark Completed +### Done when +${t.acceptance.map(c => `- [ ] ${c}`).join('\n')}` -Update task status in plan.json: -```json -{ - "id": "task-id", - "status": "completed" // Change from "pending" + const sections = [] + + if (originalUserInput) sections.push(`## Goal\n${originalUserInput}`) + + sections.push(`## Tasks\n${batch.tasks.map(formatTask).join('\n\n---\n')}`) + + // Context + const context = [] + if (previousExecutionResults.length > 0) { + context.push(`### Previous Work\n${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}`).join('\n')}`) + } + if (clarificationContext) { + context.push(`### Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `- ${q}: ${a}`).join('\n')}`) + } + context.push(`### Project Guidelines\n@.workflow/project-guidelines.json`) + if (context.length > 0) sections.push(`## Context\n${context.join('\n\n')}`) + + sections.push(`Complete each task according to its "Done when" checklist.`) + + return sections.join('\n\n') } ``` -### Step 5: Continue +#### Parallel Batch Execution (Codex Pattern) -**DO NOT STOP. Immediately proceed to Step 2 to find next task.** +```javascript +// ==================== CODEX SUBAGENT PATTERN ==================== -Output progress: -``` -✓ [2/5] Completed: [task.title] -→ Next: [next_task.title] -``` +async function executeBatch(batch) { + const executor = getTaskExecutor(batch.tasks[0]) + + if (executor === 'agent') { + return executeWithAgent(batch) + } else { + return executeWithCLI(batch, executor) + } +} -## Task Format Reference +// Option A: Agent Execution (spawn_agent pattern) +async function executeWithAgent(batch) { + // Step 1: Spawn agents for parallel execution (role file read by agent itself) + const executionAgents = batch.tasks.map((task, index) => { + return spawn_agent({ + message: ` +## TASK ASSIGNMENT -```json -{ - "id": "T1", - "title": "Implement auth validation", - "scope": "src/auth/", - "action": "Create|Update|Implement|Refactor|Add|Delete|Configure|Test|Fix", - "description": "What to implement (1-2 sentences)", - "modification_points": [ - { - "file": "src/auth/validator.ts", - "target": "validateToken:45-60", - "change": "Add expiry check" - }, - { - "file": "src/auth/middleware.ts", - "target": "authMiddleware", - "change": "Call new validator" +### Execution Context +- **Batch ID**: ${batch.groupId} +- **Task Index**: ${index + 1} of ${batch.tasks.length} +- **Execution Type**: ${batch.executionType} + +### Task Content +${buildExecutionPrompt({ ...batch, tasks: [task] })} + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first) +2. Read: .workflow/project-tech.json (technology context) +3. Read: .workflow/project-guidelines.json (constraints) +4. Understand existing patterns before modifying + +### Quality Standards +- Follow existing code patterns +- Maintain backward compatibility +- No unnecessary changes beyond scope + +### Deliverables +- Implement task according to "Done when" checklist +- Return: Brief completion summary with files modified +` + }) + }) + + // Step 3: Batch wait for all agents + const results = wait({ + ids: executionAgents, + timeout_ms: 900000 // 15 minutes per batch + }) + + // Step 4: Collect results + const batchResult = { + executionId: `[${batch.groupId}]`, + status: results.timed_out ? 'partial' : 'completed', + tasksSummary: batch.taskSummary, + completionSummary: '', + keyOutputs: '', + notes: '' + } + + executionAgents.forEach((agentId, index) => { + if (results.status[agentId].completed) { + batchResult.completionSummary += `Task ${index + 1}: ${results.status[agentId].completed}\n` } - ], - "implementation": ["step 1", "step 2", "...max 7 steps"], - "reference": { - "pattern": "pattern name", - "files": ["example1.ts"], - "examples": "specific guidance" - }, - "acceptance": ["criterion 1", "criterion 2"], - "depends_on": ["T0"], - "status": "pending|completed" + }) + + // Step 5: Cleanup all agents + executionAgents.forEach(id => close_agent({ id })) + + return batchResult +} + +// Option B: CLI Execution (ccw cli) +async function executeWithCLI(batch, executor) { + const sessionId = executionContext?.session?.id || 'standalone' + const fixedExecutionId = `${sessionId}-${batch.groupId}` + + const cli_command = `ccw cli -p "${buildExecutionPrompt(batch)}" --tool ${executor} --mode write --id ${fixedExecutionId}` + + // Execute in background + Bash({ + command: cli_command, + run_in_background: true + }) + + // STOP HERE - CLI executes in background, task hook will notify on completion + return { + executionId: `[${batch.groupId}]`, + status: 'in_progress', + tasksSummary: batch.taskSummary, + fixedCliId: fixedExecutionId + } } ``` -**Key Fields**: -- `scope`: Module/feature level path (prefer over single file) -- `modification_points[]`: All files to modify with precise targets -- `target`: Function/class/line range (e.g., `validateToken:45-60`) +#### Execution Flow -## Execution Rules +```javascript +// ==================== MAIN EXECUTION FLOW ==================== -1. **Never stop mid-workflow** - Continue until all tasks complete -2. **One task at a time** - Fully complete before moving on -3. **Respect dependencies** - Skip blocked tasks, return later -4. **Update status immediately** - Mark completed right after finishing -5. **Self-verify** - Check acceptance criteria before marking done +const parallelBatches = executionBatches.filter(b => b.executionType === "parallel") +const sequentialBatches = executionBatches.filter(b => b.executionType === "sequential") -## Final Summary +// Phase 1: Launch all parallel batches (Codex batch wait advantage) +if (parallelBatches.length > 0) { + TodoWrite({ + todos: executionBatches.map(b => ({ + status: b.executionType === "parallel" ? "in_progress" : "pending" + })) + }) + + // Spawn all parallel batch agents at once (role file read by agent itself) + const allParallelAgents = [] + const batchToAgents = new Map() + + for (const batch of parallelBatches) { + const executor = getTaskExecutor(batch.tasks[0]) + + if (executor === 'agent') { + const agents = batch.tasks.map((task, index) => spawn_agent({ + message: ` +## TASK: ${task.title} +${buildExecutionPrompt({ ...batch, tasks: [task] })} -When ALL tasks completed: +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json +` + })) + + allParallelAgents.push(...agents) + batchToAgents.set(batch.groupId, agents) + } + } + + // Single batch wait for ALL parallel agents (KEY CODEX ADVANTAGE) + if (allParallelAgents.length > 0) { + const parallelResults = wait({ + ids: allParallelAgents, + timeout_ms: 900000 + }) + + // Collect results per batch + for (const batch of parallelBatches) { + const agents = batchToAgents.get(batch.groupId) || [] + const batchResult = { + executionId: `[${batch.groupId}]`, + status: 'completed', + tasksSummary: batch.taskSummary, + completionSummary: agents.map((id, i) => + parallelResults.status[id]?.completed || 'incomplete' + ).join('\n') + } + previousExecutionResults.push(batchResult) + } + + // Cleanup all parallel agents + allParallelAgents.forEach(id => close_agent({ id })) + } + + TodoWrite({ + todos: executionBatches.map(b => ({ + status: parallelBatches.includes(b) ? "completed" : "pending" + })) + }) +} -```markdown -## Execution Complete - -**Plan**: $FILE -**Total Tasks**: N -**All Completed**: Yes - -### Results -| # | Task | Status | -|---|------|--------| -| 1 | [title] | ✓ | -| 2 | [title] | ✓ | - -### Files Modified -- `path/file1.ts` -- `path/file2.ts` - -### Summary -[Brief description of what was accomplished] +// Phase 2: Execute sequential batches one by one +for (const batch of sequentialBatches) { + TodoWrite({ + todos: executionBatches.map(b => ({ + status: b === batch ? "in_progress" : (processed.has(b) ? "completed" : "pending") + })) + }) + + const result = await executeBatch(batch) + previousExecutionResults.push(result) + + TodoWrite({ + todos: executionBatches.map(b => ({ + status: "completed" /* or "pending" for remaining */ + })) + }) +} ``` +### Step 4: Progress Tracking + +Progress tracked at batch level. Icons: ⚡ (parallel), → (sequential) + +### Step 5: Code Review (Optional) + +**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"` + +```javascript +// ==================== CODE REVIEW (CODEX PATTERN) ==================== + +if (codeReviewTool !== 'Skip') { + console.log(` +## Code Review + +Starting ${codeReviewTool} review... +`) + + const reviewPrompt = ` +PURPOSE: Code review for implemented changes against plan acceptance criteria +TASK: • Verify plan acceptance criteria • Check verification requirements • Analyze code quality • Identify issues +MODE: analysis +CONTEXT: @**/* @${executionContext.session.artifacts.plan} | Memory: Review lite-execute changes +EXPECTED: Quality assessment with: acceptance verification, issue identification, recommendations +CONSTRAINTS: Focus on plan acceptance criteria | analysis=READ-ONLY +` + + if (codeReviewTool === 'Agent Review') { + // Spawn review agent (role file read by agent itself) + const reviewAgent = spawn_agent({ + message: ` +## TASK: Code Review + +${reviewPrompt} + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first) +2. Read plan artifact: ${executionContext.session.artifacts.plan} +${executionContext.session.artifacts.explorations?.map(e => `3. Read exploration: ${e.path}`).join('\n') || ''} + +### Review Focus +1. Verify each acceptance criterion from plan.tasks[].acceptance +2. Check verification requirements (unit_tests, success_metrics) +3. Validate plan adherence and risk mitigations +4. Identify any issues or improvements needed + +### Output Format +Summary: [overall assessment] +Acceptance: [criterion 1: ✓/✗, criterion 2: ✓/✗, ...] +Issues: [list of issues if any] +Recommendations: [suggestions] +` + }) + + const reviewResult = wait({ + ids: [reviewAgent], + timeout_ms: 600000 + }) + + console.log(` +### Review Complete + +${reviewResult.status[reviewAgent].completed} +`) + + close_agent({ id: reviewAgent }) + + } else if (codeReviewTool === 'Gemini Review') { + // CLI-based review + Bash({ + command: `ccw cli -p "${reviewPrompt}" --tool gemini --mode analysis`, + run_in_background: true + }) + // Wait for hook callback + + } else if (codeReviewTool === 'Codex Review') { + // Git-aware review + Bash({ + command: `ccw cli --tool codex --mode review --uncommitted`, + run_in_background: true + }) + // Wait for hook callback + } +} +``` + +### Step 6: Update Development Index + +```javascript +// After all executions complete +const projectJsonPath = '.workflow/project-tech.json' +if (fileExists(projectJsonPath)) { + const projectJson = JSON.parse(Read(projectJsonPath)) + + if (!projectJson.development_index) { + projectJson.development_index = { feature: [], enhancement: [], bugfix: [], refactor: [], docs: [] } + } + + function detectCategory(text) { + text = text.toLowerCase() + if (/\b(fix|bug|error|issue|crash)\b/.test(text)) return 'bugfix' + if (/\b(refactor|cleanup|reorganize)\b/.test(text)) return 'refactor' + if (/\b(doc|readme|comment)\b/.test(text)) return 'docs' + if (/\b(add|new|create|implement)\b/.test(text)) return 'feature' + return 'enhancement' + } + + const category = detectCategory(`${planObject.summary} ${planObject.approach}`) + const entry = { + title: planObject.summary.slice(0, 60), + date: new Date().toISOString().split('T')[0], + description: planObject.approach.slice(0, 100), + status: previousExecutionResults.every(r => r.status === 'completed') ? 'completed' : 'partial', + session_id: executionContext?.session?.id || null + } + + projectJson.development_index[category].push(entry) + Write(projectJsonPath, JSON.stringify(projectJson, null, 2)) + + console.log(`✓ Development index: [${category}] ${entry.title}`) +} +``` + +--- + +## Codex vs Claude Comparison (for this workflow) + +| Aspect | Claude Code Task | Codex Subagent | +|--------|------------------|----------------| +| **Creation** | `Task({ subagent_type, prompt })` | `spawn_agent({ message: task })` | +| **Role Loading** | Auto via `subagent_type` | Agent reads `~/.codex/agents/*.md` in MANDATORY FIRST STEPS | +| **Parallel Wait** | Multiple `Task()` calls | **Batch `wait({ ids: [...] })`** | +| **Result Retrieval** | Sync return or `TaskOutput` | `wait({ ids }).status[id].completed` | +| **Follow-up** | `resume` parameter | `send_input({ id, message })` | +| **Cleanup** | Automatic | **Explicit `close_agent({ id })`** | + +**Codex Advantages for lite-execute**: +- True parallel execution with batch `wait` for all independent tasks +- Single wait call for multiple agents (reduced orchestration overhead) +- Fine-grained lifecycle control for complex task graphs + +--- + +## Data Structures + +### executionContext (Input - Mode 1) + +```javascript +{ + planObject: { + summary: string, + approach: string, + tasks: [...], + estimated_time: string, + recommended_execution: string, + complexity: string + }, + clarificationContext: {...} | null, + executionMethod: "Agent" | "Codex" | "Auto", + codeReviewTool: "Skip" | "Gemini Review" | "Codex Review" | string, + originalUserInput: string, + executorAssignments: { + [taskId]: { executor: "gemini" | "codex" | "agent", reason: string } + }, + session: { + id: string, + folder: string, + artifacts: { + explorations: [{angle, path}], + plan: string + } + } +} +``` + +### executionResult (Output) + +```javascript +{ + executionId: string, // e.g., "[P1]", "[S1]" + status: "completed" | "partial" | "failed", + tasksSummary: string, + completionSummary: string, + keyOutputs: string, + notes: string, + fixedCliId: string | null // For CLI resume capability +} +``` + +--- + ## Error Handling -| Situation | Action | -|-----------|--------| -| File not found | Error and stop | -| Task blocked (deps not met) | Skip, try next task | -| All remaining tasks blocked | Report circular dependency | -| Task execution error | Report error, mark failed, continue to next | -| Acceptance criteria not met | Retry or report, then continue | +| Error | Resolution | +|-------|------------| +| spawn_agent failure | Fallback to CLI execution | +| wait() timeout | Use completed results, log partial status | +| Agent crash | Collect partial output, offer retry | +| CLI execution failure | Use fixed ID for resume | +| Circular dependency | Force remaining tasks with warning | +| Missing executionContext | Error: "No execution context found" | + +--- + +## Best Practices + +**Codex-Specific**: +- Pass role file path in MANDATORY FIRST STEPS (agent reads itself) +- Use batch `wait({ ids: [...] })` for parallel tasks +- Delay `close_agent` until all interactions complete +- Track `fixedCliId` for resume capability + +**General**: +- Task Grouping: Based on explicit depends_on only +- Execution: All independent tasks launch via single batch wait +- Progress: TodoWrite at batch level (⚡ parallel, → sequential) + +--- + +**Now execute the lite-execute workflow** diff --git a/.codex/prompts/lite-fix.md b/.codex/prompts/lite-fix.md new file mode 100644 index 00000000..12daaf5d --- /dev/null +++ b/.codex/prompts/lite-fix.md @@ -0,0 +1,670 @@ +--- +description: Lightweight bug diagnosis and fix workflow with optimized Codex subagent patterns (merged mode) +argument-hint: BUG="" [HOTFIX="true"] +--- + +# Workflow Lite-Fix Command (Codex Optimized Version) + +## Overview + +Intelligent lightweight bug fixing command with **optimized subagent orchestration**. Uses merged mode pattern for context preservation across diagnosis, clarification, and fix planning phases. + +**Core Optimizations:** +- **Context Preservation**: Primary agent retained across phases via `send_input()` +- **Merged Mode**: Diagnosis → Merge → Clarify → Plan in single agent context +- **Reduced Agent Cycles**: Minimize spawn/close overhead +- **Dual-Role Pattern**: Single agent handles both exploration and planning (Low/Medium) + +**Core capabilities:** +- Intelligent bug analysis with automatic severity detection +- Parallel code diagnosis via Codex subagents (spawn_agent + batch wait) +- **Merged clarification + fix planning** (send_input to retained agent) +- Adaptive fix planning based on severity +- Two-step confirmation: fix-plan display → user approval +- Outputs fix-plan.json file after user confirmation + +## Bug Description + +**Target bug**: $BUG +**Hotfix mode**: $HOTFIX + +## Execution Modes + +### Mode Selection Based on Severity + +| Severity | Mode | Pattern | Phases | +|----------|------|---------|--------| +| Low/Medium | 方案A (合并模式) | Single dual-role agent | 2-phase with send_input | +| High/Critical | 方案B (混合模式) | Multi-agent + primary merge | Parallel → Merge → Plan | + +## Execution Process + +``` +Phase 0: Setup & Severity Assessment + ├─ Parse input (description, error message, or .md file) + ├─ Create session folder + ├─ Intelligent severity pre-assessment (Low/Medium/High/Critical) + └─ Select execution mode (方案A or 方案B) + +========== 方案A: Low/Medium Severity (Merged Mode) ========== + +Phase 1A: Dual-Role Agent (Diagnosis + Planning) + ├─ spawn_agent with combined diagnosis + planning role + ├─ wait for initial diagnosis + └─ Agent retains context for next phase + +Phase 2A: Clarification + Fix Planning (send_input) + ├─ send_input: clarification answers + "generate fix plan" + ├─ wait for fix-plan.json generation + └─ close_agent (single cleanup) + +========== 方案B: High/Critical Severity (Mixed Mode) ========== + +Phase 1B: Parallel Multi-Angle Diagnosis + ├─ spawn_agent × N (primary = dual-role, others = explore-only) + ├─ wait({ ids: [...] }) for all diagnoses + └─ Collect all diagnosis results + +Phase 2B: Merge + Clarify (send_input to primary) + ├─ close_agent × (N-1) non-primary agents + ├─ send_input to primary: other agents' diagnoses + "merge findings" + └─ wait for merged analysis + clarification needs + +Phase 3B: Fix Planning (send_input to primary) + ├─ send_input: clarification answers + "generate fix plan" + ├─ wait for fix-plan.json generation + └─ close_agent (primary cleanup) + +========== Common Phases ========== + +Phase 4: Confirmation + ├─ Display fix-plan summary (tasks, severity, risk level) + ├─ Output confirmation request + └─ STOP and wait for user approval + +Phase 5: Output + └─ Confirm fix-plan.json written to session folder +``` + +## Implementation + +### Phase 0: Setup & Severity Assessment + +**Session Setup** (MANDATORY): +```javascript +// Helper: Get UTC+8 (China Standard Time) ISO string +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const bugSlug = "$BUG".toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 + +const sessionId = `${bugSlug}-${dateStr}` +const sessionFolder = `.workflow/.lite-fix/${sessionId}` + +// Create session folder +mkdir -p ${sessionFolder} +``` + +**Hotfix Mode Check**: +```javascript +const hotfixMode = "$HOTFIX" === "true" + +if (hotfixMode) { + // Skip diagnosis, go directly to minimal fix planning + proceed_to_direct_fix() +} +``` + +**Severity Assessment**: +```javascript +// Analyze bug severity based on symptoms, scope, urgency, impact +const severity = analyzeBugSeverity("$BUG") +// Returns: 'Low' | 'Medium' | 'High' | 'Critical' + +// Mode selection +const executionMode = (severity === 'Low' || severity === 'Medium') ? 'A' : 'B' + +console.log(` +## Bug Analysis + +**Severity**: ${severity} +**Execution Mode**: 方案${executionMode} (${executionMode === 'A' ? '合并模式 - Single Agent' : '混合模式 - Multi-Agent'}) +`) +``` + +**Angle Selection** (for diagnosis): +```javascript +const DIAGNOSIS_ANGLE_PRESETS = { + runtime_error: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], + performance: ['performance', 'bottlenecks', 'caching', 'data-access'], + security: ['security', 'auth-patterns', 'dataflow', 'validation'], + data_corruption: ['data-integrity', 'state-management', 'transactions', 'validation'], + ui_bug: ['state-management', 'event-handling', 'rendering', 'data-binding'], + integration: ['api-contracts', 'error-handling', 'timeouts', 'fallbacks'] +} + +function selectDiagnosisAngles(bugDescription, count) { + const text = bugDescription.toLowerCase() + let preset = 'runtime_error' + + if (/slow|timeout|performance|lag|hang/.test(text)) preset = 'performance' + else if (/security|auth|permission|access|token/.test(text)) preset = 'security' + else if (/corrupt|data|lost|missing|inconsistent/.test(text)) preset = 'data_corruption' + else if (/ui|display|render|style|click|button/.test(text)) preset = 'ui_bug' + else if (/api|integration|connect|request|response/.test(text)) preset = 'integration' + + return DIAGNOSIS_ANGLE_PRESETS[preset].slice(0, count) +} + +const angleCount = severity === 'Critical' ? 4 : (severity === 'High' ? 3 : (severity === 'Medium' ? 2 : 1)) +const selectedAngles = selectDiagnosisAngles("$BUG", angleCount) +``` + +--- + +## 方案A: Low/Medium Severity (合并模式) + +**Pattern**: Single dual-role agent handles diagnosis + clarification + fix planning with context preserved via `send_input()`. + +### Phase 1A: Dual-Role Agent (Diagnosis + Planning) + +```javascript +// ==================== MERGED MODE ==================== + +// Step 1: Spawn single dual-role agent (角色文件由 agent 自己读取) +const dualAgent = spawn_agent({ + message: ` +## PHASE 1: DIAGNOSIS + +### Task Objective +Execute comprehensive diagnosis for bug root cause analysis. You have combined diagnosis + planning capabilities. + +### Bug Description +$BUG + +### Diagnosis Angles (analyze all) +${selectedAngles.map((angle, i) => `${i + 1}. ${angle}`).join('\n')} + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read diagnosis role**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +2. **Read planning role**: ~/.codex/agents/cli-lite-planning-agent.md (for Phase 2) +3. Run: ccw tool exec get_modules_by_depth '{}' (project structure) +4. Run: rg -l "{error_keyword_from_bug}" --type ts (locate relevant files) +5. Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json +6. Read: .workflow/project-tech.json +7. Read: .workflow/project-guidelines.json + +### Diagnosis Tasks +For each angle (${selectedAngles.join(', ')}): +1. **Error Tracing**: rg for error messages, stack traces +2. **Root Cause Analysis**: Identify code paths, edge cases +3. **Affected Files**: List with relevance scores + +### Expected Output +1. Write diagnosis to: ${sessionFolder}/diagnosis-merged.json +2. List any clarification needs (questions + options) +3. **DO NOT proceed to fix planning yet** - wait for Phase 2 input + +### Clarification Format (if needed) +If you need clarification, output: +\`\`\`json +{ + "clarification_needs": [ + { + "question": "...", + "context": "...", + "options": ["Option 1", "Option 2", "Option 3"], + "recommended": 0 + } + ] +} +\`\`\` + +### Deliverables for Phase 1 +- Write: ${sessionFolder}/diagnosis-merged.json +- Return: Diagnosis summary + clarification needs (if any) +` +}) + +// Step 3: Wait for diagnosis +const diagnosisResult = wait({ + ids: [dualAgent], + timeout_ms: 600000 // 10 minutes +}) + +// Extract clarification needs from result +const clarificationNeeds = extractClarificationNeeds(diagnosisResult.status[dualAgent].completed) +``` + +**Handle Clarification (if needed)**: +```javascript +if (clarificationNeeds.length > 0) { + console.log(` +## Clarification Needed + +${clarificationNeeds.map((need, index) => ` +### Question ${index + 1} + +**${need.question}** + +Context: ${need.context} + +Options: +${need.options.map((opt, i) => ` ${i + 1}. ${opt}${need.recommended === i ? ' ★ (Recommended)' : ''}`).join('\n')} +`).join('\n')} + +--- + +**Please reply with your choices** (e.g., "Q1: 2, Q2: 1") to continue. + +**WAITING FOR USER INPUT...** +`) + // STOP - Wait for user reply + return +} +``` + +### Phase 2A: Clarification + Fix Planning (send_input) + +```javascript +// After user replies with clarification answers... +const clarificationAnswers = /* user's answers */ + +// Step 4: send_input for fix planning (CONTEXT PRESERVED) +send_input({ + id: dualAgent, + message: ` +## PHASE 2: FIX PLANNING + +### User Clarifications +${clarificationAnswers || "No clarifications needed"} + +### Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json + +### Generate Fix Plan +Based on your diagnosis, generate a comprehensive fix plan: + +1. Read your diagnosis file: ${sessionFolder}/diagnosis-merged.json +2. Synthesize root cause from all analyzed angles +3. Generate fix-plan.json with: + - summary: 2-3 sentence overview + - root_cause: Consolidated from diagnosis + - strategy: "immediate_patch" | "comprehensive_fix" | "refactor" + - tasks: 1-3 structured fix tasks (group by fix area) + - severity: ${severity} + - risk_level: based on analysis + +### Task Grouping Rules +1. Group by fix area (all changes for one fix = one task) +2. Avoid file-per-task pattern +3. Each task = 10-30 minutes of work +4. Prefer parallel tasks (minimal dependencies) + +### Deliverables +- Write: ${sessionFolder}/fix-plan.json +- Return: Brief fix plan summary +` +}) + +// Step 5: Wait for fix planning +const planResult = wait({ + ids: [dualAgent], + timeout_ms: 600000 // 10 minutes +}) + +// Step 6: Cleanup (single close) +close_agent({ id: dualAgent }) +``` + +--- + +## 方案B: High/Critical Severity (混合模式) + +**Pattern**: Parallel multi-angle diagnosis → keep primary agent → send_input for merge + clarify + plan. + +### Phase 1B: Parallel Multi-Angle Diagnosis + +```javascript +// ==================== MIXED MODE ==================== + +// Step 1: Spawn parallel diagnosis agents (角色文件由 agent 自己读取) +// primary = dual-role (diagnosis + planning) +const diagnosisAgents = selectedAngles.map((angle, index) => { + const isPrimary = index === 0 + + return spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### Agent Type +${isPrimary ? '**PRIMARY** (Dual-role: Diagnosis + Planning)' : `Secondary (Diagnosis only - angle: ${angle})`} + +### Task Objective +Execute **${angle}** diagnosis for bug root cause analysis. + +### Bug Description +$BUG + +### Diagnosis Angle +${angle} + +### Output File +${sessionFolder}/diagnosis-${angle}.json + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read diagnosis role**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +${isPrimary ? '2. **Read planning role**: ~/.codex/agents/cli-lite-planning-agent.md (for Phase 2 & 3)\n3.' : '2.'} Run: ccw tool exec get_modules_by_depth '{}' +${isPrimary ? '4.' : '3.'} Run: rg -l "{error_keyword_from_bug}" --type ts +${isPrimary ? '5.' : '4.'} Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json +${isPrimary ? '6.' : '5.'} Read: .workflow/project-tech.json +${isPrimary ? '7.' : '6.'} Read: .workflow/project-guidelines.json + +### Diagnosis Strategy (${angle} focus) +1. **Error Tracing**: rg for error messages, stack traces +2. **Root Cause Analysis**: Code paths, edge cases for ${angle} +3. **Affected Files**: List with ${angle} relevance + +### Expected Output +Write: ${sessionFolder}/diagnosis-${angle}.json +Return: 2-3 sentence summary of ${angle} findings + +${isPrimary ? ` +### PRIMARY AGENT NOTE +You will receive follow-up tasks via send_input: +- Phase 2: Merge other agents' diagnoses +- Phase 3: Generate fix plan +Keep your context ready for continuation. +` : ''} +` + }) +}) + +// Step 3: Batch wait for ALL diagnosis agents +const diagnosisResults = wait({ + ids: diagnosisAgents, + timeout_ms: 600000 // 10 minutes +}) + +// Step 4: Collect all diagnosis results +const allDiagnoses = selectedAngles.map((angle, index) => ({ + angle, + agentId: diagnosisAgents[index], + result: diagnosisResults.status[diagnosisAgents[index]].completed, + file: `${sessionFolder}/diagnosis-${angle}.json` +})) + +console.log(` +## Phase 1B Complete + +Diagnoses collected: +${allDiagnoses.map(d => `- ${d.angle}: ${d.file}`).join('\n')} +`) +``` + +### Phase 2B: Merge + Clarify (send_input to primary) + +```javascript +// Step 5: Close non-primary agents, keep primary +const primaryAgent = diagnosisAgents[0] +const primaryAngle = selectedAngles[0] + +diagnosisAgents.slice(1).forEach(id => close_agent({ id })) + +console.log(` +## Phase 2B: Merge Analysis + +Closed ${diagnosisAgents.length - 1} secondary agents. +Sending merge task to primary agent (${primaryAngle})... +`) + +// Step 6: send_input for merge + clarification +send_input({ + id: primaryAgent, + message: ` +## PHASE 2: MERGE + CLARIFY + +### Task +Merge all diagnosis findings and identify clarification needs. + +### Your Diagnosis (${primaryAngle}) +Already in your context from Phase 1. + +### Other Agents' Diagnoses to Merge +${allDiagnoses.slice(1).map(d => ` +#### Diagnosis: ${d.angle} +File: ${d.file} +Summary: ${d.result} +`).join('\n')} + +### Merge Instructions +1. Read all diagnosis files: +${allDiagnoses.map(d => ` - ${d.file}`).join('\n')} + +2. Synthesize findings: + - Identify common root causes across angles + - Note conflicting findings + - Rank confidence levels + +3. Write merged analysis: ${sessionFolder}/diagnosis-merged.json + +4. List clarification needs (if any): + - Questions that need user input + - Options with recommendations + +### Expected Output +- Write: ${sessionFolder}/diagnosis-merged.json +- Return: Merged findings summary + clarification needs +` +}) + +// Step 7: Wait for merge +const mergeResult = wait({ + ids: [primaryAgent], + timeout_ms: 300000 // 5 minutes +}) + +// Extract clarification needs +const clarificationNeeds = extractClarificationNeeds(mergeResult.status[primaryAgent].completed) +``` + +**Handle Clarification (if needed)**: +```javascript +if (clarificationNeeds.length > 0) { + console.log(` +## Clarification Needed + +${clarificationNeeds.map((need, index) => ` +### Question ${index + 1} + +**${need.question}** + +Context: ${need.context} + +Options: +${need.options.map((opt, i) => ` ${i + 1}. ${opt}${need.recommended === i ? ' ★ (Recommended)' : ''}`).join('\n')} +`).join('\n')} + +--- + +**Please reply with your choices** to continue. + +**WAITING FOR USER INPUT...** +`) + return +} +``` + +### Phase 3B: Fix Planning (send_input to primary) + +```javascript +// After user replies with clarification answers... +const clarificationAnswers = /* user's answers */ + +// Step 8: send_input for fix planning (CONTEXT PRESERVED) +send_input({ + id: primaryAgent, + message: ` +## PHASE 3: FIX PLANNING + +### User Clarifications +${clarificationAnswers || "No clarifications needed"} + +### Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json + +### Generate Fix Plan +Based on your merged diagnosis, generate a comprehensive fix plan: + +1. Read merged diagnosis: ${sessionFolder}/diagnosis-merged.json +2. Consider all ${selectedAngles.length} diagnosis angles +3. Generate fix-plan.json with: + - summary: 2-3 sentence overview + - root_cause: Consolidated from all diagnoses + - strategy: "immediate_patch" | "comprehensive_fix" | "refactor" + - tasks: 1-5 structured fix tasks + - severity: ${severity} + - risk_level: based on analysis + +### High/Critical Complexity Fields (REQUIRED) +For each task: +- rationale: Why this fix approach +- verification: How to verify success +- risks: Potential issues with fix + +### Task Grouping Rules +1. Group by fix area (all changes for one fix = one task) +2. Avoid file-per-task pattern +3. Each task = 10-45 minutes of work +4. True dependencies only (prefer parallel) + +### Deliverables +- Write: ${sessionFolder}/fix-plan.json +- Return: Brief fix plan summary +` +}) + +// Step 9: Wait for fix planning +const planResult = wait({ + ids: [primaryAgent], + timeout_ms: 600000 // 10 minutes +}) + +// Step 10: Cleanup primary agent +close_agent({ id: primaryAgent }) +``` + +--- + +## Common Phases (Both Modes) + +### Phase 4: Confirmation + +```javascript +const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`)) + +console.log(` +## Fix Plan + +**Summary**: ${fixPlan.summary} +**Root Cause**: ${fixPlan.root_cause} +**Strategy**: ${fixPlan.strategy} + +**Tasks** (${fixPlan.tasks.length}): +${fixPlan.tasks.map((t, i) => ` +### Task ${i+1}: ${t.title} +- **Description**: ${t.description} +- **Scope**: ${t.scope} +- **Action**: ${t.action} +- **Complexity**: ${t.complexity} +- **Dependencies**: ${t.depends_on?.join(', ') || 'None'} +`).join('\n')} + +**Severity**: ${fixPlan.severity} +**Risk Level**: ${fixPlan.risk_level} +**Estimated Time**: ${fixPlan.estimated_time} + +--- + +## Confirmation Required + +Please review the fix plan above and reply with: + +- **"Allow"** - Proceed with this fix plan +- **"Modify"** - Describe what changes you want +- **"Cancel"** - Abort the workflow + +**WAITING FOR USER CONFIRMATION...** +`) + +return +``` + +### Phase 5: Output + +```javascript +// After User Confirms "Allow" +console.log(` +## Fix Plan Output Complete + +**Fix plan file**: ${sessionFolder}/fix-plan.json +**Session folder**: ${sessionFolder} + +**Contents**: +- diagnosis-merged.json (or diagnosis-{angle}.json files) +- fix-plan.json + +--- + +You can now use this fix plan with your preferred execution method. +`) +``` + +--- + +## Mode Comparison + +| Aspect | 方案A (合并模式) | 方案B (混合模式) | +|--------|-----------------|-----------------| +| **Severity** | Low/Medium | High/Critical | +| **Agents** | 1 (dual-role) | N (parallel) → 1 (primary kept) | +| **Phases** | 2 (diagnosis → plan) | 3 (diagnose → merge → plan) | +| **Context** | Fully preserved | Merged via send_input | +| **Overhead** | Minimal | Higher (parallel coordination) | +| **Coverage** | Single comprehensive | Multi-angle deep dive | + +## Optimization Benefits + +| Aspect | Before (Original) | After (Optimized) | +|--------|-------------------|-------------------| +| **Agent Cycles** | spawn × N → close all → spawn new | spawn → send_input → close once | +| **Context Loss** | Diagnosis context lost before planning | Context preserved via send_input | +| **Merge Process** | None (separate planning agent) | Explicit merge phase (方案B) | +| **Low/Medium** | Same as High/Critical | Simplified single-agent path | + +## Session Folder Structure + +``` +.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/ +├── diagnosis-merged.json # 方案A or merged 方案B +├── diagnosis-{angle1}.json # 方案B only +├── diagnosis-{angle2}.json # 方案B only +├── diagnosis-{angle3}.json # 方案B only (if applicable) +├── diagnosis-{angle4}.json # 方案B only (if applicable) +└── fix-plan.json # Fix plan (after confirmation) +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| spawn_agent failure | Fallback to direct diagnosis | +| wait() timeout | Use completed results, continue | +| send_input failure | Re-spawn agent with context summary | +| Clarification timeout | Use diagnosis findings as-is | +| Confirmation timeout | Save context, display resume instructions | +| Root cause unclear | Extend diagnosis or escalate to 方案B | + +--- + +**Now execute the lite-fix workflow for bug**: $BUG diff --git a/.codex/prompts/lite-plan-a.md b/.codex/prompts/lite-plan-a.md new file mode 100644 index 00000000..f42889b3 --- /dev/null +++ b/.codex/prompts/lite-plan-a.md @@ -0,0 +1,349 @@ +--- +description: Lightweight interactive planning workflow with single-agent merged mode for explore → clarify → plan full flow +argument-hint: TASK="" +--- + +# 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 + +## 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 | + +## Plan-A vs Plan-B Comparison + +| Dimension | Plan-A (This Document) | Plan-B | +|-----------|----------------------|--------| +| Agent count | 1 | N (parallel exploration) + 1 (main agent) | +| Suitable complexity | Low/Medium | High | +| Exploration depth | Single angle, deep | Multi-angle parallel | +| Context | Fully coherent | Requires merge transfer | +| Recommended scenario | Clear task, single module | Complex task, cross-module | + +--- + +**Execute task**: $TASK diff --git a/.codex/prompts/lite-plan-b.md b/.codex/prompts/lite-plan-b.md new file mode 100644 index 00000000..1007000f --- /dev/null +++ b/.codex/prompts/lite-plan-b.md @@ -0,0 +1,497 @@ +--- +description: Lightweight interactive planning workflow with hybrid mode - multi-agent parallel exploration + primary agent merge/clarify/plan +argument-hint: TASK="" +--- + +# Workflow Lite-Plan-B (Hybrid Mode) + +## Overview + +Hybrid mode for complex planning tasks. Multiple agents explore in parallel from different angles, then the primary agent merges findings, handles clarification, and generates the implementation plan while retaining its exploration context. + +**Core capabilities:** +- **Parallel multi-angle exploration** via multiple subagents +- **Primary agent reuse** for merge, clarification, and planning (context preserved) +- Intelligent deduplication and conflict resolution during merge +- Best for High complexity tasks requiring cross-module analysis + +## Applicable Scenarios + +- **High complexity tasks** +- Multi-angle parallel exploration required +- Cross-module or architecture-level changes +- Complex dependencies requiring multiple perspectives + +## Core Advantages + +| Metric | Traditional Separated Mode | Plan-B Hybrid Mode | +|--------|---------------------------|-------------------| +| Agent creation count | N + 1 (fully independent) | **N → 1** (reuse primary agent) | +| Context transfer | Full serialization | **Primary agent retained + incremental merge** | +| Merge quality | Simple concatenation | **Intelligent agent merge** | +| Planning coherence | Low (new agent) | **High (reuses exploration agent)** | + +## Task Description + +**Target task**: $TASK + +## Execution Process + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Phase 1: Parallel Exploration │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │Agent 0 │ │Agent 1 │ │Agent 2 │ │Agent 3 │ │ +│ │(primary)│ │(explore)│ │(explore)│ │(explore)│ │ +│ │angle-0 │ │angle-1 │ │angle-2 │ │angle-3 │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ +│ │ │ │ │ │ +│ └───────────┴───────────┴───────────┘ │ +│ ↓ │ +│ wait({ ids: all }) │ +│ ↓ │ +├─────────────────────────────────────────────────────────────────┤ +│ Phase 2: Merge + Clarify │ +│ ↓ │ +│ close(Agent 1, 2, 3) ← close non-primary agents │ +│ ↓ │ +│ send_input(Agent 0, { │ +│ other_explorations: [Agent 1,2,3 results], │ +│ task: "MERGE + CLARIFY" │ +│ }) │ +│ ↓ │ +│ wait() → get merged results + clarification questions │ +│ ↓ │ +│ [Collect user answers] │ +│ ↓ │ +├─────────────────────────────────────────────────────────────────┤ +│ Phase 3: Planning │ +│ ↓ │ +│ send_input(Agent 0, { │ +│ clarification_answers: [...], │ +│ task: "GENERATE PLAN" │ +│ }) │ +│ ↓ │ +│ wait() → get plan.json │ +│ ↓ │ +│ close(Agent 0) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## 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 & Multi-Angle Selection + +```javascript +const complexity = analyzeTaskComplexity("$TASK") +// Plan-B is suitable for High complexity + +const ANGLE_PRESETS = { + architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'], + security: ['security', 'auth-patterns', 'dataflow', 'validation'], + performance: ['performance', 'bottlenecks', 'caching', 'data-access'], + bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], + feature: ['patterns', 'integration-points', 'testing', 'dependencies'] +} + +// Plan-B selects 3-4 angles for parallel exploration +const selectedAngles = selectAngles("$TASK", 4) // e.g., ['architecture', 'patterns', 'testing', 'dependencies'] +``` + +--- + +### Phase 1: Parallel Exploration (Primary Agent Has Planning Capability) + +```javascript +// ==================== PLAN-B: HYBRID MODE ==================== + +// Step 1: Create parallel exploration agents (role files read by agents themselves) +// First agent is primary, has merge + planning capability +const explorationAgents = selectedAngles.map((angle, index) => { + const isPrimary = index === 0 + + return spawn_agent({ + message: ` +## TASK ASSIGNMENT (Phase 1: Exploration) + +### Task Description +${task_description} + +### Your Exploration Angle +**Angle**: ${angle} +**Index**: ${index + 1} of ${selectedAngles.length} +**Output File**: ${sessionFolder}/exploration-${angle}.json +${isPrimary ? '\n**Note**: You are the PRIMARY agent. After Phase 1, you will receive other agents\' results for merging and planning.' : ''} + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read explorer role**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +${isPrimary ? '2. **Read planner role**: ~/.codex/agents/cli-lite-planning-agent.md (for Phase 2 & 3)\n3.' : '2.'} Run: ccw tool exec get_modules_by_depth '{}' +${isPrimary ? '4.' : '3.'} Run: rg -l "{keyword}" --type ts +${isPrimary ? '5.' : '4.'} Read: .workflow/project-tech.json +${isPrimary ? '6.' : '5.'} Read: .workflow/project-guidelines.json + +### Exploration Focus: ${angle} + +**Structural Analysis**: +- Identify modules and files related to ${angle} +- Map imports/exports and dependencies +- Locate entry points and integration surfaces + +**Semantic Analysis**: +- How does existing code handle ${angle} concerns? +- What patterns are established for ${angle}? +- Where would new code integrate from ${angle} viewpoint? + +### Output Format + +Write to ${sessionFolder}/exploration-${angle}.json: +\`\`\`json +{ + "angle": "${angle}", + "project_structure": [...], + "relevant_files": [ + {"path": "src/file.ts", "relevance": 0.9, "rationale": "..."} + ], + "patterns": [...], + "dependencies": [...], + "integration_points": [ + {"location": "file:line", "description": "..."} + ], + "constraints": [...], + "clarification_needs": [ + {"question": "...", "options": ["A", "B"], "recommended": 0, "context": "..."} + ], + "_metadata": { + "exploration_angle": "${angle}", + "exploration_index": ${index + 1}, + "timestamp": "..." + } +} +\`\`\` + +### Return +2-3 sentence summary of ${angle} findings +` + }) +}) + +// Step 2: Batch wait for ALL explorations to complete (KEY ADVANTAGE of Codex) +const exploreResults = wait({ + ids: explorationAgents, + timeout_ms: 600000 // 10 minutes +}) + +// Step 3: Collect all exploration results +const allExplorations = selectedAngles.map((angle, index) => ({ + angle: angle, + agentId: explorationAgents[index], + result: exploreResults.status[explorationAgents[index]].completed, + file: `${sessionFolder}/exploration-${angle}.json` +})) + +console.log(` +## Phase 1 Complete + +Explorations completed: +${allExplorations.map(e => `- ${e.angle}: ${e.result.substring(0, 100)}...`).join('\n')} +`) +``` + +--- + +### Phase 2: Merge + Clarify (Reuse Primary Agent) + +```javascript +// Step 4: Close non-primary agents, keep primary agent (index=0) +const primaryAgent = explorationAgents[0] +const primaryAngle = selectedAngles[0] + +explorationAgents.slice(1).forEach(id => close_agent({ id })) + +// Step 5: Send merge task to primary agent +send_input({ + id: primaryAgent, + message: ` +## PHASE 2: MERGE + CLARIFY + +You are now in **Merger** role. Combine your ${primaryAngle} findings with other explorations below. + +### Other Explorations to Merge + +${allExplorations.slice(1).map(e => ` +#### ${e.angle} Exploration +**File**: ${e.file} +**Summary**: ${e.result} + +Read the full exploration: Read("${e.file}") +`).join('\n')} + +### Merge Instructions + +1. **Read All Exploration Files** + ${allExplorations.map(e => `- Read("${e.file}")`).join('\n ')} + +2. **Consolidate Findings** + - **relevant_files**: Deduplicate, keep highest relevance score for each file + - **patterns**: Merge unique patterns, note which angle discovered each + - **integration_points**: Combine all, group by module + - **constraints**: Merge and categorize (hard vs soft constraints) + - **clarification_needs**: Deduplicate similar questions + +3. **Write Merged Exploration** + Write to: ${sessionFolder}/exploration-merged.json + +4. **Output Clarification Questions** + +Format: +\`\`\` +MERGED_EXPLORATION_COMPLETE + +Files consolidated: [count] +Patterns identified: [count] +Integration points: [count] + +CLARIFICATION_NEEDED: +Q1: [merged question] | Options: [A, B, C] | Recommended: [X] | Source: [angles] +Q2: [merged question] | Options: [A, B] | Recommended: [Y] | Source: [angles] +\`\`\` + +If no clarification needed: +\`\`\` +CLARIFICATION_NEEDED: NONE + +Ready for Phase 3 (Planning). Send clarification answers or "PROCEED_TO_PLANNING". +\`\`\` +` +}) + +// Step 6: Wait for merge result +const mergeResult = wait({ ids: [primaryAgent], timeout_ms: 300000 }) +const mergeOutput = mergeResult.status[primaryAgent].completed + +// Step 7: Handle clarification +let clarificationAnswers = null + +if (mergeOutput.includes('CLARIFICATION_NEEDED:') && !mergeOutput.includes('CLARIFICATION_NEEDED: NONE')) { + const questions = parseClarificationQuestions(mergeOutput) + + console.log(` +## Clarification Needed (Merged from ${selectedAngles.length} angles) + +${questions.map((q, i) => ` +### Q${i+1}: ${q.question} +Options: ${q.options.join(', ')} +Recommended: ${q.recommended} +Source angles: ${q.source} +`).join('\n')} + +**Please provide your answers...** +`) + + clarificationAnswers = collectUserAnswers(questions) +} +``` + +--- + +### Phase 3: Planning (Continue Reusing Primary Agent) + +```javascript +// Step 8: Send planning task +send_input({ + id: primaryAgent, + message: ` +## PHASE 3: GENERATE PLAN + +You are now in **Planner** role. Generate implementation plan based on merged explorations. + +${clarificationAnswers ? ` +### Clarification Answers +${clarificationAnswers.map(a => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')} +` : '### No clarification needed'} + +### Planning Instructions + +1. **Read Schema** + Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json + +2. **Read Merged Exploration** + Read: ${sessionFolder}/exploration-merged.json + +3. **Generate Plan** + Based on consolidated findings from ${selectedAngles.length} exploration angles: + - ${selectedAngles.join('\n - ')} + +4. **Plan Requirements** + - Summary: 2-3 sentence overview + - Approach: High-level strategy referencing multiple angles + - Tasks: 2-7 tasks grouped by feature (NOT by file) + - Each task: id, title, scope, action, description, modification_points, implementation, acceptance, depends_on + - Reference exploration angles in task descriptions + +5. **Task Grouping Rules** + - Group by feature: All changes for one feature = one task (even if spanning angles) + - Substantial tasks: 15-60 minutes each + - True dependencies only + - Prefer parallel execution + +6. **Write Output** + Write: ${sessionFolder}/plan.json + +### Metadata +Include in _metadata: +- exploration_angles: ${JSON.stringify(selectedAngles)} +- planning_mode: "merged-multi-angle" +- source_explorations: ${allExplorations.length} + +### Return +Brief completion summary +` +}) + +// Step 9: Wait for planning to complete +const planResult = wait({ ids: [primaryAgent], timeout_ms: 600000 }) + +// Step 10: Final cleanup +close_agent({ id: primaryAgent }) +``` + +--- + +### Phase 4: Confirmation + +```javascript +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +console.log(` +## Implementation Plan (Multi-Angle: ${selectedAngles.join(', ')}) + +**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} +**Exploration Angles**: ${plan._metadata.exploration_angles.join(', ')} + +--- + +## Confirmation Required + +Please review the plan above and reply with one of the following: + +- **"Allow"** - Confirm and finalize plan.json +- **"Modify"** - Describe what changes you want to make +- **"Cancel"** - Abort the planning workflow + +**WAITING FOR USER CONFIRMATION...** +`) +``` + +--- + +## Codex vs Claude Comparison (for hybrid mode) + +| Aspect | Claude Code Task | Codex Subagent (Plan-B) | +|--------|------------------|------------------------| +| **Creation** | `Task({ subagent_type, prompt })` | `spawn_agent({ message: role + task })` | +| **Role Loading** | Auto via `subagent_type` | Manual: Agent reads `~/.codex/agents/*.md` | +| **Parallel Wait** | Multiple `Task()` calls | **Batch `wait({ ids: [...] })`** | +| **Result Retrieval** | Sync return or `TaskOutput` | `wait({ ids }).status[id].completed` | +| **Agent Reuse** | `resume` parameter | **`send_input` to continue** | +| **Cleanup** | Automatic | **Explicit `close_agent({ id })`** | + +**Plan-B Advantages**: +- True parallel exploration with batch `wait` +- Primary agent retains context across all phases +- Fine-grained lifecycle control + +--- + +## Agent Lifecycle Comparison + +``` +Traditional Mode: + Agent 1 ──────● close + Agent 2 ──────● close + Agent 3 ──────● close + Agent 4 ──────● close + Planning Agent ────────────● close + +Plan-B Hybrid Mode: + Agent 0 ─────────────────────────────────● close (reused until end) + Agent 1 ──────● close + Agent 2 ──────● close + Agent 3 ──────● close + ↑ ↑ ↑ + Phase1 Phase2 Phase3 + (parallel) (merge+clarify) (planning) +``` + +--- + +## Session Folder Structure + +``` +.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/ +├── exploration-architecture.json # Angle 1 (primary agent) +├── exploration-patterns.json # Angle 2 +├── exploration-testing.json # Angle 3 +├── exploration-dependencies.json # Angle 4 +├── exploration-merged.json # Merged by primary agent +└── plan.json # Final plan +``` + +## Workflow States + +| State | Action | Next | +|-------|--------|------| +| Phase 1 Complete | All explorations done | → Phase 2 (Merge) | +| Phase 2 Output | Merged + questions | → Wait for user reply | +| User Replied | Answers received | → send_input to Phase 3 | +| Phase 3 Output | Plan generated | → Phase 4 (Confirmation) | +| User: "Allow" | Confirmed | → Output complete | +| User: "Modify" | Changes requested | → send_input with revisions | +| User: "Cancel" | Aborted | → close all agents, end workflow | + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Partial exploration timeout | Use completed results, note missing angles in merge | +| Primary agent unexpectedly closed | Re-spawn, paste existing exploration results in message | +| Merge phase timeout | send_input to request current merge progress | +| Planning phase timeout | send_input requesting partial plan output | + +## Plan-A vs Plan-B Comparison + +| Dimension | Plan-A | Plan-B (This Document) | +|-----------|--------|----------------------| +| Agent count | 1 | N → 1 (parallel then reuse) | +| Suitable complexity | Low/Medium | **High** | +| Exploration depth | Single angle | **Multi-angle parallel** | +| Context | Fully coherent | Primary agent coherent + incremental merge | +| Recommended scenario | Clear task | **Complex task, cross-module** | + +--- + +**Execute task**: $TASK diff --git a/.codex/prompts/lite-plan.md b/.codex/prompts/lite-plan-c.md similarity index 55% rename from .codex/prompts/lite-plan.md rename to .codex/prompts/lite-plan-c.md index c6894a61..20a3a651 100644 --- a/.codex/prompts/lite-plan.md +++ b/.codex/prompts/lite-plan-c.md @@ -1,19 +1,19 @@ --- -description: Lightweight interactive planning workflow with direct exploration, outputs plan.json after user confirmation +description: Lightweight interactive planning workflow with Codex subagent orchestration, outputs plan.json after user confirmation argument-hint: TASK="" [EXPLORE="true"] --- -# Workflow Lite-Plan Command +# Workflow Lite-Plan Command (Codex Subagent Version) ## Overview -Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and outputs plan.json for subsequent execution. +Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Uses Codex subagent API for parallel exploration and planning phases. **Core capabilities:** - Intelligent task analysis with automatic exploration detection -- Direct code exploration (grep, find, file reading) when codebase understanding needed +- **Parallel code exploration via Codex subagents** (spawn_agent + batch wait) - Interactive clarification after exploration to gather missing information -- Adaptive planning strategy based on complexity +- Adaptive planning: Low complexity → Direct; Medium/High → cli-lite-planning-agent subagent - Two-step confirmation: plan display → user approval - Outputs plan.json file after user confirmation @@ -25,22 +25,23 @@ Intelligent lightweight planning command with dynamic workflow adaptation based ## Execution Process ``` -Phase 1: Task Analysis & Exploration +Phase 1: Task Analysis & Exploration (Subagent Orchestration) ├─ Parse input (description or .md file) ├─ Intelligent complexity assessment (Low/Medium/High) ├─ Exploration decision (auto-detect or EXPLORE="true") └─ Decision: - ├─ needsExploration=true → Direct exploration using grep/find/read + ├─ needsExploration=true → Spawn parallel cli-explore-agent subagents └─ needsExploration=false → Skip to Phase 2/3 Phase 2: Clarification (optional) - ├─ Aggregate clarification needs from exploration + ├─ Aggregate clarification needs from exploration results ├─ Output questions to user └─ STOP and wait for user reply Phase 3: Planning (NO CODE EXECUTION - planning only) - └─ Generate plan.json following schema - └─ MUST proceed to Phase 4 + └─ Decision (based on complexity): + ├─ Low → Direct planning following schema + └─ Medium/High → Spawn cli-lite-planning-agent subagent → plan.json Phase 4: Confirmation ├─ Display plan summary (tasks, complexity, estimated time) @@ -53,7 +54,7 @@ Phase 5: Output ## Implementation -### Phase 1: Intelligent Direct Exploration +### Phase 1: Intelligent Multi-Angle Exploration (Subagent Orchestration) **Session Setup** (MANDATORY - follow exactly): ```javascript @@ -86,6 +87,8 @@ if (!needsExploration) { } ``` +**Context Protection**: File reading >=50k chars → force `needsExploration=true` + **Complexity Assessment** (Intelligent Analysis): ```javascript // Analyzes task complexity based on: @@ -96,9 +99,6 @@ if (!needsExploration) { const complexity = analyzeTaskComplexity("$TASK") // Returns: 'Low' | 'Medium' | 'High' -// Low: Single file, isolated change, minimal risk -// Medium: Multiple files, some dependencies, moderate risk -// High: Cross-module, architectural, high risk // Angle assignment based on task type const ANGLE_PRESETS = { @@ -129,58 +129,115 @@ console.log(` Task Complexity: ${complexity} Selected Angles: ${selectedAngles.join(', ')} -Starting direct exploration... +Launching ${selectedAngles.length} parallel subagent explorations... `) ``` -**Direct Exploration** (No Agent - Use grep/find/read directly): +**Launch Parallel Exploration Subagents** (Codex Pattern): ```javascript -// For each selected angle, perform direct exploration +// ==================== CODEX SUBAGENT PATTERN ==================== -selectedAngles.forEach((angle, index) => { - console.log(`\n### Exploring: ${angle} (${index + 1}/${selectedAngles.length})`) +// Step 1: Spawn parallel exploration subagents (角色文件由 agent 自己读取) +const explorationAgents = selectedAngles.map((angle, index) => { + return spawn_agent({ + message: ` +## TASK ASSIGNMENT - // Step 1: Structural Scan - // - Find relevant files using grep/rg - // - Analyze directory structure - // - Identify modules related to the angle +### Task Objective +Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints. - // Example commands: - // rg -l "keyword_from_task" --type ts - // find . -name "*.ts" -path "*auth*" - // tree -L 3 src/ +### Assigned Context +- **Exploration Angle**: ${angle} +- **Task Description**: $TASK +- **Exploration Index**: ${index + 1} of ${selectedAngles.length} +- **Output File**: ${sessionFolder}/exploration-${angle}.json - // Step 2: Content Analysis - // - Read key files identified - // - Analyze patterns and conventions - // - Identify integration points +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +2. Run: ccw tool exec get_modules_by_depth '{}' (project structure) +3. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files) +4. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference) +5. Read: .workflow/project-tech.json (technology stack and architecture context) +6. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) - // Step 3: Document Findings - const explorationResult = { - angle: angle, - project_structure: [], // Modules/architecture relevant to angle - relevant_files: [], // Files affected from angle perspective - patterns: [], // Angle-related patterns to follow - dependencies: [], // Dependencies relevant to angle - integration_points: [], // Where to integrate from angle viewpoint - constraints: [], // Angle-specific limitations/conventions - clarification_needs: [], // Angle-related ambiguities - _metadata: { - exploration_angle: angle, - exploration_index: index + 1, - timestamp: getUtc8ISOString() - } - } +### Exploration Strategy (${angle} focus) - // Write exploration result - Write(`${sessionFolder}/exploration-${angle}.json`, JSON.stringify(explorationResult, null, 2)) +**Step 1: Structural Scan** (Bash) +- get_modules_by_depth.sh → identify modules related to ${angle} +- find/rg → locate files relevant to ${angle} aspect +- Analyze imports/dependencies from ${angle} perspective + +**Step 2: Semantic Analysis** (Gemini CLI) +- How does existing code handle ${angle} concerns? +- What patterns are used for ${angle}? +- Where would new code integrate from ${angle} viewpoint? + +**Step 3: Write Output** +- Consolidate ${angle} findings into JSON +- Identify ${angle}-specific clarification needs + +### Expected Output + +**File**: ${sessionFolder}/exploration-${angle}.json + +**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly + +**Required Fields** (all ${angle} focused): +- project_structure: Modules/architecture relevant to ${angle} +- relevant_files: Files affected from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` +- patterns: ${angle}-related patterns to follow +- dependencies: Dependencies relevant to ${angle} +- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) +- constraints: ${angle}-specific limitations/conventions +- clarification_needs: ${angle}-related ambiguities (options array + recommended index) +- _metadata.exploration_angle: "${angle}" + +### Success Criteria +- [ ] Schema obtained via cat explore-json-schema.json +- [ ] get_modules_by_depth.sh executed +- [ ] At least 3 relevant files identified with ${angle} rationale +- [ ] Patterns are actionable (code examples, not generic advice) +- [ ] Integration points include file:line locations +- [ ] JSON output follows schema exactly +- [ ] clarification_needs includes options + recommended + +### Deliverables +Write: ${sessionFolder}/exploration-${angle}.json +Return: 2-3 sentence summary of ${angle} findings +` + }) }) + +// Step 3: Batch wait for ALL exploration subagents (KEY ADVANTAGE of Codex) +const explorationResults = wait({ + ids: explorationAgents, + timeout_ms: 600000 // 10 minutes +}) + +// Step 4: Handle timeout +if (explorationResults.timed_out) { + console.log('部分探索超时，继续使用已完成结果') +} + +// Step 5: Collect results from completed agents +const completedExplorations = {} +explorationAgents.forEach((agentId, index) => { + const angle = selectedAngles[index] + if (explorationResults.status[agentId].completed) { + completedExplorations[angle] = explorationResults.status[agentId].completed + } +}) + +// Step 6: Cleanup - close all exploration agents +explorationAgents.forEach(id => close_agent({ id })) ``` **Build Exploration Manifest**: ```javascript -// After all explorations complete, build manifest +// After all explorations complete, auto-discover all exploration-*.json files const explorationFiles = find(`${sessionFolder}`, "-name", "exploration-*.json") const explorationManifest = { @@ -248,9 +305,6 @@ explorations.forEach(exp => { }) // Intelligent deduplication: analyze allClarifications by intent -// - Identify questions with similar intent across different angles -// - Merge similar questions: combine options, consolidate context -// - Produce dedupedClarifications with unique intents only const dedupedClarifications = intelligentMerge(allClarifications) ``` @@ -293,26 +347,21 @@ ${need.options.map((opt, i) => ` ${i + 1}. ${opt}${need.recommended === i ? ' **IMPORTANT**: Phase 3 is **planning only** - NO code execution. -**Read Schema**: -```javascript -// Read plan schema for reference -const schema = Read("~/.claude/workflows/cli-templates/schemas/plan-json-schema.json") -``` +**Planning Strategy Selection** (based on Phase 1 complexity): -**Read All Exploration Files**: +**Low Complexity** - Direct Planning: ```javascript -// MANDATORY - Read and review ALL exploration files +// Step 1: Read schema +const schema = Read("~/.claude/workflows/cli-templates/schemas/plan-json-schema.json") + +// Step 2: Read all exploration files for context const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) manifest.explorations.forEach(exp => { const explorationData = Read(exp.path) console.log(`\n### Exploration: ${exp.angle}\n${explorationData}`) }) -``` -**Generate Plan**: -```javascript -// Generate plan following schema -// Plan MUST incorporate insights from exploration files +// Step 3: Generate plan following schema (direct, no subagent) const plan = { summary: "Brief description of what will be implemented", approach: "High-level approach and strategy", @@ -322,7 +371,7 @@ const plan = { // 2-7 tasks recommended ], estimated_time: "Total estimated time", - complexity: complexity, // Low | Medium | High + complexity: complexity, _metadata: { timestamp: getUtc8ISOString(), source: "lite-plan", @@ -330,18 +379,94 @@ const plan = { exploration_angles: manifest.explorations.map(e => e.angle) } } + +// Step 4: Write plan +Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2)) + +// Step 5: Proceed to Phase 4 (Confirmation) ``` -**Task Grouping Rules**: +**Medium/High Complexity** - Spawn cli-lite-planning-agent Subagent: + +```javascript +// ==================== CODEX SUBAGENT PATTERN ==================== + +// Step 1: Create planning subagent (角色文件由 agent 自己读取) +const planningAgent = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### Objective +Generate implementation plan and write plan.json. + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first) +2. Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference) +3. Read: .workflow/project-tech.json (technology stack, architecture, key components) +4. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +**CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json + +### Task Description +$TASK + +### Multi-Angle Exploration Context + +${manifest.explorations.map(exp => `#### Exploration: ${exp.angle} (${exp.file}) +Path: ${exp.path} + +Read this file for detailed ${exp.angle} analysis.`).join('\n\n')} + +Total explorations: ${manifest.exploration_count} +Angles covered: ${manifest.explorations.map(e => e.angle).join(', ')} + +Manifest: ${sessionFolder}/explorations-manifest.json + +### User Clarifications +${JSON.stringify(clarificationContext) || "None"} + +### Complexity Level +${complexity} + +### Requirements +Generate plan.json following the schema obtained above. Key constraints: +- tasks: 2-7 structured tasks (**group by feature/module, NOT by file**) +- _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))} + +### Task Grouping Rules 1. **Group by feature**: All changes for one feature = one task (even if 3-5 files) 2. **Group by context**: Tasks with similar context or related functional changes can be grouped together -3. **Minimize task count**: Simple, unrelated tasks can also be grouped to reduce overhead +3. **Minimize agent count**: Simple, unrelated tasks can also be grouped to reduce agent execution overhead 4. **Avoid file-per-task**: Do NOT create separate tasks for each file 5. **Substantial tasks**: Each task should represent 15-60 minutes of work 6. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output 7. **Prefer parallel**: Most tasks should be independent (no depends_on) -**Proceed to Phase 4** - DO NOT execute code here. +### Execution +1. Read schema file (cat command above) +2. Execute CLI planning using Gemini (Qwen fallback) +3. Read ALL exploration files for comprehensive context +4. Synthesize findings and generate plan following schema +5. Write JSON: Write('${sessionFolder}/plan.json', jsonContent) +6. Return brief completion summary + +### Deliverables +Write: ${sessionFolder}/plan.json +Return: Brief plan summary +` +}) + +// Step 3: Wait for planning subagent to complete +const planResult = wait({ + ids: [planningAgent], + timeout_ms: 900000 // 15 minutes +}) + +// Step 4: Cleanup +close_agent({ id: planningAgent }) +``` + +**Output**: `${sessionFolder}/plan.json` --- @@ -362,7 +487,7 @@ ${plan.tasks.map((t, i) => ` ### Task ${i+1}: ${t.title} - **Description**: ${t.description} - **Scope**: ${t.scope} -- **Files**: ${t.files.join(', ')} +- **Files**: ${t.files?.join(', ') || 'N/A'} - **Complexity**: ${t.complexity} - **Dependencies**: ${t.depends_on?.join(', ') || 'None'} `).join('\n')} @@ -393,9 +518,7 @@ return **After User Confirms "Allow"**: ```javascript -// Write final plan.json to session folder -Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2)) - +// Final plan.json already written in Phase 3 console.log(` ## Plan Output Complete @@ -419,6 +542,24 @@ You can now use this plan with your preferred execution method: --- +## Codex vs Claude Comparison (for this workflow) + +| Aspect | Claude Code Task | Codex Subagent | +|--------|------------------|----------------| +| **Creation** | `Task({ subagent_type, prompt })` | `spawn_agent({ message: role + task })` | +| **Role Loading** | Auto via `subagent_type` | Manual: Read `~/.codex/agents/*.md` | +| **Parallel Wait** | Multiple `Task()` calls | **Batch `wait({ ids: [...] })`** | +| **Result Retrieval** | Sync return or `TaskOutput` | `wait({ ids }).status[id].completed` | +| **Follow-up** | `resume` parameter | `send_input({ id, message })` | +| **Cleanup** | Automatic | **Explicit `close_agent({ id })`** | + +**Codex Advantages for lite-plan**: +- True parallel exploration with batch `wait` +- Fine-grained lifecycle control +- Efficient multi-agent coordination + +--- + ## Session Folder Structure ``` @@ -431,16 +572,6 @@ You can now use this plan with your preferred execution method: └── plan.json # Implementation plan (after confirmation) ``` -**Example**: -``` -.workflow/.lite-plan/implement-jwt-refresh-2025-11-25/ -├── exploration-architecture.json -├── exploration-auth-patterns.json -├── exploration-security.json -├── explorations-manifest.json -└── plan.json -``` - ## Workflow States | State | Action | Next | @@ -458,8 +589,9 @@ You can now use this plan with your preferred execution method: | Error | Resolution | |-------|------------| -| Exploration failure | Skip exploration, continue with task description only | -| No relevant files found | Broaden search scope or proceed with minimal context | +| Subagent spawn failure | Fallback to direct exploration | +| wait() timeout | Use completed results, log partial status | +| Planning subagent failure | Fallback to direct planning | | Clarification timeout | Use exploration findings as-is | | Confirmation timeout | Save context, display resume instructions | | Modify loop > 3 times | Suggest breaking task into smaller pieces | diff --git a/codex SUBAGENT 策略补充.md b/codex SUBAGENT 策略补充.md index c1f3d897..7acf6d30 100644 --- a/codex SUBAGENT 策略补充.md +++ b/codex SUBAGENT 策略补充.md @@ -73,7 +73,7 @@ Codex subagent **没有系统提示词**，无法像 Claude Code 那样通过 `s ### 4.2 角色文件位置 ``` -.codex/agents/ +~/.codex/agents/ ├── cli-explore-agent.md # 代码探索 ├── cli-lite-planning-agent.md # 轻量规划 ├── code-developer.md # 代码开发 @@ -86,11 +86,15 @@ Codex subagent **没有系统提示词**，无法像 Claude Code 那样通过 `s ### 4.3 角色加载模板 ```javascript -// 标准 spawn_agent 消息结构 +// 标准 spawn_agent 消息结构（角色路径传递，agent 自己读取） spawn_agent({ message: ` -## ROLE DEFINITION -${Read('.codex/agents/{agent-type}.md')} +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json ## TASK CONTEXT ${taskContext} @@ -101,19 +105,21 @@ ${deliverables} }) ``` +> **注意**：角色文件由 agent 自己读取，主流程只传递路径。详见 §9.1 角色加载模式。 + ### 4.4 角色映射表 | Claude subagent_type | Codex 角色文件 | |----------------------|----------------| -| `cli-explore-agent` | `.codex/agents/cli-explore-agent.md` | -| `cli-lite-planning-agent` | `.codex/agents/cli-lite-planning-agent.md` | -| `code-developer` | `.codex/agents/code-developer.md` | -| `context-search-agent` | `.codex/agents/context-search-agent.md` | -| `debug-explore-agent` | `.codex/agents/debug-explore-agent.md` | -| `doc-generator` | `.codex/agents/doc-generator.md` | -| `action-planning-agent` | `.codex/agents/action-planning-agent.md` | -| `test-fix-agent` | `.codex/agents/test-fix-agent.md` | -| `universal-executor` | `.codex/agents/universal-executor.md` | +| `cli-explore-agent` | `~/.codex/agents/cli-explore-agent.md` | +| `cli-lite-planning-agent` | `~/.codex/agents/cli-lite-planning-agent.md` | +| `code-developer` | `~/.codex/agents/code-developer.md` | +| `context-search-agent` | `~/.codex/agents/context-search-agent.md` | +| `debug-explore-agent` | `~/.codex/agents/debug-explore-agent.md` | +| `doc-generator` | `~/.codex/agents/doc-generator.md` | +| `action-planning-agent` | `~/.codex/agents/action-planning-agent.md` | +| `test-fix-agent` | `~/.codex/agents/test-fix-agent.md` | +| `universal-executor` | `~/.codex/agents/universal-executor.md` | ## 5. 结构化交付模式 @@ -182,16 +188,18 @@ Worker 3: src/database/** → 数据层变更 ## 7. 消息设计规范 -### 7.1 spawn_agent message 结构（含角色加载） +### 7.1 spawn_agent message 结构（角色路径传递） ```text -## ROLE DEFINITION -{角色文件内容 - 从 .codex/agents/*.md 读取} +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json --- -## TASK ASSIGNMENT - Goal: 一句话目标（做什么） Scope: @@ -213,6 +221,8 @@ Quality bar: - 验收标准 2 ``` +> **注意**：角色文件路径放在 MANDATORY FIRST STEPS，由 agent 自己读取。主流程不传递角色内容。 + ### 7.2 send_input 追问模式 ```text @@ -247,7 +257,7 @@ spawn_agent(new_message) → 创建新 agent ## 9. 最佳实践清单 -- [ ] **首条消息加载角色**：从 `.codex/agents/*.md` 读取角色定义 +- [ ] **角色文件路径传递**：在 MANDATORY FIRST STEPS 中指定 `~/.codex/agents/*.md` 路径，由 agent 自己读取 - [ ] 创建前明确 Goal/Scope/Context/Deliverables/Quality bar - [ ] 按职责或模块域拆分，避免文件冲突 - [ ] 要求统一输出模板，便于合并 @@ -257,13 +267,278 @@ spawn_agent(new_message) → 创建新 agent - [ ] 超时后评估是否继续等待或催促收敛 - [ ] 合并结果时检查冲突和一致性 +### 9.1 角色加载模式（重要） + +**❌ 错误模式：主流程读取角色内容并传递** +```javascript +// 主流程读取角色文件内容 +const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') + +spawn_agent({ + message: ` +## ROLE DEFINITION +${exploreRole} // 内容嵌入到 message 中 + +## TASK +... +` +}) +``` + +**问题**： +- message 体积膨胀，传输开销大 +- 角色内容在主流程上下文中占用空间 +- 不符合 agent 自主性原则 + +**✅ 正确模式：传递路径，agent 自己读取** +```javascript +spawn_agent({ + message: ` +## TASK ASSIGNMENT +... + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json +... +` +}) +``` + +**优势**： +- message 精简，只传递任务相关内容 +- agent 拥有完整的角色理解上下文 +- 遵循 agent 自主执行原则 + +--- + +## 10. Subagent 深度交互准则 + +### 10.1 核心理念：充分交流优于多次调用 + +**传统模式问题**： +- 探索 → 澄清 → 规划 分离执行，上下文断裂 +- 每个阶段独立 subagent，信息传递有损耗 +- 多轮用户交互，体验割裂 + +**优化理念**： +- **单 subagent 深度交互** > 多 subagent 浅层调用 +- **澄清与规划合并**，一次完成上下文积累 +- **send_input 多轮对话**，保持上下文连贯 + +### 10.2 澄清 + 规划合并模式 + +**原有分离模式**（Claude lite-plan）： +``` +Phase 1: spawn explore-agent × N → wait → close +Phase 2: 主 agent 收集澄清问题 → 用户回答 +Phase 3: spawn planning-agent → wait → close +``` + +**优化合并模式**（Codex 推荐）： +``` +Phase 1: spawn explore-agent × N → wait (保持 agent 活跃) +Phase 2: send_input 传递澄清答案 → agent 继续生成 plan +Phase 3: wait 获取最终 plan → close +``` + +**实现示例**： +```javascript +// ==================== 合并模式：探索 + 澄清 + 规划 ==================== + +// Step 1: 创建探索 agent（带规划能力） +const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') +const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md') + +const agent = spawn_agent({ + message: ` +## ROLE DEFINITION (DUAL ROLE) + +### Primary: Exploration +${exploreRole} + +### Secondary: Planning (activated after clarification) +${planningRole} + +--- + +## TASK ASSIGNMENT + +### Phase 1: Exploration +Goal: Explore codebase for "${task_description}" +Output: Structured findings + clarification questions (if any) + +### Phase 2: Await Clarification (if questions exist) +Output format for questions: +\`\`\` +CLARIFICATION_NEEDED: +Q1: [question] | Options: [A, B, C] | Recommended: [A] +Q2: [question] | Options: [A, B] | Recommended: [B] +\`\`\` + +### Phase 3: Generate Plan (after clarification) +Trigger: Receive clarification answers via send_input +Output: plan.json following schema + +### Deliverables +- exploration.json (Phase 1) +- plan.json (Phase 3, after clarification) +` +}) + +// Step 2: 等待探索结果 +const exploreResult = wait({ ids: [agent], timeout_ms: 600000 }) + +// Step 3: 解析是否需要澄清 +const needsClarification = exploreResult.status[agent].completed.includes('CLARIFICATION_NEEDED') + +if (needsClarification) { + // Step 4: 获取用户回答（主 agent 处理） + const userAnswers = collectUserAnswers(exploreResult) + + // Step 5: 通过 send_input 继续交互（关键：不 close） + send_input({ + id: agent, + message: ` +## CLARIFICATION ANSWERS +${userAnswers.map(a => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')} + +## NEXT STEP +Based on exploration findings and clarification answers, generate plan.json. +Follow schema: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json +` + }) + + // Step 6: 等待规划结果 + const planResult = wait({ ids: [agent], timeout_ms: 900000 }) +} + +// Step 7: 最终清理 +close_agent({ id: agent }) +``` + +### 10.3 多轮 send_input 交互模式 + +**场景**：复杂任务需要多次迭代确认 + +```javascript +// 创建 agent +const agent = spawn_agent({ message: roleDefinition + taskPrompt }) + +// 第一轮：获取初步方案 +const round1 = wait({ ids: [agent], timeout_ms: 300000 }) + +// 第二轮：用户反馈后迭代 +send_input({ + id: agent, + message: ` +## USER FEEDBACK +${userFeedback} + +## REQUEST +Revise the plan based on feedback. Focus on: +1. ${focusPoint1} +2. ${focusPoint2} +` +}) +const round2 = wait({ ids: [agent], timeout_ms: 300000 }) + +// 第三轮：确认细节 +send_input({ + id: agent, + message: ` +## CONFIRMATION +Plan approved with minor adjustments: +- Change task T2 scope to include ${additionalScope} +- Add dependency T1 → T3 + +## FINAL REQUEST +Output final plan.json with these adjustments. +` +}) +const finalResult = wait({ ids: [agent], timeout_ms: 300000 }) + +// 清理 +close_agent({ id: agent }) +``` + +### 10.4 简化命令设计原则 + +**原则 1：减少 Phase 数量** +| 原有模式 | 优化模式 | +|----------|----------| +| Phase 1: Explore | Phase 1: Explore + Clarify + Plan (单 agent) | +| Phase 2: Clarify | ↑ | +| Phase 3: Plan | ↑ | +| Phase 4: Confirm | Phase 2: Confirm (主 agent) | +| Phase 5: Execute | Phase 3: Execute | + +**原则 2：延迟 close_agent** +```javascript +// ❌ 错误：过早关闭 +const result = wait({ ids: [agent] }) +close_agent({ id: agent }) // 关闭后无法继续交互 +// ... 发现需要追问，只能重建 agent + +// ✅ 正确：延迟关闭 +const result = wait({ ids: [agent] }) +// 检查是否需要继续交互 +if (needsMoreInteraction(result)) { + send_input({ id: agent, message: followUpMessage }) + const result2 = wait({ ids: [agent] }) +} +close_agent({ id: agent }) // 确认不再需要后才关闭 +``` + +**原则 3：上下文复用** +```javascript +// ❌ 错误：每个阶段独立 agent，上下文丢失 +const exploreAgent = spawn_agent({ message: explorePrompt }) +const exploreResult = wait({ ids: [exploreAgent] }) +close_agent({ id: exploreAgent }) + +const planAgent = spawn_agent({ + message: planPrompt + JSON.stringify(exploreResult) // 需要手动传递上下文 +}) + +// ✅ 正确：单 agent 多阶段，上下文自动保持 +const agent = spawn_agent({ message: dualRolePrompt }) +const exploreResult = wait({ ids: [agent] }) +send_input({ id: agent, message: "Now generate plan based on your findings" }) +const planResult = wait({ ids: [agent] }) // agent 自动保持探索上下文 +close_agent({ id: agent }) +``` + +### 10.5 效果对比 + +| 指标 | 分离模式 | 合并模式 | 提升 | +|------|----------|----------|------| +| Agent 创建数 | 3-5 | 1-2 | 60-80% ↓ | +| 用户交互轮次 | 3-4 | 1-2 | 50% ↓ | +| 上下文传递损耗 | 高 | 低 | 显著 ↓ | +| 总执行时间 | 长（多次 spawn/close） | 短（复用 agent） | 30-50% ↓ | +| 结果一致性 | 中（多 agent 可能不一致） | 高（单 agent 统一视角） | 显著 ↑ | + +### 10.6 适用场景判断 + +**使用合并模式**（推荐）： +- 探索 → 澄清 → 规划 流程 +- 诊断 → 澄清 → 修复方案 流程 +- 任何需要多阶段但上下文强相关的任务 + +**使用分离模式**： +- 多角度并行探索（不同角度独立，无需共享上下文） +- 职责完全不同的阶段（如：代码生成 vs 测试生成） +- 需要不同专业角色的场景 + --- # Claude → Codex 多 Agent 命令转换规范 -## 10. 转换概述 +## 11. 转换概述 -### 10.1 核心差异 +### 11.1 核心差异 | 维度 | Claude Code | Codex | |------|-------------|-------| @@ -273,16 +548,16 @@ spawn_agent(new_message) → 创建新 agent | **追问/续做** | `resume` 参数 | `send_input()` | | **生命周期** | 自动回收 | 显式 `close_agent()` | -### 10.2 转换原则 +### 11.2 转换原则 1. **角色前置**：每个 subagent 首条消息必须包含角色定义 2. **批量等待**：利用 `wait({ ids: [...] })` 实现真并行 3. **结果汇聚**：主 agent 负责合并多个 subagent 结果 4. **显式清理**：任务完成后统一 close -## 11. 转换模板 +## 12. 转换模板 -### 11.1 Claude Task 调用转换 +### 12.1 Claude Task 调用转换 **Claude 原始调用**： ```javascript @@ -301,7 +576,7 @@ Execute architecture exploration... **Codex 转换后**： ```javascript // Step 1: 读取角色定义 -const roleDefinition = Read('.codex/agents/cli-explore-agent.md') +const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md') // Step 2: 创建 subagent（角色 + 任务合并） const agentId = spawn_agent({ @@ -329,7 +604,7 @@ const result = wait({ ids: [agentId], timeout_ms: 300000 }) close_agent({ id: agentId }) ``` -### 11.2 并行多 Agent 转换 +### 12.2 并行多 Agent 转换 **Claude 原始调用**（并行 3 个 agent）： ```javascript @@ -345,7 +620,7 @@ const tasks = angles.map(angle => **Codex 转换后**： ```javascript // Step 1: 读取角色定义（只读一次） -const roleDefinition = Read('.codex/agents/cli-explore-agent.md') +const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md') // Step 2: 并行创建多个 subagent const agentIds = angles.map(angle => { @@ -378,9 +653,9 @@ const aggregatedFindings = agentIds.map(id => results.status[id].completed) agentIds.forEach(id => close_agent({ id })) ``` -## 12. lite-plan 命令转换示例 +## 13. lite-plan 命令转换示例 -### 12.1 Phase 1: 探索阶段转换 +### 13.1 Phase 1: 探索阶段转换 **Claude 原始实现**： ```javascript @@ -404,7 +679,7 @@ Execute **${angle}** exploration... **Codex 转换后**： ```javascript // Step 1: 加载角色定义 -const exploreRole = Read('.codex/agents/cli-explore-agent.md') +const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') // Step 2: 并行创建探索 subagent const explorationAgents = selectedAngles.map((angle, index) => { @@ -470,7 +745,7 @@ explorationAgents.forEach((agentId, index) => { explorationAgents.forEach(id => close_agent({ id })) ``` -### 12.2 Phase 3: 规划阶段转换 +### 13.2 Phase 3: 规划阶段转换 **Claude 原始实现**： ```javascript @@ -489,7 +764,7 @@ Generate implementation plan and write plan.json. **Codex 转换后**： ```javascript // Step 1: 加载规划角色 -const planningRole = Read('.codex/agents/cli-lite-planning-agent.md') +const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md') // Step 2: 创建规划 subagent const planningAgent = spawn_agent({ @@ -547,13 +822,13 @@ const planResult = wait({ close_agent({ id: planningAgent }) ``` -## 13. 完整工作流转换模板 +## 14. 完整工作流转换模板 -### 13.1 Codex 多阶段工作流结构 +### 14.1 Codex 多阶段工作流结构 ```javascript // ==================== Phase 1: 探索 ==================== -const exploreRole = Read('.codex/agents/cli-explore-agent.md') +const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') const explorationAgents = [] // 并行创建探索 agents @@ -616,7 +891,7 @@ Proceed to generate recommendations based on responses. } // ==================== Phase 3: 规划 ==================== -const planRole = Read('.codex/agents/cli-lite-planning-agent.md') +const planRole = Read('~/.codex/agents/cli-lite-planning-agent.md') const planAgent = spawn_agent({ message: ` @@ -637,9 +912,9 @@ close_agent({ id: planAgent }) // ... (主 agent 直接处理用户交互) ``` -## 14. 角色文件管理 +## 15. 角色文件管理 -### 14.1 角色文件结构规范 +### 15.1 角色文件结构规范 ```markdown --- @@ -662,18 +937,18 @@ color: {blue|green|yellow|cyan|...} **NEVER**: ... ``` -### 14.2 新增角色检查清单 +### 15.2 新增角色检查清单 -- [ ] 文件位于 `.codex/agents/` 目录 +- [ ] 文件位于 `~/.codex/agents/` 目录 - [ ] 包含 YAML front matter (name, description, color) - [ ] 定义 Core Capabilities - [ ] 定义 Execution Process/Workflow - [ ] 包含 Key Reminders (ALWAYS/NEVER) - [ ] 在 §4.4 角色映射表中添加条目 -## 15. 常见转换问题 +## 16. 常见转换问题 -### 15.1 run_in_background 处理 +### 16.1 run_in_background 处理 **Claude**：`run_in_background=false` 表示同步等待 **Codex**：始终异步，通过 `wait()` 控制同步点 @@ -687,7 +962,7 @@ const agentId = spawn_agent({ message: "..." }) const result = wait({ ids: [agentId] }) // 阻塞直到完成 ``` -### 15.2 resume 转换 +### 16.2 resume 转换 **Claude**：使用 `resume` 参数恢复 agent **Codex**：使用 `send_input` 继续交互 @@ -701,7 +976,7 @@ send_input({ id: previousAgentId, message: "Continue..." }) const result = wait({ ids: [previousAgentId] }) ``` -### 15.3 TaskOutput 轮询转换 +### 16.3 TaskOutput 轮询转换 **Claude**：`TaskOutput({ task_id, block: false })` 轮询 **Codex**：`wait({ ids, timeout_ms })` 带超时等待 @@ -721,11 +996,11 @@ while (result.timed_out) { } ``` -## 16. 转换检查清单 +## 17. 转换检查清单 转换 Claude 多 Agent 命令到 Codex 时，确保： -- [ ] **角色加载**：首条 message 包含 `.codex/agents/*.md` 内容 +- [ ] **角色加载**：首条 message 包含 `~/.codex/agents/*.md` 内容 - [ ] **并行优化**：多个独立 agent 使用批量 `wait({ ids: [...] })` - [ ] **超时处理**：设置合理 `timeout_ms`，处理 `timed_out` 情况 - [ ] **结果汇聚**：主 agent 负责合并 `status[id].completed`