workflow-lite-plan

<purpose> 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. </purpose> <process> ## 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 ```javascript 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): ```javascript 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): ```javascript // 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**: ```javascript 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.key_findings?.length > 0) { task_description += `\n\n## Key Findings\n${handoffSpec.key_findings.map((f, i) => `${i+1}. ${f.point || f} (${f.confidence || 'medium'})`).join('\n')}` } if (handoffSpec.decision_context?.length > 0) { task_description += `\n\n## Decision Context\n${handoffSpec.decision_context.map(d => `- **${d.decision || d}**: ${d.reason || ''}`).join('\n')}` } if (handoffSpec.code_anchors?.length > 0) { task_description += `\n\n## Code Anchors\n${handoffSpec.code_anchors.slice(0, 10).map(a => `- \`${a.file}:${a.lines}\`: ${a.significance}`).join('\n')}` } } } // Brainstorm handoff has no code_anchors/key_files — needs exploration for implementation context const isBrainstormSource = handoffSpec?.source === 'brainstorm-with-file' const isAnalysisSource = handoffSpec?.source === 'analyze-with-file' needsExploration = workflowPreferences.forceExplore ? true : isBrainstormSource ? true // brainstorm explore is lightweight, lite-plan needs deeper exploration : (hasPriorAnalysis || isAnalysisSource) ? false : (task.mentions_specific_files || task.requires_codebase_context || task.needs_architecture_understanding || task.modifies_existing_code) if (!needsExploration) { // Bridge: Build manifest from analyze session's exploration artifacts if (isAnalysisSource && handoffSpec?.exploration_artifacts) { const artifacts = handoffSpec.exploration_artifacts const explorationEntries = [] let idx = 1 const artifactMapping = [ { key: 'exploration_codebase', angle: 'codebase-discovery' }, { key: 'explorations', angle: 'analysis-findings' }, { key: 'perspectives', angle: 'multi-perspective' }, { key: 'research', angle: 'external-research' } ] artifactMapping.forEach(({ key, angle }) => { if (artifacts[key] && file_exists(artifacts[key])) { explorationEntries.push({ angle, file: artifacts[key].split('/').pop(), path: artifacts[key], source_schema: 'analyze', index: idx++ }) } }) if (artifacts.deep_dives?.length > 0) { artifacts.deep_dives.forEach(divePath => { if (file_exists(divePath)) { const name = divePath.match(/explorations\/(.+)\.json$/)?.[1] || `deep-dive-${idx}` explorationEntries.push({ angle: name, file: `${name}.json`, path: divePath, source_schema: 'analyze', index: idx++ }) } }) } if (explorationEntries.length > 0) { Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify({ session_id: sessionId, task_description, timestamp: getUtc8ISOString(), complexity, exploration_count: explorationEntries.length, source: 'analyze-with-file', source_session: handoffSpec.session_id, explorations: explorationEntries }, null, 2)) console.log(`[Analyze Bridge] ${explorationEntries.length} artifacts from ${handoffSpec.session_id}`) } } // If no manifest built; LP-Phase 3 loads with safe fallback proceed_to_next_phase() } ``` **Context Protection**: File reading >=50k chars → force `needsExploration=true` (delegate to cli-explore-agent) **Complexity Assessment**: ```javascript 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' else if (/security|auth|permission|access/.test(text)) preset = 'security' else if (/performance|slow|optimi|cache/.test(text)) preset = 'performance' else if (/fix|bug|error|issue|broken/.test(text)) preset = 'bugfix' return ANGLE_PRESETS[preset].slice(0, count) } const selectedAngles = selectAngles(task_description, complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1)) console.log(`Exploration Plan: ${complexity} | ${selectedAngles.join(', ')} | cli-lite-planning-agent`) ``` **Launch Parallel Explorations**: **CRITICAL**: MUST NOT use `run_in_background: true` — exploration results are REQUIRED before planning. ```javascript 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