workflow-lite-plan

name	workflow-lite-plan
description	Lightweight planning skill - task analysis, multi-angle exploration, clarification, adaptive planning, confirmation, and execution handoff
allowed-tools	Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep

Planning pipeline: explore → clarify → plan → confirm → handoff to workflow-lite-execute. Produces exploration results, a structured plan (plan.json), independent task files (.task/TASK-*.json), and hands off to workflow-lite-execute for implementation.

1. Context Isolation

CRITICAL: If invoked from analyze-with-file or brainstorm-with-file, the prior session is COMPLETE and all its phase instructions are FINISHED and MUST NOT be referenced. Only follow LP-Phase 1-5 defined in THIS document. Phase numbers are INDEPENDENT of any prior workflow.

2. Input

<task-description>         Task description or path to .md file (required)

Flag	Description
-y, --yes	Auto mode: Skip clarification, auto-confirm plan, auto-select execution, skip review (entire plan+execute workflow)
--force-explore	Force code exploration even when task has prior analysis

Note: Workflow preferences (autoYes, forceExplore) must be initialized at skill start. If not provided by caller, skill will prompt user for workflow mode selection.

3. Output Artifacts

Artifact	Description
exploration-{angle}.json	Per-angle exploration results (1-4 files based on complexity)
explorations-manifest.json	Index of all exploration files
planning-context.md	Evidence paths + synthesized understanding
plan.json	Plan overview with task_ids[] (plan-overview-base-schema.json)
.task/TASK-*.json	Independent task files (one per task)

Output Directory: .workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/

Agent Usage: All complexities → cli-lite-planning-agent

Schema Reference: ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json

4. Phase Summary

Phase	Core Action	Output
LP-0	Initialize workflowPreferences	autoYes, forceExplore
LP-1	Complexity assessment → parallel cli-explore-agents (1-4)	exploration-*.json + manifest
LP-2	Aggregate + dedup clarification_needs → multi-round AskUserQuestion	clarificationContext (in-memory)
LP-3	cli-lite-planning-agent	plan.json + .task/TASK-*.json
LP-4	Display plan → AskUserQuestion (Confirm + Execution + Review)	userSelection
LP-5	Build executionContext → Skill("workflow-lite-execute")	handoff (Mode 1)

5. LP-Phase 0: Workflow Preferences Initialization

if (typeof workflowPreferences === 'undefined' || workflowPreferences === null) {
  workflowPreferences = {
    autoYes: false,      // false: show LP-Phase 2/4 prompts | true (-y): skip all prompts
    forceExplore: false
  }
}

6. LP-Phase 1: Intelligent Multi-Angle Exploration

Session Setup (MANDATORY):

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
const priorHeader = task_description.match(/^## Prior (?:Analysis|Brainstorm) \((.+?)\)/m)
const taskSlug = (priorHeader ? priorHeader[1] : task_description).toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40).replace(/^-+|-+$/g, '')
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `${taskSlug}-${dateStr}`
const sessionFolder = `.workflow/.lite-plan/${sessionId}`
bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`)

TodoWrite Template (initial state — subsequent phases update status progressively):

// Pattern: set phases[0..N-1].status="completed", phases[N].status="in_progress"
// Only full block shown here; subsequent updates follow same structure with status changes
TodoWrite({ todos: [
  { content: `LP-Phase 1: Exploration [${complexity}] ${selectedAngles.length} angles`, status: "in_progress", activeForm: `Exploring: ${selectedAngles.join(', ')}` },
  { content: "LP-Phase 2: Clarification", status: "pending" },
  { content: "LP-Phase 3: Planning [cli-lite-planning-agent]", status: "pending" },
  { content: "LP-Phase 4: Confirmation", status: "pending" },
  { content: "LP-Phase 5: Execution", status: "pending" }
]})

Exploration Decision Logic:

const hasPriorAnalysis = /##\s*Prior Analysis/i.test(task_description)
const hasHandoffSpec = /```json:handoff-spec/i.test(task_description)

