planflow-ai 1.3.4 → 1.4.1

package/.claude/resources/core/wave-execution.md

@@ -0,0 +1,329 @@
+
+# Wave-Based Parallel Execution
+
+## Purpose
+
+When `wave_execution: true` in `flow/.flowconfig` (default), `/execute-plan` analyzes phase dependencies, groups independent phases into **waves**, and executes phases within each wave **in parallel** using Agent sub-agents. Waves are sequenced — Wave N+1 starts only after all Wave N phases complete. This reduces total execution time by 40-60% for plans with independent phases.
+
+**Core principle**: Dependency analysis in, parallel waves out, sequential commits after.
+
+---
+
+## Architecture
+
+```
+Coordinator (main session)
+    │
+    ├─ Step 2b: Wave Analysis
+    │   ├─ Parse Dependencies from each phase
+    │   ├─ Build dependency graph
+    │   ├─ Topological sort → group into waves
+    │   └─ Present wave summary to user
+    │
+    ├─ For each Wave:
+    │   │
+    │   ├─ Sequential: Approve each phase in Plan Mode
+    │   │
+    │   ├─ Parallel: Spawn Agent sub-agents for all wave phases
+    │   │   ├─► Agent: Phase A  (model: [tier from model routing])
+    │   │   ├─► Agent: Phase B  (model: [tier from model routing])
+    │   │   └─► Agent: Phase C  (model: [tier from model routing])
+    │   │
+    │   ├─ Collect JSON returns from all sub-agents
+    │   │
+    │   ├─ Post-wave processing:
+    │   │   ├─ Detect file conflicts (files_modified overlap)
+    │   │   ├─ Accumulate files_modified list
+    │   │   ├─ Buffer patterns from all phases
+    │   │   ├─ Git commit per-task (iterate tasks within each phase, in phase order)
+    │   │   └─ Handle failures (present to user)
+    │   │
+    │   └─ Next Wave...
+    │
+    └─ Completion summary with wave execution stats
+```
+
+Planning and user approval always happen **sequentially** in the main session. Only **implementation** is parallelized within waves.
+
+---
+
+## Dependency Analysis
+
+### Dependency Declaration Syntax
+
+Each plan phase may include an optional `**Dependencies**` field after `**Complexity**`:
+
+```markdown
+### Phase 3: API Integration
+
+**Scope**: ...
+**Complexity**: 5/10
+**Dependencies**: Phase 1, Phase 2
+
+- [ ] Task 1
+- [ ] Task 2
+```
+
+### Dependency Rules
+
+| Declaration | Meaning |
+|-------------|---------|
+| `**Dependencies**: Phase 1, Phase 3` | Phase depends on Phase 1 and Phase 3 completing first |
+| `**Dependencies**: None` | Phase has no dependencies — can run in parallel with others |
+| No `Dependencies` field | **Default**: depends on previous phase (backward-compatible sequential) |
+
+**Parsing rules**:
+1. Look for `**Dependencies**:` line in each phase section
+2. Extract phase numbers: parse `Phase N` references (case-insensitive)
+3. `None` (case-insensitive) means explicitly independent
+4. Missing field = implicit dependency on Phase N-1 (Phase 1 has no implicit dependency)
+5. Self-references are ignored
+6. References to non-existent phases are ignored with a warning
+
+### Special Rules
+
+- **Tests phase**: NEVER parallelized, regardless of dependency declaration. Always runs alone in the final wave.
+- **Phase 1**: Always in Wave 1 (no possible predecessors)
+
+---
+
+## Wave Grouping Algorithm
+
+### Topological Sort
+
+1. **Build graph**: For each phase, record its dependencies (explicit or implicit)
+2. **Assign wave numbers**:
+   - Phases with no dependencies → Wave 1
+   - For each remaining phase: wave = max(wave of each dependency) + 1
+3. **Tests phase exception**: Move to its own final wave regardless of computed wave number
+4. **Validate**: Check for circular dependencies — if found, warn user and fall back to sequential
+
+### Example
+
+Given a plan with 5 phases:
+```
+Phase 1: Types and interfaces          Dependencies: None
+Phase 2: Utility functions              Dependencies: None
+Phase 3: API integration                Dependencies: Phase 1, Phase 2
+Phase 4: Configuration updates          Dependencies: Phase 1, Phase 3
+Phase 5: Tests                          Dependencies: Phase 1, Phase 2, Phase 3, Phase 4
+```
+
+Wave grouping result:
+```
+Wave 1: Phase 1, Phase 2    (both independent)
+Wave 2: Phase 3              (depends on Wave 1 phases)
+Wave 3: Phase 4              (depends on Phase 3 in Wave 2)
+Wave 4: Phase 5              (tests — always last, alone)
+```
+
+Sequential execution: 5 phases in sequence
+Wave execution: 4 waves (Wave 1 runs 2 phases in parallel)
+Estimated speedup: ~20% (1 fewer sequential step)
+
+### Backward Compatibility
+
+Plans without any `Dependencies` fields produce a fully sequential wave plan:
+```
+Wave 1: Phase 1
+Wave 2: Phase 2
+Wave 3: Phase 3
+...
+```
+
+This matches existing behavior exactly — no regression.
+
+---
+
+## Wave Execution Summary
+
+Before execution begins, the coordinator presents the wave plan to the user:
+
+```markdown
+## Wave Execution Plan
+
+| Wave | Phases | Parallel |
+|------|--------|----------|
+| 1 | Phase 1: Types, Phase 2: Utilities | Yes (2 parallel) |
+| 2 | Phase 3: API Integration | No (1 phase) |
+| 3 | Phase 4: Config Updates | No (1 phase) |
+| 4 | Phase 5: Tests | No (always sequential) |
+
+**Sequential phases**: 5 → **Waves**: 4 → **Estimated speedup**: ~20%
+
+Proceed with wave execution? (yes/no/sequential)
+```
+
+User options:
+- **yes**: Execute with wave parallelism
+- **no**: Stop execution
+- **sequential**: Fall back to sequential execution (ignore waves)
+
+---
+
+## Parallel Spawning Rules
+
+### Sub-Agent Setup
+
+Each phase within a wave is spawned as an **independent Agent sub-agent** following the phase-isolation context template (see `phase-isolation.md` COR-PI-2). Key additions for wave execution:
+
+1. **Files Modified context**: For Wave N, include files_modified from ALL completed waves (1 through N-1), not just the previous phase
+2. **No cross-phase awareness**: Sub-agents within the same wave do NOT know about each other. They receive no information about sibling phases.
+3. **Model routing**: Each sub-agent uses the model tier from its own phase complexity score (same as phase isolation)
+
+### Spawning Pattern
+
+```
+For Wave N (phases A, B, C):
+  Launch in parallel:
+  - Agent(model: [tier_A], prompt: phase_A_context)
+  - Agent(model: [tier_B], prompt: phase_B_context)
+  - Agent(model: [tier_C], prompt: phase_C_context)
+
+  Wait for all to complete.
+  Process results sequentially.
+```
+
+This mirrors the discovery-sub-agents pattern (see `discovery-sub-agents.md` COR-DSA-3) but with phase-isolation context templates instead of exploration prompts.
+
+### Return Format
+
+Each sub-agent returns the **same JSON format** as phase isolation (see `phase-isolation.md`), including the `tasks_completed` array for per-task file tracking. The `tasks_completed` field enables the wave coordinator to create atomic per-task commits after the wave completes. See `.claude/resources/core/atomic-commits.md` for the full `tasks_completed` schema.
+
+---
+
+## Wave Coordinator Behavior
+
+### Per-Wave Processing
+
+After all sub-agents in a wave return, the coordinator processes results **sequentially in phase order**:
+
+1. **Collect returns**: Gather JSON from all sub-agents
+2. **Validate JSON**: Parse each return, check for required fields
+3. **Detect file conflicts**: Check for files_modified overlap between phases in this wave
+4. **Process each phase** (in phase number order):
+   - Update plan file (mark tasks `[x]`)
+   - Accumulate files_modified into running list
+   - Buffer patterns_captured entries
+   - Git commit per-task if enabled: iterate `tasks_completed` array and create one commit per task (`feat(phase-N.task-M): <desc> — <feature>`). See `.claude/resources/core/atomic-commits.md` for format.
+   - Log decisions and deviations
+5. **Report wave completion**: Summary of all phases in this wave, including `task_verifications` results from each phase return (display pass/fail counts and any repairs applied per phase)
+
+### File Conflict Detection
+
+After collecting all wave results, check for **files_modified overlap**:
+
+```
+For each pair of phases (A, B) in the wave:
+  overlap = A.files_modified ∩ B.files_modified
+  if overlap is not empty:
+    → File conflict detected
+```
+
+**On conflict**:
+1. Present the conflicting files and which phases modified them
+2. Offer options:
+   - **(1) Accept as-is**: Last writer wins (the phase with the higher number committed last)
+   - **(2) Re-run conflicting phases sequentially**: Re-execute only the conflicting phases in order
+   - **(3) Stop execution**: Halt for manual resolution
+
+File conflict does NOT affect non-conflicting phases — their results are preserved.
+
+### Failure Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| One phase fails, others succeed | Process successful phases normally. Present failure to user. Offer: retry failed phase, skip it, or stop. |
+| Multiple phases fail | Process any successful phases. Present all failures. Offer same options per failed phase. |
+| All phases in wave fail | Present all failures. Offer: retry wave, skip wave, or stop. |
+| Sub-agent timeout | Treat as failure for that phase. Other phases unaffected. |
+| Invalid JSON return | Treat as failure for that phase. |
+
+**Key rule**: A failed phase in a wave does NOT cancel other phases in the same wave. Parallel phases are independent — let them all complete.
+
+### Git Commit Ordering
+
+When `commit: true` in `.flowconfig`, git commits happen **after** the wave completes, **per-task in phase order then task order**:
+
+```
+Wave 1 complete:
+  Phase 1, Task 1: git add -A && git commit -m "feat(phase-1.task-1): Define user and session types — feature-name"
+  Phase 1, Task 2: git add -A && git commit -m "feat(phase-1.task-2): Create user schema with Prisma — feature-name"
+  Phase 2, Task 1: git add -A && git commit -m "feat(phase-2.task-1): Implement utility helpers — feature-name"
+  Phase 2, Task 2: git add -A && git commit -m "feat(phase-2.task-2): Add string formatting utils — feature-name"
+```
+
+The coordinator iterates each phase's `tasks_completed` array (from the JSON return) in task_number order. This ensures **deterministic, fine-grained commit history** regardless of which sub-agent finished first. See `.claude/resources/core/atomic-commits.md` for the full commit format spec.
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+```yaml
+wave_execution: true    # Enable wave-based parallel execution (default: true)
+```
+
+- `true` (default): Analyze dependencies and execute in parallel waves
+- `false`: Sequential execution (ignore Dependencies, legacy behavior)
+
+### Toggle via `/flow`
+
+```
+/flow wave_execution=true
+/flow wave_execution=false
+```
+
+### Interaction Matrix
+
+| wave_execution | phase_isolation | model_routing | Behavior |
+|---------------|-----------------|---------------|----------|
+| `true` | `true` | `true` | Full parallel: waves + isolated sub-agents + correct tier models |
+| `true` | `true` | `false` | Parallel waves + isolated sub-agents + session model |
+| `true` | `false` | `true` | Parallel waves + inline execution per phase + correct tier models |
+| `true` | `false` | `false` | Parallel waves + inline execution + session model |
+| `false` | `true` | `true` | Sequential + isolated sub-agents + correct tier models (existing behavior) |
+| `false` | `true` | `false` | Sequential + isolated sub-agents + session model |
+| `false` | `false` | `true` | Sequential + inline + correct tier models |
+| `false` | `false` | `false` | Sequential + inline + session model (original behavior) |
+
+**Note**: `wave_execution: true` requires `phase_isolation: true` for best results. Without phase isolation, parallel execution still works but sub-agents share the session context, which may cause interference.
+
+### Interaction with Aggregation
+
+When phases are aggregated (combined complexity ≤ 6), aggregated phases are treated as a **single unit** for wave analysis:
+- They share one dependency set (union of all aggregated phases' dependencies)
+- They produce one wave slot
+- They run as one sub-agent call (same as current aggregation behavior)
+
+---
+
+## Rules
+
+1. **Planning stays sequential** — approve each phase before wave execution begins
+2. **Tests never parallel** — tests phase always runs alone in the final wave
+3. **No cross-phase awareness** — sub-agents in the same wave know nothing about each other
+4. **Deterministic commits** — git commits happen sequentially in phase order after wave completes
+5. **Failures are isolated** — one failed phase does not cancel sibling phases in the same wave
+6. **Backward compatible** — plans without Dependencies fields execute sequentially (no behavior change)
+7. **User controls** — user can always choose sequential execution at the wave summary prompt
+8. **File conflicts are presented** — never silently resolve file conflicts, always ask the user
+9. **Reuse phase-isolation format** — sub-agent prompts and JSON returns follow phase-isolation.md exactly
+10. **Wave analysis is fast** — dependency parsing and topological sort add negligible overhead
+11. **Verification is internal to sub-agents** — per-task verification loops run entirely inside each phase sub-agent. The wave coordinator does not interact with verification; it only processes the final `task_verifications` field from the JSON return. See `.claude/resources/core/per-task-verification.md` for the complete verification system.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/core/phase-isolation.md` | Sub-agent context template, JSON return format, coordinator processing |
+| `.claude/resources/core/discovery-sub-agents.md` | Parallel spawning pattern (3 agents → collect → merge) |
+| `.claude/resources/core/review-multi-agent.md` | Parallel agents with deduplication |
+| `.claude/resources/core/model-routing.md` | Model tier selection per phase complexity |
+| `.claude/resources/core/complexity-scoring.md` | Complexity scores and aggregation rules |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification system, debug sub-agent, and repair loops |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill (Steps 2b, 3, 4 modified for waves) |
+| `.claude/resources/patterns/plans-templates.md` | Plan template with Dependencies field |

package/.claude/resources/patterns/plans-patterns.md

@@ -74,6 +74,7 @@ Every plan must be divided into implementation phases with clear scope boundarie
 
 - **Scope**: What this phase covers
 - **Complexity**: Score from 0-10
+- **Dependencies**: (Optional) Which phases must complete first
 - **Tasks**: Checkboxes for tracking
 - **Build Verification**: Command to verify
 
@@ -130,6 +131,48 @@ When executing a plan, each phase must trigger **Plan mode** before implementati
 
 ---
 
+### 13. Declare Phase Dependencies for Parallel Execution
+
+Phases may include an optional `**Dependencies**` field to declare which prior phases must complete before execution can begin. This enables wave-based parallel execution where independent phases run simultaneously.
+
+**Syntax**:
+
+- `**Dependencies**: None` — No dependencies; can run in the first wave
+- `**Dependencies**: Phase 1, Phase 3` — Depends on specific phases completing first
+- **Omitting the field** — Defaults to depending on the immediately previous phase (sequential)
+
+**Rules**:
+
+1. Mark phases as `Dependencies: None` when they have no data or code dependency on other phases
+2. When two or more phases share the same dependency set, they form a wave and can execute in parallel
+3. The Tests phase always depends on ALL prior phases — never mark it as `Dependencies: None`
+4. Dependencies must only reference phases with lower numbers (no forward or circular dependencies)
+5. When uncertain whether phases are independent, default to sequential (omit the field)
+6. The dependency declaration is metadata for the execution engine — it does not change the phase content
+
+**Example** — independent phases forming a parallel wave:
+
+```markdown
+### Phase 1: Types and Schemas
+**Dependencies**: None
+
+### Phase 2: API Routes
+**Dependencies**: Phase 1
+
+### Phase 3: CLI Commands
+**Dependencies**: Phase 1
+
+### Phase 4: Integration
+**Dependencies**: Phase 2, Phase 3
+
+### Phase 5: Tests (Final)
+**Dependencies**: Phase 1, Phase 2, Phase 3, Phase 4
+```
+
+Phases 2 and 3 can run in parallel (Wave 2). Phase 4 waits for both. Phase 5 waits for all.
+
+---
+
 ## Forbidden Patterns
 
 ### 1. DON'T Read or Reference Archived Plans
@@ -210,6 +253,18 @@ Keep discovery documents in `flow/discovery/` and plans in `flow/plans/`.
 
 ---
 
+### 14. DON'T Mark the Tests Phase as Independent
+
+The Tests phase must always depend on ALL prior phases. Never assign `Dependencies: None` to the Tests phase.
+
+---
+
+### 15. DON'T Create Circular or Forward Dependencies
+
+Dependencies must only reference phases with lower numbers. A phase cannot depend on itself or on any phase that comes after it.
+
+---
+
 ## Summary
 
 Following these planning patterns ensures:
@@ -223,3 +278,4 @@ Following these planning patterns ensures:
 - **Clarity**: Archived plans are ignored, only active plans are referenced
 - **Intelligent Pacing**: Complexity scores guide execution strategy
 - **Collaborative Execution**: Plan mode ensures user approval before each phase
+- **Parallel Execution**: Dependency declarations enable wave-based parallel phase execution

package/.claude/resources/patterns/plans-templates.md

@@ -51,8 +51,10 @@ Use this template when creating new implementation plans:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: None
 
 - [ ] Task 1
+  <verify>npx tsc --noEmit src/path/to/file.ts</verify>
 - [ ] Task 2
 
 **Build Verification**: Run `npm run build`
@@ -61,6 +63,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: Phase 1
 
 - [ ] Task 1
 - [ ] Task 2
@@ -71,6 +74,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: Write comprehensive tests
 **Complexity**: X/10
+**Dependencies**: Phase 1, Phase 2, ..., Phase N-1
 
 - [ ] Unit tests for logic hooks
 - [ ] Unit tests for utilities
@@ -87,6 +91,130 @@ Use this template when creating new implementation plans:
 
 ---
 
+## Dependencies Field
+
+The optional `**Dependencies**` field declares which phases must complete before a phase can start. This enables wave-based parallel execution.
+
+### Syntax
+
+- `**Dependencies**: None` — Phase has no dependencies and can run in the first wave (parallel with other independent phases)
+- `**Dependencies**: Phase 1, Phase 3` — Phase depends on Phases 1 and 3 completing first
+- **Omitting the field entirely** — Backward-compatible default; phase depends on the immediately previous phase (sequential execution)
+
+### Rules
+
+1. The Tests phase (always last) depends on ALL prior phases — it is never parallelized
+2. Phases with `Dependencies: None` form the first execution wave
+3. A phase cannot depend on itself or on phases that come after it
+4. When in doubt, omit the field to default to sequential execution
+
+### Example
+
+```markdown
+### Phase 1: Types and Schemas
+**Scope**: Define TypeScript types
+**Complexity**: 3/10
+**Dependencies**: None
+
+### Phase 2: Config Parser
+**Scope**: Implement config parsing
+**Complexity**: 4/10
+**Dependencies**: Phase 1
+
+### Phase 3: CLI Commands
+**Scope**: Implement CLI interface
+**Complexity**: 4/10
+**Dependencies**: Phase 1
+
+### Phase 4: Integration
+**Scope**: Connect all pieces
+**Complexity**: 5/10
+**Dependencies**: Phase 2, Phase 3
+
+### Phase 5: Tests (Final)
+**Scope**: Write comprehensive tests
+**Complexity**: 5/10
+**Dependencies**: Phase 1, Phase 2, Phase 3, Phase 4
+```
+
+In this example, Phases 2 and 3 can run in parallel (both only depend on Phase 1). Phase 4 waits for both 2 and 3. Phase 5 (tests) waits for everything.
+
+---
+
+## Verify Tag
+
+The optional `<verify>` tag allows tasks to include a verification command that runs immediately after the task completes. This enables early error detection — failures are caught per-task instead of waiting until the final build step.
+
+### Syntax
+
+Add a `<verify>` tag indented under a task checkbox:
+
+```markdown
+- [ ] Create type definitions in `/src/types/workflow.ts`
+  <verify>npx tsc --noEmit src/types/workflow.ts</verify>
+```
+
+The `<verify>` tag contains a single shell command that validates the task's output. The command should be **targeted** (single file or narrow scope) rather than a full build.
+
+### Rules
+
+1. **Optional**: Tasks without a `<verify>` tag skip verification entirely (backward compatible)
+2. **One command per tag**: Each `<verify>` tag contains exactly one shell command
+3. **Targeted checks only**: Use single-file or narrow-scope commands — never full builds
+4. **Indented under the task**: The `<verify>` tag must be indented under its parent task checkbox
+5. **No verify for manual-review tasks**: Config files, documentation, and other tasks requiring human judgment should omit `<verify>`
+
+### Examples
+
+**Task with verification:**
+
+```markdown
+- [ ] Create `UserProfile` type in `/src/types/user.ts`
+  <verify>npx tsc --noEmit src/types/user.ts</verify>
+- [ ] Write unit tests for user validation
+  <verify>npx jest src/types/__tests__/user.test.ts --no-coverage</verify>
+```
+
+**Task without verification (backward compatible):**
+
+```markdown
+- [ ] Update `.flowconfig` with new setting
+- [ ] Add documentation for the new feature
+```
+
+**Mixed phase (some tasks verified, some not):**
+
+```markdown
+### Phase 2: Backend Implementation
+
+**Scope**: Implement API routes and data layer.
+**Complexity**: 6/10
+**Dependencies**: Phase 1
+
+- [ ] Create API route handler in `/src/routes/workflow.ts`
+  <verify>npx tsc --noEmit src/routes/workflow.ts</verify>
+- [ ] Add database migration for `workflow_steps` table
+- [ ] Create service layer in `/src/services/workflow.ts`
+  <verify>npx tsc --noEmit src/services/workflow.ts</verify>
+
+**Build Verification**: Run `npm run build`
+```
+
+### Heuristic Reference
+
+When writing plans, use these heuristics to decide which tasks get `<verify>` tags:
+
+| Task Type | Verify Command | Example |
+|-----------|---------------|---------|
+| File creation (`.ts`) | `npx tsc --noEmit <file>` | `npx tsc --noEmit src/types/user.ts` |
+| Test writing | `npx jest <test-file> --no-coverage` | `npx jest src/__tests__/user.test.ts --no-coverage` |
+| Schema/type definition | `npx tsc --noEmit <type-file>` | `npx tsc --noEmit src/types/schema.ts` |
+| Config file changes | No verify (manual review) | — |
+| Documentation | No verify (manual review) | — |
+| Generic/ambiguous tasks | No verify (default) | — |
+
+---
+
 ## Phase Templates
 
 ### Types and Schemas Phase
@@ -96,9 +224,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Define all TypeScript types and Zod schemas needed for the feature.
 **Complexity**: 3/10
+**Dependencies**: None
 
 - [ ] Create type definitions in `/src/types/`
+  <verify>npx tsc --noEmit src/types/feature.ts</verify>
 - [ ] Create Zod validation schemas in `/src/types/rest-inputs.ts`
+  <verify>npx tsc --noEmit src/types/rest-inputs.ts</verify>
 
 **Build Verification**: Run `npm run build`
 ```
@@ -110,9 +241,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Implement API routes and commands.
 **Complexity**: 7/10
+**Dependencies**: Phase 1
 
 - [ ] Create command in `/src/commands/`
+  <verify>npx tsc --noEmit src/commands/feature.ts</verify>
 - [ ] Create API route in `/src/app/api/`
+  <verify>npx tsc --noEmit src/app/api/feature/route.ts</verify>
 - [ ] Add database operations if needed
 
 **Build Verification**: Run `npm run build`
@@ -125,8 +259,10 @@ Use this template when creating new implementation plans:
 
 **Scope**: Implement Zustand stores for state management.
 **Complexity**: 5/10
+**Dependencies**: Phase 1
 
 - [ ] Create or extend store in `/src/stores/`
+  <verify>npx tsc --noEmit src/stores/featureStore.ts</verify>
 - [ ] Add actions and selectors
 
 **Build Verification**: Run `npm run build`
@@ -139,9 +275,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Build the user interface components.
 **Complexity**: 6/10
+**Dependencies**: Phase 3
 
 - [ ] Create logic hook (`useFeatureLogic.internal.ts`)
+  <verify>npx tsc --noEmit src/components/feature/useFeatureLogic.internal.ts</verify>
 - [ ] Create view component (`index.tsx`)
+  <verify>npx tsc --noEmit src/components/feature/index.tsx</verify>
 - [ ] Follow view/logic separation pattern
 
 **Build Verification**: Run `npm run build`
@@ -154,6 +293,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: Connect all pieces and verify functionality.
 **Complexity**: 4/10
+**Dependencies**: Phase 2, Phase 4
 
 - [ ] Integrate components with pages
 - [ ] Connect to API endpoints
@@ -169,11 +309,16 @@ Use this template when creating new implementation plans:
 
 **Scope**: Write comprehensive tests for all new code.
 **Complexity**: 5/10
+**Dependencies**: Phase 1, Phase 2, Phase 3, Phase 4, Phase 5
 
 - [ ] Unit tests for logic hooks (`*.client.test.ts`)
+  <verify>npx jest src/components/feature/__tests__/useFeatureLogic.test.ts --no-coverage</verify>
 - [ ] Unit tests for utility functions
+  <verify>npx jest src/utils/__tests__/feature.test.ts --no-coverage</verify>
 - [ ] Integration tests for API routes
+  <verify>npx jest src/app/api/feature/__tests__/route.test.ts --no-coverage</verify>
 - [ ] Command tests
+  <verify>npx jest src/commands/__tests__/feature.test.ts --no-coverage</verify>
 
 **Build Verification**: Run `npm run build && npm run test`
 ```
@@ -226,4 +371,11 @@ Based on complexity scores (per `.claude/resources/core/complexity-scoring.md`):
 - **Phases 3-4**: Can be aggregated (combined complexity: 11, but cautious)
 - **Phase 5**: Can aggregate with Phase 6 if simple
 - **Phase 6**: Tests - always execute separately
+
+Based on dependency graph (when Dependencies fields are present):
+
+- **Wave 1**: Phase 1 (no dependencies)
+- **Wave 2**: Phases 2, 3 (both depend only on Phase 1 — run in parallel)
+- **Wave 3**: Phases 4, 5 (depend on earlier waves)
+- **Wave 4**: Phase 6 (Tests — always sequential, always last)
 ```

package/.claude/resources/skills/_index.md

@@ -14,6 +14,8 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 >
 > **Note**: The execute-plan skill supports **Model Routing** — automatic model selection per phase based on complexity scores (0-3 → haiku, 4-5 → sonnet, 6-10 → opus). Controlled by `model_routing` in `flow/.flowconfig`. See `.claude/resources/core/model-routing.md` for full rules.
 >
+> **Note**: The execute-plan skill supports **Wave-Based Parallel Execution** — dependency-aware grouping of independent phases into parallel waves. When `wave_execution: true` in `.flowconfig` (default), phases with explicit `Dependencies` metadata are analyzed, grouped into waves via topological sort, and executed in parallel within each wave. See `.claude/resources/core/wave-execution.md` for full rules.
+>
 > **Note**: The discovery skill also includes **Design Awareness**. During discovery, the LLM asks whether the feature involves UI work and captures structured design tokens (colors, typography, spacing) into a `## Design Context` section. During execution, these tokens are auto-injected into UI phase prompts. See `.claude/resources/core/design-awareness.md` for full rules.
 >
 > **Note**: The review-code and review-pr skills include a **Verification Pass**. After initial analysis, each finding is re-examined against surrounding code context and classified as Confirmed, Likely, or Dismissed. False positives are filtered before output. See `.claude/resources/core/review-verification.md` for full rules.
@@ -100,9 +102,9 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 | SKL-EXEC-1 | Purpose and inputs | execute-plan-skill.md | 4-100 |
 | SKL-EXEC-2 | Critical rules (build only at end, no DB commands) | execute-plan-skill.md | 18-92 |
 | SKL-EXEC-3 | Step 1: Parse the plan | execute-plan-skill.md | 103-112 |
-| SKL-EXEC-4 | Step 2: Analyze complexity and determine execution strategy | execute-plan-skill.md | 113-151 |
-| SKL-EXEC-5 | Step 3: Present execution plan summary | execute-plan-skill.md | 152-180 |
-| SKL-EXEC-6 | Step 4: Execute each phase with Plan mode | execute-plan-skill.md | 181-236 |
+| SKL-EXEC-4 | Step 2: Analyze complexity + Step 2b: Wave analysis (dependency graph, wave grouping) | execute-plan-skill.md | 113-151 |
+| SKL-EXEC-5 | Step 3: Present execution plan summary (with wave groupings and estimated speedup) | execute-plan-skill.md | 152-180 |
+| SKL-EXEC-6 | Step 4: Execute each wave (approve sequentially, spawn parallel sub-agents per wave) | execute-plan-skill.md | 181-236 |
 | SKL-EXEC-7 | Step 5: Update progress after each phase | execute-plan-skill.md | 237-249 |
 | SKL-EXEC-8 | Step 5b: Phase-boundary context check (compaction) | execute-plan-skill.md | 250-275 |
 | SKL-EXEC-9 | Step 6: Handle tests phase | execute-plan-skill.md | 277-302 |
@@ -189,9 +191,9 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 |------|-------------|
 | SKL-EXEC-2 | Need critical rules (build timing, DB commands) |
 | SKL-EXEC-3 | Parsing plan file structure |
-| SKL-EXEC-4 | Analyzing complexity and determining execution strategy |
-| SKL-EXEC-5 | Presenting execution plan summary to user |
-| SKL-EXEC-6 | Executing a phase with Plan mode |
+| SKL-EXEC-4 | Analyzing complexity, wave analysis, or determining execution strategy |
+| SKL-EXEC-5 | Presenting execution plan summary (with wave groupings) to user |
+| SKL-EXEC-6 | Executing a wave (parallel sub-agents) or single phase with Plan mode |
 | SKL-EXEC-7 | Updating progress after a phase |
 | SKL-EXEC-8 | Compacting at phase boundaries |
 | SKL-EXEC-9 | Handling the tests phase |