workflow-lite-plan

## Auto Mode When `--yes` or `-y`: Auto-confirm decomposition, skip interactive validation, use defaults. # Workflow Lite Planex ## Usage ```bash $workflow-lite-plan "Implement user authentication with OAuth, JWT, and 2FA" $workflow-lite-plan -c 4 "Refactor payment module with Stripe and PayPal" $workflow-lite-plan -y "Build notification system with email and SMS" $workflow-lite-plan --continue "auth-20260228" ``` **Flags**: - `-y, --yes`: Skip all confirmations (auto mode) - `-c, --concurrency N`: Max concurrent agents within each wave (default: 4) - `--continue`: Resume existing session **Output Directory**: `.workflow/.lite-plan/{session-id}/` --- ## Overview Explore-first wave-based pipeline using `spawn_agents_on_csv`. Two-stage CSV execution: **explore.csv** (codebase discovery) → **tasks.csv** (implementation), with cross-phase context propagation via `context_from` linking (`E*` → `T*`). **Core workflow**: Decompose → **[Confirm]** → Wave Explore → Synthesize & Plan → **[Confirm]** → Wave Execute → Aggregate ``` ┌──────────────────────────────────────────────────────────────────────┐ │ WORKFLOW LITE PLANEX │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: Requirement → explore.csv │ │ ├─ Analyze complexity → select exploration angles (1-4) │ │ ├─ Generate explore.csv (1 row per angle) │ │ └─ ⛔ MANDATORY: User validates (skip ONLY if -y) │ │ │ │ Phase 2: Wave Explore (spawn_agents_on_csv) │ │ ├─ For each explore wave: │ │ │ ├─ Build wave CSV from explore.csv │ │ │ ├─ spawn_agents_on_csv(explore instruction template) │ │ │ └─ Merge findings/key_files into explore.csv │ │ └─ discoveries.ndjson shared across agents │ │ │ │ Phase 3: Synthesize & Plan → tasks.csv │ │ ├─ Read all explore findings → cross-reference │ │ ├─ Resolve conflicts between angles │ │ ├─ Decompose into execution tasks with context_from: E*;T* │ │ ├─ Compute dependency waves (topological sort) │ │ └─ ⛔ MANDATORY: User validates (skip ONLY if -y) │ │ │ │ Phase 4: Wave Execute (spawn_agents_on_csv) │ │ ├─ For each task wave: │ │ │ ├─ Build prev_context from explore.csv + tasks.csv │ │ │ ├─ Build wave CSV with prev_context column │ │ │ ├─ spawn_agents_on_csv(execute instruction template) │ │ │ └─ Merge results into tasks.csv │ │ └─ discoveries.ndjson carries across all waves │ │ │ │ Phase 5: Aggregate │ │ ├─ Export results.csv │ │ ├─ Generate context.md with all findings │ │ └─ Display summary │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` --- ## Context Flow ``` explore.csv tasks.csv ┌──────────┐ ┌──────────┐ │ E1: arch │──────────→│ T1: setup│ context_from: E1;E2 │ findings │ │ prev_ctx │← E1+E2 findings ├──────────┤ ├──────────┤ │ E2: deps │──────────→│ T2: impl │ context_from: E1;T1 │ findings │ │ prev_ctx │← E1+T1 findings ├──────────┤ ├──────────┤ │ E3: test │──┐ ┌───→│ T3: test │ context_from: E3;T2 │ findings │ └───┘ │ prev_ctx │← E3+T2 findings └──────────┘ └──────────┘ Two context channels: 1. Directed: context_from → prev_context (CSV findings lookup) 2. Broadcast: discoveries.ndjson (append-only shared board) context_from prefix: E* → explore.csv lookup, T* → tasks.csv lookup ``` --- ## CSV Schemas ### explore.csv ```csv id,angle,description,focus,deps,wave,status,findings,key_files,error "E1","architecture","Explore codebase architecture for: auth system","architecture","","1","pending","","","" "E2","dependencies","Explore dependency landscape for: auth system","dependencies","","1","pending","","","" "E3","testing","Explore test infrastructure for: auth system","testing","","1","pending","","","" ``` **Columns**: | Column | Phase | Description | |--------|-------|-------------| | `id` | Input | Exploration ID: E1, E2, ... | | `angle` | Input | Exploration angle name | | `description` | Input | What to explore from this angle | | `focus` | Input | Keywords and focus areas | | `deps` | Input | Semicolon-separated dep IDs (usually empty — all wave 1) | | `wave` | Computed | Wave number (usually 1 for all explorations) | | `status` | Output | `pending` → `completed` / `failed` | | `findings` | Output | Discoveries (max 800 chars) | | `key_files` | Output | Relevant files (semicolon-separated) | | `error` | Output | Error message if failed | ### tasks.csv ```csv id,title,description,test,acceptance_criteria,scope,hints,execution_directives,deps,context_from,wave,status,findings,files_modified,tests_passed,acceptance_met,error "T1","Setup types","Create type definitions","Verify types compile with tsc","All interfaces exported","src/types/**","Follow existing patterns || src/types/index.ts","tsc --noEmit","","E1;E2","1","pending","","","","","" "T2","Implement core","Implement core auth logic","Unit test: login returns token","Login flow works end-to-end","src/auth/**","Reuse BaseService || src/services/Base.ts","npm test -- --grep auth","T1","E1;E2;T1","2","pending","","","","","" ``` **Columns**: | Column | Phase | Description | |--------|-------|-------------| | `id` | Input | Task ID: T1, T2, ... | | `title` | Input | Short task title | | `description` | Input | Self-contained task description — what to implement | | `test` | Input | Test cases: what tests to write and how to verify (unit/integration/edge) | | `acceptance_criteria` | Input | Measurable conditions that define "done" | | `scope` | Input | Target file/directory glob — constrains agent write area, prevents cross-task file conflicts | | `hints` | Input | Implementation tips + reference files. Format: `tips text \|\| file1;file2`. Either part is optional | | `execution_directives` | Input | Execution constraints: commands to run for verification, tool restrictions | | `deps` | Input | Dependency task IDs: T1;T2 (semicolon-separated) | | `context_from` | Input | Context source IDs: **E1;E2;T1** — `E*` lookups in explore.csv, `T*` in tasks.csv | | `wave` | Computed | Wave number (computed by topological sort, 1-based) | | `status` | Output | `pending` → `completed` / `failed` / `skipped` | | `findings` | Output | Execution findings (max 500 chars) | | `files_modified` | Output | Semicolon-separated file paths | | `tests_passed` | Output | Whether all defined test cases passed (true/false) | | `acceptance_met` | Output | Summary of which acceptance criteria were met/unmet | | `error` | Output | Error message if failed (empty if success) | ### Per-Wave CSV (Temporary) Each wave generates a temporary CSV with an extra `prev_context` column. **Explore wave**: `explore-wave-{N}.csv` — same columns as explore.csv (no prev_context, explorations are independent). **Execute wave**: `task-wave-{N}.csv` — all task columns + `prev_context`: ```csv id,title,description,test,acceptance_criteria,scope,hints,execution_directives,deps,context_from,wave,prev_context "T2","Implement core","Implement core auth logic","Unit test: login returns token","Login flow works end-to-end","src/auth/**","Reuse BaseService || src/services/Base.ts","npm test -- --grep auth","T1","E1;E2;T1","2","[Explore architecture] Found BaseService pattern in src/services/\n[Task T1] Created types at src/types/auth.ts" ``` The `prev_context` column is built from `context_from` by looking up completed rows' `findings` in both explore.csv (`E*`) and tasks.csv (`T*`). --- ## Output Artifacts | File | Purpose | Lifecycle | |------|---------|-----------| | `explore.csv` | Exploration state — angles with findings/key_files | Updated after Phase 2 | | `tasks.csv` | Execution state — tasks with results | Updated after each wave in Phase 4 | | `explore-wave-{N}.csv` | Per-wave explore input (temporary) | Created before wave, deleted after | | `task-wave-{N}.csv` | Per-wave execute input (temporary) | Created before wave, deleted after | | `results.csv` | Final results export | Created in Phase 5 | | `discoveries.ndjson` | Shared discovery board (all agents, all phases) | Append-only | | `context.md` | Human-readable execution report | Created in Phase 5 | --- ## Session Structure ``` .workflow/.lite-plan/{session-id}/ ├── explore.csv # Exploration state ├── tasks.csv # Execution state ├── results.csv # Final results export ├── discoveries.ndjson # Shared discovery board ├── context.md # Full context summary ├── explore-wave-{N}.csv # Temporary per-wave explore input (cleaned up) └── task-wave-{N}.csv # Temporary per-wave execute input (cleaned up) ``` --- ## Implementation ### Session Initialization ```javascript const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() // Parse flags const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') const continueMode = $ARGUMENTS.includes('--continue') const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/) const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 4 const requirement = $ARGUMENTS .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '') .trim() const slug = requirement.toLowerCase() .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-') .substring(0, 40) const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '') const sessionId = `wpp-${dateStr}-${slug}` const sessionFolder = `.workflow/.lite-plan/${sessionId}` // Continue mode: find existing session if (continueMode) { const existing = Bash(`ls -t .workflow/.lite-plan/ 2>/dev/null | head -1`).trim() if (existing) { sessionId = existing sessionFolder = `.workflow/.lite-plan/${sessionId}` // Check which phase to resume: if tasks.csv exists → Phase 4, else → Phase 2 } } Bash(`mkdir -p ${sessionFolder}`) ``` --- ### Phase 1: Requirement → explore.csv **Objective**: Analyze requirement complexity, select exploration angles, generate explore.csv. **Steps**: 1. **Analyze & Decompose** ```javascript Bash({ command: `ccw cli -p "PURPOSE: Analyze requirement complexity and select 1-4 exploration angles for codebase discovery before implementation. TASK: • Classify requirement type (feature/bugfix/refactor/security/performance) • Assess complexity (Low: 1 angle, Medium: 2-3, High: 3-4) • Select exploration angles from: architecture, dependencies, integration-points, testing, patterns, security, performance, state-management, error-handling, edge-cases • For each angle, define focus keywords and what to discover MODE: analysis CONTEXT: @**/* EXPECTED: JSON object: {type: string, complexity: string, angles: [{id: string, angle: string, description: string, focus: string}]}. Each angle id = E1, E2, etc. CONSTRAINTS: 1-4 angles | Angles must be distinct | Each angle must have clear focus REQUIREMENT: ${requirement}" --tool gemini --mode analysis --rule planning-breakdown-task-steps`, run_in_background: true }) // Wait for CLI completion via hook callback // Parse JSON from CLI output → { type, complexity, angles[] } ``` 2. **Generate explore.csv** ```javascript const header = 'id,angle,description,focus,deps,wave,status,findings,key_files,error' const rows = angles.map(a => [a.id, a.angle, a.description, a.focus, '', '1', 'pending', '', '', ''] .map(v => `"${String(v).replace(/"/g, '""')}"`) .join(',') ) Write(`${sessionFolder}/explore.csv`, [header, ...rows].join('\n')) ``` 3. **User Validation — MANDATORY CONFIRMATION GATE** (skip ONLY if AUTO_YES)