// Parse structured handoff from analyze-with-file or brainstorm-with-file (if present)
let handoffSpec = null
if (hasHandoffSpec) {
  const specMatch = task_description.match(/```json:handoff-spec\s*\n([\s\S]*?)\n```/)
  if (specMatch) {
    handoffSpec = JSON.parse(specMatch[1])
    // handoffSpec contains: { source, session_id, session_folder, summary,
    //   implementation_scope[], code_anchors[], key_files[], key_findings[], decision_context[],
    //   exploration_artifacts: { exploration_codebase, explorations, perspectives, research, deep_dives[] } }
    // implementation_scope[]: { objective, rationale, priority, target_files[], acceptance_criteria[], change_summary }
    console.log(`[Handoff] From ${handoffSpec.source} session ${handoffSpec.session_id}`)
    console.log(`[Handoff] ${handoffSpec.implementation_scope.length} scoped items with acceptance criteria`)

    // Enrich task_description with handoff context for downstream planning agent
    // These fields were previously produced but unused — now injected into planning context
    if (handoffSpec.summary) {
      task_description += `\n\n## Analysis Summary\n${handoffSpec.summary}`
    }
    if (handoffSpec.?. > ) {
      task_description += 
    }
     (handoffSpec.?. > ) {
      task_description += 
    }
     (handoffSpec.?. > ) {
      task_description += 
    }
  }
}


 isBrainstormSource = handoffSpec?. === 
 isAnalysisSource = handoffSpec?. === 

needsExploration = workflowPreferences. ? 
  : isBrainstormSource ?   
  : (hasPriorAnalysis || isAnalysisSource) ? 
  : (task. ||
     task. ||
     task. ||
     task.)

 (!needsExploration) {
  
   (isAnalysisSource && handoffSpec?.) {
     artifacts = handoffSpec.
     explorationEntries = []
     idx = 
     artifactMapping = [
      { : , :  },
      { : , :  },
      { : , :  },
      { : , :  }
    ]
    artifactMapping.( {
       (artifacts[key] && (artifacts[key])) {
        explorationEntries.({
          angle, : artifacts[key].().(),
          : artifacts[key], : , : idx++
        })
      }
    })
     (artifacts.?. > ) {
      artifacts..( {
         ((divePath)) {
           name = divePath.()?.[] || 
          explorationEntries.({
            : name, : ,
            : divePath, : , : idx++
          })
        }
      })
    }
     (explorationEntries. > ) {
      (, .({
        : sessionId, task_description, : (),
        complexity, : explorationEntries.,
        : , : handoffSpec.,
        : explorationEntries
      }, , ))
      .()
    }
  }
  
  ()
}

Context Protection: File reading >=50k chars → force needsExploration=true (delegate to cli-explore-agent)

Complexity Assessment:

const complexity = analyzeTaskComplexity(task_description)
// 'Low': single file, single function, zero cross-module impact (fix typo, rename var, adjust constant)
// 'Medium': multiple files OR integration point OR new pattern (add endpoint, implement feature, refactor)
// 'High': cross-module, architectural, systemic (new subsystem, migration, security overhaul)
// Default bias: uncertain between Low/Medium → choose Medium

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']
}

function selectAngles(taskDescription, count) {
  const text = taskDescription.toLowerCase()
  let preset = 'feature'
  if (/refactor|architect|restructure|modular/.test(text)) preset = 'architecture'
    (.(text)) preset = 
    (.(text)) preset = 
    (.(text)) preset = 
   [preset].(, count)
}

 selectedAngles = (task_description, complexity ===  ?  : (complexity ===  ?  : ))

.()

Launch Parallel Explorations:

CRITICAL: MUST NOT use run_in_background: true — exploration results are REQUIRED before planning.

const explorationTasks = selectedAngles.map((angle, index) =>
  Task(
    subagent_type="cli-explore-agent",
    run_in_background=false,
    description=`Explore: ${angle}`,
    prompt=`
## Task Objective
Execute **${angle}** exploration for task planning context.

## Output Location
**Session Folder**: ${sessionFolder}
**Output File**: ${sessionFolder}/exploration-${angle}.json

## Assigned Context
- **Exploration Angle**: ${angle}
- **Task Description**: ${task_description}
- **Exploration Index**: ${index + 1} of ${selectedAngles.length}

## Exploration Strategy (${angle} focus)

**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
**Schema**: explore-json-schema.json (auto-loaded by agent)
- All fields scoped to ${angle} perspective
- Ensure rationale is specific and >10 chars (not generic)
- Include file:line locations in integration_points
- _metadata.exploration_angle: "${angle}"

## Success Criteria
- [ ] get_modules_by_depth.sh executed
- [ ] At least 3 relevant files with specific rationale (>10 chars) + role classification
- [ ] Patterns are actionable (code examples, not generic advice)
- [ ] Integration points include file:line locations
- [ ] Constraints are project-specific to ${angle}
- [ ] JSON follows schema; clarification_needs includes options + recommended
- [ ] Files with relevance >= 0.7 have key_code array + topic_relation

## Execution
**Write**: \`/exploration-.json\`
**Return**: 2-3 sentence summary of  findings
`
  )
)

