Claude-Code-Workflow/.codex/skills/workflow-lite-plan-execute/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
workflow-lite-plan-execute	Unified lightweight planning skill with mode selection (Lite Plan, Multi-CLI Plan, Lite Fix). Supports exploration, diagnosis, multi-CLI collaboration, and shared execution via lite-execute.	spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context

Planning Workflow

Unified lightweight planning skill that consolidates multiple planning approaches into a single entry point with mode selection. Default mode: Lite Plan. All planning modes share a common execution phase (lite-execute).

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│  Planning Workflow Orchestrator (SKILL.md)                │
│  → Parse args → Mode selection → Load phase → Execute    │
└────────────┬─────────────────────────────────────────────┘
             │ Mode Selection (default: Lite Plan)
    ┌────────┼────────┬──────────┐
    ↓        ↓        ↓          ↓ (shared)
┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐
│Phase 1 │ │Phase 2 │ │Phase 3 │ │  Phase 4   │
│  Lite  │ │Multi-  │ │  Lite  │ │   Lite     │
│  Plan  │ │CLI Plan│ │  Fix   │ │  Execute   │
└────────┘ └────────┘ └────────┘ └────────────┘
     │          │          │           ↑
     └──────────┴──────────┴───────────┘
            (all hand off to Phase 4)

Key Design Principles

1. Mode Selection First: User chooses planning approach before any work begins
2. Shared Execution: All planning modes produce executionContext consumed by Phase 4 (lite-execute)
3. Progressive Phase Loading: Only load the selected planning phase + execution phase
4. Auto-Continue: Planning phase completes → automatically loads execution phase
5. Default Lite Plan: When no mode specified, use Lite Plan (most common)

Auto Mode

When --yes or -y: Skip mode selection (use default or flag-specified mode), auto-approve plan, skip clarifications.

Usage

Skill(skill="workflow-lite-plan-execute", args="<task description>")
Skill(skill="workflow-lite-plan-execute", args="[FLAGS] \"<task description>\"")

# Flags
--mode lite-plan|multi-cli|lite-fix    Planning mode selection (default: lite-plan)
-y, --yes                              Skip all confirmations (auto mode)
-e, --explore                          Force exploration (lite-plan only)
--hotfix                               Fast hotfix mode (lite-fix only)

# Examples
Skill(skill="workflow-lite-plan-execute", args="\"Implement JWT authentication\"")                              # Default: lite-plan
Skill(skill="workflow-lite-plan-execute", args="--mode multi-cli \"Refactor payment module\"")                  # Multi-CLI planning
Skill(skill="workflow-lite-plan-execute", args="--mode lite-fix \"Login fails with 500 error\"")                # Bug fix mode
Skill(skill="workflow-lite-plan-execute", args="-y \"Add user profile page\"")                                  # Auto mode
Skill(skill="workflow-lite-plan-execute", args="--mode lite-fix --hotfix \"Production DB timeout\"")            # Hotfix mode

Subagent API Reference

spawn_agent

Create a new subagent with task assignment.

const agentId = spawn_agent({
  message: `
## 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}

## DELIVERABLES
${deliverables}
`
})

wait

Get results from subagent (only way to retrieve results).

const result = wait({
  ids: [agentId],
  timeout_ms: 600000  // 10 minutes
})

if (result.timed_out) {
  // Handle timeout - can continue waiting or send_input to prompt completion
}

send_input

Continue interaction with active subagent (for clarification or follow-up).