Auto-discover & Build Manifest:

const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`)
  .split('\n').filter(f => f.trim())

const explorationManifest = {
  session_id: sessionId,
  task_description: task_description,
  timestamp: getUtc8ISOString(),
  complexity: complexity,
  exploration_count: explorationFiles.length,
  explorations: explorationFiles.map(file => {
    const data = JSON.parse(Read(file))
    return {
      angle: data._metadata.exploration_angle,
      file: path.basename(file),
      path: file,
      index: data._metadata.exploration_index
    }
  })
}

Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2))
console.log(`Exploration complete: ${explorationManifest.explorations.map(e => e.angle).join(', ')}`)

// TodoWrite: Phase 1 → completed, Phase 2 → in_progress

Output: exploration-{angle}.json (1-4 files) + explorations-manifest.json

7. LP-Phase 2: Clarification (Optional, Multi-Round)

Skip if: No exploration or clarification_needs is empty across all explorations

CRITICAL: AskUserQuestion limits max 4 questions per call. MUST execute multiple rounds to exhaust all clarification needs.

const manifest = file_exists(`${sessionFolder}/explorations-manifest.json`)
  ? JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
  : { exploration_count: 0, explorations: [] }
const explorations = manifest.explorations.map(exp => ({
  angle: exp.angle,
  data: JSON.parse(Read(exp.path))
}))

// Aggregate from all explorations
const allClarifications = []
explorations.forEach(exp => {
  if (exp.data.clarification_needs?.length > 0) {
    exp.data.clarification_needs.forEach(need => {
      allClarifications.push({ ...need, source_angle: exp.angle })
    })
  }
})

// Intelligent dedup: merge similar intent across angles, combine options
const dedupedClarifications = intelligentMerge(allClarifications)

if (workflowPreferences.autoYes) {
  console.()
}   (dedupedClarifications. > ) {
    = 
   totalRounds = .(dedupedClarifications. / )

   ( i = ; i < dedupedClarifications.; i += ) {
     batch = dedupedClarifications.(i, i + )
     currentRound = .(i / ) + 
    .()

    ({
      : batch.( ({
        : ,
        : need..(, ),
        : ,
        : need..( ({
          : need. === index ?  : opt,
          : need. === index ?  : 
        }))
      }))
    })
    
  }
}

Output: clarificationContext (in-memory)

8. LP-Phase 3: Planning

IMPORTANT: LP-Phase 3 is planning only — NO code execution. All execution happens in LP-Phase 5 via workflow-lite-execute.

Executor Assignment (after plan generation):

// Priority: 1. User explicit ("用 gemini 分析..." → gemini) | 2. Default → agent
const executorAssignments = {}  // { taskId: { executor: 'gemini'|'codex'|'agent', reason } }
const taskFiles = Glob(`${sessionFolder}/.task/TASK-*.json`)
taskFiles.forEach(taskPath => {
  const task = JSON.parse(Read(taskPath))
  executorAssignments[task.id] = { executor: '...', reason: '...' }
})

Invoke cli-lite-planning-agent:

Task(
  subagent_type="cli-lite-planning-agent",
  run_in_background=false,
  description="Generate detailed implementation plan",
  prompt=`
Generate implementation plan and write plan.json.

## Output Location
**Session Folder**: ${sessionFolder}
**Output Files**:
- ${sessionFolder}/planning-context.md (evidence + understanding)
- ${sessionFolder}/plan.json (plan overview — NO embedded tasks[])
- ${sessionFolder}/.task/TASK-*.json (independent task files, one per task)