send_input({
  id: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

Clean up subagent resources (irreversible).

close_agent({ id: agentId })

Execution Flow

Input Parsing:
   ├─ Extract flags: --mode, --yes, --explore, --hotfix
   └─ Extract task description (string or file path)

Mode Selection:
   └─ Decision:
      ├─ --mode lite-plan (or no --mode flag) → Read phases/01-lite-plan.md
      ├─ --mode multi-cli → Read phases/02-multi-cli-plan.md
      ├─ --mode lite-fix → Read phases/03-lite-fix.md
      └─ No flag + not --yes → AskUserQuestion (default: Lite Plan)

Planning Phase (one of):
   ├─ Phase 1: Lite Plan
   │   └─ Ref: phases/01-lite-plan.md
   │      └─ Output: executionContext (plan.json + explorations + selections)
   │
   ├─ Phase 2: Multi-CLI Plan
   │   └─ Ref: phases/02-multi-cli-plan.md
   │      └─ Output: executionContext (plan.json + synthesis rounds + selections)
   │
   └─ Phase 3: Lite Fix
       └─ Ref: phases/03-lite-fix.md
          └─ Output: executionContext (fix-plan.json + diagnoses + selections)

Execution Phase (always):
   └─ Phase 4: Lite Execute
       └─ Ref: phases/04-lite-execute.md
          └─ Input: executionContext from planning phase
          └─ Output: Executed tasks + optional code review

Phase Reference Documents (read on-demand when phase executes):

Phase	Document	Purpose
1	phases/01-lite-plan.md	Lightweight planning with exploration, clarification, and plan generation
2	phases/02-multi-cli-plan.md	Multi-CLI collaborative planning with ACE context and cross-verification
3	phases/03-lite-fix.md	Bug diagnosis and fix planning with severity-based workflow
4	phases/04-lite-execute.md	Shared execution engine: task grouping, batch execution, code review

Mode Selection Logic

// Flag parsing
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const modeFlag = extractFlag($ARGUMENTS, '--mode')  // 'lite-plan' | 'multi-cli' | 'lite-fix' | null

// Mode determination
let selectedMode

if (modeFlag) {
  // Explicit mode flag
  selectedMode = modeFlag
} else if (autoYes) {
  // Auto mode: default to lite-plan
  selectedMode = 'lite-plan'
} else {
  // Interactive: ask user
  const selection = AskUserQuestion({
    questions: [{
      question: "Select planning approach:",
      header: "Mode",
      multiSelect: false,
      options: [
        { label: "Lite Plan (Recommended)", description: "Lightweight planning with exploration and clarification" },
        { label: "Multi-CLI Plan", description: "Multi-model collaborative planning (Gemini + Codex + Claude)" },
        { label: "Lite Fix", description: "Bug diagnosis and fix planning with severity assessment" }
      ]
    }]
  })
  selectedMode = parseSelection(selection)  // Map to 'lite-plan' | 'multi-cli' | 'lite-fix'
}

// Load phase document
const phaseDoc = {
  'lite-plan': 'phases/01-lite-plan.md',
  'multi-cli': 'phases/02-multi-cli-plan.md',
  'lite-fix': 'phases/03-lite-fix.md'
}[selectedMode]

Read(phaseDoc)  // Load selected planning phase
// Execute planning phase...
// After planning completes:
Read('phases/04-lite-execute.md')  // Load execution phase

Data Flow

Planning Phase (01/02/03)
   │
   ├─ Produces: executionContext = {
   │     planObject: plan.json or fix-plan.json,
   │     explorationsContext / diagnosisContext / synthesis rounds,
   │     clarificationContext,
   │     executionMethod: "Agent" | "Codex" | "Auto",
   │     codeReviewTool: "Skip" | "Gemini Review" | ...,
   │     originalUserInput: string,
   │     session: { id, folder, artifacts }
   │   }
   │
   ↓
Execution Phase (04)
   │
   ├─ Consumes: executionContext
   ├─ Task grouping → Batch creation → Parallel/sequential execution
   ├─ Optional code review
   └─ Development index update

TodoWrite Pattern

Initialization (after mode selection):

[
  {"content": "Mode: {selectedMode} - Planning", "status": "in_progress", "activeForm": "Planning ({selectedMode})"},
  {"content": "Execution (Phase 4)", "status": "pending", "activeForm": "Executing tasks"}
]

After planning completes:

[
  {"content": "Mode: {selectedMode} - Planning", "status": "completed", "activeForm": "Planning ({selectedMode})"},
  {"content": "Execution (Phase 4)", "status": "in_progress", "activeForm": "Executing tasks"}
]

Phase-internal sub-tasks are managed by each phase document (attach/collapse pattern).

Core Rules

1. Planning phases NEVER execute code - all execution delegated to Phase 4
2. Only ONE planning phase runs per invocation (Phase 1, 2, or 3)
3. Phase 4 ALWAYS runs after planning completes
4. executionContext is the contract between planning and execution phases
5. Progressive loading: Read phase doc ONLY when about to execute
6. No cross-phase loading: Don't load Phase 2 if user selected Phase 1
7. Explicit Lifecycle: Always close_agent after wait completes to free resources

Error Handling

Error	Resolution
Unknown --mode value	Default to lite-plan with warning
Planning phase failure	Display error, offer retry or mode switch
executionContext missing	Error: planning phase did not produce context
Phase file not found	Error with file path for debugging

Related Skills

• Full planning workflow: workflow-plan-execute/SKILL.md
• Brainstorming: workflow-brainstorm-auto-parallel/SKILL.md