## Project Context (MANDATORY)
Execute: ccw spec load --category planning
**CRITICAL**: All generated tasks MUST comply with constraints in specs/*.md

## Task Description
${task_description}

## Multi-Angle Exploration Context

${manifest.explorations.length > 0
  ? manifest.explorations.map(exp => `### Exploration: ${exp.angle} (${exp.file})
Path: ${exp.path}
Read this file for detailed ${exp.angle} analysis.`).join('\n\n') + `

Total: ${manifest.exploration_count} | Angles: ${manifest.explorations.map(e => e.angle).join(', ')}
Manifest: ${sessionFolder}/explorations-manifest.json`
  : `No exploration files. Task Description contains "## Prior Analysis" — use as primary planning context.`}

## Structured Handoff Spec (from ${handoffSpec?.source || 'upstream workflow'})
${handoffSpec ? `
**Source**: ${handoffSpec.source} session ${handoffSpec.session_id}
**CRITICAL**: Use implementation_scope as PRIMARY input for task generation.
${isBrainstormSource ? '**NOTE**: Brainstorm source — code_anchors/key_files are empty. Use exploration results as primary file context.' : ''}
Each scope item maps to one or more tasks. Acceptance criteria become convergence.criteria.

${.stringify(handoffSpec.implementation_scope, , )}

**Code Anchors** (implementation targets):


**Key Findings** (context):


**Task Generation Rules when handoffSpec present**:
1. Each implementation_scope item → 1 task (group only if tightly coupled)
2. scope.acceptance_criteria[] → task.convergence.criteria[]
3. scope.target_files[] → task.files[] with change from scope.change_summary
4. scope.objective → task.title, scope.rationale → task.description context
5. scope.priority → task ordering (high first)
` : }

## User Clarifications


## Complexity Level


## Requirements
- _metadata.exploration_angles: 
- Two-layer output: plan.json (task_ids[], NO tasks[]) + .task/TASK-*.json
- Field names: files[].change (not modification_points), convergence.criteria (not acceptance)

## Task Grouping Rules
1. **Group by feature**: All changes for one feature = one task (even if 3-5 files)
2. **Group by context**: Related functional changes can be grouped together
3. **Minimize agent count**: Group simple unrelated tasks to reduce overhead
4. **Avoid file-per-task**: Do NOT create separate tasks for each file
5. **Substantial tasks**: Each task = 15-60 minutes of work
6. **True dependencies only**: depends_on only when Task B needs Task A's output
7. **Prefer parallel**: Most tasks should be independent

## Execution
1. ccw spec load → 2. Read ALL exploration files → 3. Synthesize + generate
4. Write: planning-context.md, .task/TASK-*.json, plan.json (task_ids[], NO tasks[])
5. Return brief completion summary
`
)

Output: ${sessionFolder}/plan.json

// TodoWrite: Phase 3 → completed, Phase 4 → in_progress

9. LP-Phase 4: Task Confirmation & Execution Selection

Display Plan:

const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
const tasks = (plan.task_ids || []).map(id => JSON.parse(Read(`${sessionFolder}/.task/${id}.json`)))

console.log(`
## Implementation Plan
**Summary**: ${plan.summary}
**Approach**: ${plan.approach}
**Tasks** (${tasks.length}):
${tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope || t.files?.[0]?.path || ''})`).join('\n')}
**Complexity**: ${plan.complexity} | **Time**: ${plan.estimated_time} | **Recommended**: ${plan.recommended_execution}
`)

Collect Confirmation:

let userSelection

if (workflowPreferences.autoYes) {
  console.log(`[Auto] Allow & Execute | Auto | Skip + Skip`)
  userSelection = { confirmation: "Allow", execution_method: "Auto", code_review_tool: "Skip", convergence_review_tool: "Skip" }
} else {
  // "Other" in Execution allows specifying CLI tools from ~/.claude/cli-tools.json
  userSelection = AskUserQuestion({
    questions: [
      {
        question: `Confirm plan and authorize execution? (${tasks.length} tasks, ${plan.complexity})`,
        header: "Confirm",
        multiSelect: false,
        options: [
          { label: "Allow & Execute", description: "Approve plan and begin execution immediately (no further prompts)" },
          { label: "Modify", description: "Adjust before execution" },
          { label: "Cancel", description: "Abort workflow" }
        ]
      },
      {
        question: "Execution method:",
        header: "Execution",
        multiSelect: false,
        options: [
          { label: , :  },
          { : , :  },
          { : , :  }
        ]
      },
      {
        : ,
        : ,
        : ,
        : [
          { : , :  },
          { : , :  },
          { : , :  },
          { : , :  }
        ]
      },
      {
        : ,
        : ,
        : ,
        : [
          { : , :  },
          { : , :  },
          { : , :  },
          { : , :  }
        ]
      }
    ]
  })
}

// TodoWrite: Phase 4 → completed [${userSelection.execution_method} | CR:${userSelection.code_review_tool} | CVR:${userSelection.convergence_review_tool}], Phase 5 → in_progress

10. LP-Phase 5: Handoff to Execution

CRITICAL: lite-plan NEVER executes code directly. ALL execution goes through workflow-lite-execute.

Build executionContext:

const manifest = file_exists(`${sessionFolder}/explorations-manifest.json`)
  ? JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
  : { exploration_count: 0, explorations: [] }
const explorations = {}
manifest.explorations.forEach(exp => {
  if (file_exists(exp.path)) explorations[exp.angle] = JSON.parse(Read(exp.path))
})

const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))

executionContext = {
  planObject: plan,
  taskFiles: (plan.task_ids || []).map(id => ({ id, path: `${sessionFolder}/.task/${id}.json` })),
  explorationsContext: explorations,
  explorationAngles: manifest.explorations.map(e => e.angle),
  explorationManifest: manifest,
  clarificationContext: clarificationContext || ,
  : userSelection.,
  : userSelection.,
  : userSelection.,
  : task_description,
  : executorAssignments,  
  : {
    : sessionId,
    : sessionFolder,
    : {
      : manifest..( ({ : exp., : exp. })),
      : ,
      : ,
      : 
    }
  }
}

Handoff:

if (!workflowPreferences.autoYes) {
  console.log(`Handing off to execution engine. No further prompts.`)
}

// TodoWrite: Phase 5 → completed, add LE-Phase 1 → in_progress
const taskCount = (plan.task_ids || []).length
TodoWrite({ todos: [
  { content: "LP-Phase 1: Exploration", status: "completed" },
  { content: "LP-Phase 2: Clarification", status: "completed" },
  { content: "LP-Phase 3: Planning", status: "completed" },
  { content: `LP-Phase 4: Confirmed [${userSelection.execution_method} | CR:${userSelection.code_review_tool} | CVR:${userSelection.convergence_review_tool}]`, status: "completed" },
  { content: `LP-Phase 5: Handoff → workflow-lite-execute`, status: "completed" },
  { content: `LE-Phase 1: Task Loading [${taskCount} tasks]`, status: "in_progress", activeForm: "Loading tasks" }
]})

Skill("workflow-lite-execute")
// executionContext passed as global variable (Mode 1: In-Memory Plan)

11. Session Folder Structure

.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
├── exploration-{angle}.json (1-4)   # Per-angle exploration
├── explorations-manifest.json        # Exploration index
├── planning-context.md               # Evidence paths + understanding
├── plan.json                         # Plan overview (task_ids[])
├── code-review.md                    # Generated by workflow-lite-execute Step 4
├── test-checklist.json               # Generated by workflow-lite-test-review
├── test-review.md                    # Generated by workflow-lite-test-review
└── .task/
    ├── TASK-001.json
    ├── TASK-002.json
    └── ...

Chain: lite-plan → workflow-lite-execute → workflow-lite-test-review

lite-plan (LP-Phase 1-5)
  └─ Skill("workflow-lite-execute")     ← executionContext (global)
       ├─ Step 1-3: Task Execution
       ├─ Step 4: Code Review (quality/correctness/security)
       └─ Step 5: Skill("workflow-lite-test-review")  ← testReviewContext (global)
            ├─ TR-Phase 1: Detect test framework
            ├─ TR-Phase 2: Convergence verification (plan criteria)
            ├─ TR-Phase 3-4: Run tests + Auto-fix
            └─ TR-Phase 5: Report + Sync specs

12. Error Handling

Error	Resolution
Exploration agent failure	Skip exploration, continue with task description only
Planning agent failure	Retry with reduced complexity or suggest breaking task
Clarification timeout	Use exploration findings as-is
Confirmation timeout	Save context, display resume instructions
Modify loop > 3 times	Suggest breaking task or using /workflow-plan

<auto_mode> When workflowPreferences.autoYes === true (entire plan+execute workflow):

• Clarification: Skipped | Plan Confirmation: Allow & Execute | Execution: Auto | Review: Skip

Auto mode authorizes the complete plan-and-execute workflow with a single confirmation. No further prompts. </auto_mode>

<success_criteria>

• Workflow preferences (autoYes, forceExplore) initialized at LP-Phase 0
• Complexity assessed and exploration angles selected appropriately
• Parallel exploration agents launched with run_in_background=false
• Explorations manifest built from auto-discovered files
• Clarification needs aggregated, deduped, and presented in batches of 4
• Plan generated via cli-lite-planning-agent
• Plan output as two-layer: plan.json (task_ids[]) + .task/TASK-*.json
• User confirmation collected (or auto-approved in auto mode)
• executionContext fully built with all artifacts and session references
• Handoff to workflow-lite-execute via Skill("workflow-lite-execute") with executionContext
• No code execution in planning phases -- all execution deferred to workflow-lite-execute </success_criteria>