planflow-ai 1.3.5 → 1.4.3

package/.claude/resources/skills/execute-plan-skill.md

@@ -9,6 +9,7 @@ This skill **implements the plan** by:
 
 - Reading and parsing the plan file
 - Grouping phases by complexity
+- Analyzing dependencies and grouping into parallel waves (when enabled)
 - Switching to Plan mode for each phase
 - Implementing after user approval
 - Updating progress in the plan file
@@ -149,9 +150,41 @@ Execution Groups:
 
 ---
 
+### Step 2b: Wave Analysis (Wave Execution)
+
+**Condition**: Only run this step when `wave_execution` is `true` in `flow/.flowconfig` (default: `true`). If `wave_execution` is `false` or the key is missing, skip entirely — proceed to Step 3 with sequential grouping only.
+
+Read `.claude/resources/core/wave-execution.md` for the full system reference.
+
+1. **Parse Dependencies**: For each phase, look for a `**Dependencies**:` line:
+   - `Phase 1, Phase 3` → depends on those phases completing first
+   - `None` → explicitly independent, can run in Wave 1 (if no other constraints)
+   - Missing field → implicit dependency on Phase N-1 (Phase 1 has no implicit dependency)
+   - Self-references and references to non-existent phases are ignored (warn on non-existent)
+
+2. **Build dependency graph**: Map each phase to its dependency set (after applying defaults).
+
+3. **Topological sort → assign wave numbers**:
+   - Phases with no dependencies → Wave 1
+   - For each remaining phase: `wave = max(wave of each dependency) + 1`
+   - Tests phase exception: Move to its own final wave regardless of computed wave number
+   - On circular dependency: warn user and **fall back to sequential execution**
+
+4. **Apply aggregation to waves**: If phases within the same wave are adjacent and their combined complexity ≤ 6, aggregate them into a single sub-agent call (same aggregation rules as Step 2). Aggregated phases share one wave slot and one dependency set (union of all their dependencies).
+
+5. **Estimate speedup**: Compare number of sequential phases vs number of waves.
+
+6. **Store wave plan** for use in Steps 3 and 4.
+
+**Backward compatibility**: Plans without any `Dependencies` fields produce a fully sequential wave plan (one phase per wave). This matches existing behavior exactly — no regression.
+
+---
+
 ### Step 3: Present Execution Plan Summary
 
-Before starting, present the execution plan to the user:
+Before starting, present the execution plan to the user.
+
+**When wave execution is disabled** (or wave plan is fully sequential), present the standard summary:
 
 ```markdown
 ## Execution Plan Summary
@@ -174,6 +207,36 @@ Before starting, present the execution plan to the user:
 Ready to begin execution?
 ```
 
+**When wave execution is enabled** and the wave plan contains at least one wave with multiple phases, present the wave execution summary:
+
+```markdown
+## Execution Plan Summary
+
+**Plan**: [Plan Name]
+**Total Phases**: X
+**Total Complexity**: XX/XX
+**Execution Mode**: Wave-based parallel
+
+### 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%
+**Build Verification**: Only at the end, after ALL phases complete
+
+Proceed with wave execution? (yes/no/sequential)
+```
+
+User response options for wave execution:
+- **yes**: Execute with wave parallelism
+- **no**: Stop execution
+- **sequential**: Fall back to sequential execution (ignore waves, use standard Step 4)
+
 Wait for user confirmation before proceeding.
 
 ---
@@ -184,6 +247,8 @@ Wait for user confirmation before proceeding.
 
 **REMINDER**: Do NOT run `npm run build` between phases.
 
+#### Step 4 — Sequential Mode (default, or when wave_execution is disabled)
+
 **For Each Phase**:
 
 1. **Auto-switch to Plan mode** - Call `SwitchMode` tool
@@ -206,10 +271,156 @@ Wait for user confirmation before proceeding.
    - Append `patterns_captured` entries to `flow/resources/pending-patterns.md`
    - Log `decisions` in phase completion message
    - If inline mode (no isolation), capture patterns directly per `.claude/resources/core/pattern-capture.md`
+   - **Process task verifications** (if `task_verifications` array is present in the return):
+     - Count pass/fail totals and sum repairs applied
+     - Display a brief verification summary after the phase completion message:
+       ```
+       Task Verification: X/Y passed | Z repairs applied
+       ```
+     - If any task verification has `status: "fail"`, present each failed task with its last diagnosis and offer options:
+       ```
+       ⚠️ Task verification failed after N retries:
+       **Task**: <task description>
+       **Command**: <verify command>
+       **Last diagnosis**: <root_cause from last_diagnosis>
+       **Category**: <category from last_diagnosis>
+
+       Options:
+       1. Continue with remaining phases (issue noted)
+       2. Stop and fix manually
+       ```
 8. **Update progress** - Mark tasks complete in plan file
+   - **Note**: Sub-agent creates per-task commits directly (if `commit: true`). Coordinator does NOT create a phase-level commit. See `.claude/resources/core/atomic-commits.md` for commit format: `feat(phase-N.task-M): <desc> — <feature>`
 9. **Record model used** - Track which model tier was used for this phase (for the completion summary)
 10. **Continue to next phase** - NO BUILD between phases
 
+#### Step 4 — Wave Mode (when wave_execution is enabled and user chose "yes")
+
+Execute phases **wave by wave**. Within each wave, approve phases sequentially in Plan Mode, then spawn all wave phases as parallel Agent sub-agents.
+
+**For Each Wave**:
+
+##### 4a. Sequential Approval (Plan Mode)
+
+For each phase in the current wave (in phase number order):
+
+1. **Auto-switch to Plan mode** - Call `SwitchMode` tool
+2. **Present phase details** - Show scope, tasks, approach, and wave context (e.g., "Wave 2 of 4, running in parallel with Phase 5")
+3. **Wait for approval** - Get user confirmation
+4. **Select model tier** - Same rules as sequential mode (step 4.4 above)
+5. **Inject design context** - Same rules as sequential mode (step 4.5 above)
+
+After ALL phases in the wave are approved, proceed to parallel spawning.
+
+##### 4b. Parallel Spawning
+
+Launch all approved wave phases simultaneously as independent Agent sub-agents:
+
+1. **Prepare context for each phase**: Use the phase-isolation context template (see `.claude/resources/core/phase-isolation.md`). Key addition for wave execution: the `Files Modified in Previous Phases` section includes files from ALL completed waves (1 through N-1), not just the immediately preceding phase.
+2. **Inject shared context from sibling phases** (multi-phase waves only):
+   - Skip this step for single-phase waves (no siblings to share with)
+   - Read `flow/.wave-context.jsonl` (create it if it doesn't exist yet — see wave lifecycle below)
+   - Filter entries: include only entries from OTHER phases in the current wave (not the agent's own phase). Also include entries from all previous waves.
+   - If there are matching entries, add an inline section in the sub-agent prompt after the phase spec:
+     ```
+     ## Shared Context from Sibling Phases
+
+     The following context entries were published by other phases. Use them to align on shared contracts, types, and architectural decisions.
+
+     - [phase N] (type: contract) name: UserAPI, signature: GET /users → { id, name, email }
+     - [phase N] (type: type_definition) name: UserRecord, fields: { id: string, name: string }
+     - [phase N] (type: decision) summary: Using Redis for session caching
+     ```
+   - If no matching entries exist, omit the section entirely
+3. **Spawn all in parallel**: Launch all wave phases simultaneously using Agent sub-agents with their respective model tiers.
+4. **Wait for all to complete**: All sub-agents must return before post-wave processing.
+
+**Wave context lifecycle**:
+- **Create** `flow/.wave-context.jsonl` at wave start (before first spawn in Step 4b), if it does not already exist. Start with an empty file.
+- Context entries **accumulate across all waves** — the file is NOT cleared between waves. Later waves benefit from contracts and decisions published by earlier waves.
+- **Delete** `flow/.wave-context.jsonl` after execution completes (Step 7, after build/test verification).
+
+##### 4c. Wave Coordinator — Post-Wave Processing
+
+After all sub-agents in the wave return, process results **sequentially in phase number order**:
+
+1. **Collect JSON returns**: Gather the structured JSON summary from each sub-agent
+2. **Validate JSON**: Parse each return, check for required fields (status, phase, summary, files_created, files_modified)
+3. **Collect context entries**: For each phase's JSON return, check for a `context_entries` array:
+   - If `context_entries` is present and non-empty, append each entry to `flow/.wave-context.jsonl` (one JSON object per line)
+   - If `context_entries` is absent or empty, treat as empty array — no entries to append
+   - Entry format: `{"phase": N, "type": "contract|type_definition|decision", "name": "...", "signature": "...", "fields": "...", "summary": "..."}`
+   - These entries become available to phases in subsequent waves via Step 4b
+4. **Detect file conflicts**: Check for `files_modified` overlap between phases in this wave:
+   - For each pair of phases (A, B) in the wave: compute `overlap = A.files_modified ∩ B.files_modified`
+   - If overlap is not empty → file conflict detected
+5. **Handle file conflicts** (if any):
+   - Present the conflicting files and which phases modified them
+   - 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 conflicts do NOT affect non-conflicting phases — their results are preserved
+6. **Detect contract conflicts**: For each pair of phases (A, B) in the wave, check their `context_entries` for contract entries with the same `name` but different `signature` or `fields`:
+   - Compare all entries where `type` is `contract` or `type_definition`
+   - If same `name` but different `signature`/`fields` → contract conflict detected
+   - Present conflicts and offer resolution (see Contract Conflicts below)
+   - Contract conflicts do NOT affect non-conflicting phases — their results are preserved
+7. **Process each phase** (in phase number order):
+   - Check `status` field: `success` → continue; `failure` → present errors, ask retry/skip/stop; `partial` → present deviations, ask user
+   - Update plan file (mark tasks `[x]`)
+   - Accumulate `files_created` and `files_modified` into running list
+   - Buffer `patterns_captured` entries to `flow/resources/pending-patterns.md`
+   - Git commit if enabled (sequential, one commit **per task** in phase/task order — see `.claude/resources/core/atomic-commits.md`). For each phase (in phase number order), iterate `tasks_completed` and commit: `git add -A && git commit -m "feat(phase-N.task-M): <desc> — <feature>"`
+   - Log `decisions` in phase completion message
+
+##### Contract Conflicts
+
+If contract conflicts are detected (same API name, different signatures):
+
+1. Present both versions:
+   ```
+   Warning: Contract conflict detected:
+   **API**: GET /users
+
+   Phase 1 signature: GET /users → { id: string, name: string }
+   Phase 3 signature: GET /users → { id: string, name: string, email: string }
+
+   Options:
+   1. Use Phase 1's version
+   2. Use Phase 3's version
+   3. Stop execution for manual resolution
+   ```
+2. Apply the chosen version: update the corresponding entry in `flow/.wave-context.jsonl` so subsequent waves see the resolved contract
+3. Contract conflicts do NOT affect non-conflicting phases — only the conflicting contract entries need resolution
+
+8. **Report wave completion**: Present summary of all phases in this wave, including task verification stats:
+   - For each phase in the wave that returned `task_verifications`, include pass/fail counts and repairs applied
+   - Wave completion report template:
+     ```
+     Wave N complete: X phases finished
+     - Phase A: success (Task Verification: 3/3 passed | 1 repair applied)
+     - Phase B: success (no verifications)
+     - Phase C: partial (Task Verification: 2/3 passed, 1 failed | 0 repairs applied)
+     ```
+   - If any task verification failed, display the failed task details (same format as sequential mode step 7)
+
+##### 4d. Wave 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.
+
+##### 4e. Continue to Next Wave
+
+After post-wave processing is complete (all commits done, failures handled), proceed to the next wave. Repeat from Step 4a.
+
 **Phase Presentation Template**:
 
 ```markdown
@@ -218,6 +429,8 @@ Wait for user confirmation before proceeding.
 **Complexity**: X/10
 **Scope**: [Phase scope description]
 **Design Context**: Available / Not applicable
+**Wave**: [Wave N of M] / [Sequential]
+**Parallel with**: [Phase Y, Phase Z] / [None]
 
 ### Tasks to Complete:
 - [ ] Task 1
@@ -240,6 +453,20 @@ Wait for user confirmation before proceeding.
 
 ---
 
+### Step 4f: STATE.md Phase Lifecycle Updates
+
+Update `flow/STATE.md` at each phase transition to enable session resumability:
+
+1. **Before phase starts**: Update `Current Phase: {N} — {Phase Name}`, `Current Task: first task`, `Next Action: Implement phase {N}`
+2. **During phase** (inline mode only): Update `Current Task` as tasks progress; append decisions/blockers as they occur
+3. **After phase completes**: Append to `Completed Phases`: `Phase N: Name — {outcome}`. Set `Current Phase: none`, `Current Task: none`. Append new files to `Files Modified`. Set `Next Action: Begin phase {N+1}` (or `Run build verification` if last phase)
+4. **On phase failure**: Append to `Blockers`: `Phase {N} failed: {error} (status: open, tried: {attempts})`
+5. **Wave mode**: Update STATE.md once before each wave (set current wave phases) and once after each wave completes (batch-update completed phases)
+
+**Important**: In isolation mode, the coordinator (main session) handles STATE.md updates — sub-agents do not write to STATE.md.
+
+---
+
 ### Step 5: Update Progress After Each Phase
 
 Mark completed tasks in the plan file:
@@ -251,6 +478,8 @@ Mark completed tasks in the plan file:
 
 Then continue to the next phase (NO BUILD HERE).
 
+**Note**: In wave mode, progress updates happen during post-wave processing (Step 4c.5) rather than after each individual phase spawn. The coordinator handles updates sequentially in phase order after all wave sub-agents return.
+
 ---
 
 ### Step 5b: Phase-Boundary Context Check
@@ -262,16 +491,19 @@ Then continue to the next phase (NO BUILD HERE).
 - Multiple phases completed and more remain
 - You're about to start a complex phase (complexity >= 6)
 
+**In wave mode**: Compact at **wave boundaries** (between waves), not between phases within a wave. Include wave progress in the compact summary.
+
 **How to compact at a phase boundary**:
 
 Run `/compact` with instructions that preserve execution state:
 
 ```
-/compact Executing plan: [plan file path]. Completed phases: [list]. Next phase: [name and scope]. Key files modified: [list]. Active tasklist items: [list from flow/tasklist.md]. Resume execution from phase [N].
+/compact Executing plan: [plan file path]. Completed phases: [list]. Completed waves: [N of M]. Next wave: [wave N, phases: list]. Key files modified: [list]. Active tasklist items: [list from flow/tasklist.md]. Resume execution from wave [N] / phase [N].
 ```
 
 **Rules**:
 - NEVER compact mid-phase — only at phase boundaries (between phases)
+- In wave mode, NEVER compact mid-wave — only at wave boundaries (between waves)
 - Always include enough context in the compact instructions to resume
 - After compaction, re-read the plan file and continue from the next phase
 - In autopilot mode, compact automatically without asking — this is a maintenance action, not a user decision
@@ -291,6 +523,8 @@ The Tests phase is **always executed separately**, regardless of complexity scor
 5. Implement tests
 6. **DO NOT run tests yet** - Continue to Step 7
 
+**Wave mode note**: The tests phase always runs alone in its own final wave. This is enforced during wave analysis (Step 2b.3) — the tests phase is moved to a dedicated final wave regardless of its computed wave number.
+
 ---
 
 ### Step 7b: Pattern Review
@@ -304,6 +538,82 @@ After all phases are complete but **before** build/test verification, run the pa
 
 See `.claude/resources/core/pattern-capture.md` for the full end-of-skill review protocol.
 
+### Step 7c: Auto-PR Creation
+
+After pattern review completes, optionally create and push a Pull Request if enabled:
+
+1. **Check if PR creation is enabled**: Read `flow/.flowconfig` and look for `pr: true`
+   - If `pr` is not set or is `false`, skip this entire step
+   - If `pr: true`, proceed to branch creation
+
+2. **Create and push feature branch**:
+   - Sanitize feature name: Convert plan name to lowercase, replace spaces and special characters (except hyphens) with hyphens, trim leading/trailing hyphens
+   - Example: "Add User Authentication" → `add-user-authentication`, "Feature (WIP)" → `feature-wip`
+   - Create branch: `git checkout -b feat/<sanitized-feature-name>`
+   - Check for pre-existing branch: If the branch already exists, warn the user and skip branch creation — proceed with PR creation using the existing branch
+   - Push branch: `git push -u origin feat/<sanitized-feature-name>`
+
+3. **Determine base branch**:
+   - Read `flow/.flowconfig` and check for `branch` setting
+   - If `branch` is set, use that as the base branch
+   - If `branch` is not set, detect the repository's default branch:
+     ```bash
+     gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'
+     ```
+   - If `gh` CLI is not found or the command fails, default to `main`
+
+4. **Create Pull Request**:
+   - Title format: `feat: <plan-name>` (use the plan's name from the plan file)
+   - Body format: Include plan overview and list of completed phases:
+     ```markdown
+     ## Overview
+     <Summary of the plan>
+
+     ## Completed Phases
+     - Phase 1: <Phase Name>
+     - Phase 2: <Phase Name>
+     - Phase 3: <Phase Name>
+     ```
+   - Command:
+     ```bash
+     gh pr create --base <base-branch> --head feat/<sanitized-feature-name> --title "feat: <plan-name>" --body "<body>"
+     ```
+   - Capture the PR URL from the command output (format: `https://github.com/<owner>/<repo>/pull/<number>`)
+
+5. **Handle PR creation errors gracefully**:
+   - If `gh` CLI is not found or not installed, warn the user: `⚠️ GitHub CLI (gh) not found. Please create a PR manually: git push -u origin feat/<branch-name>`
+   - If `gh pr create` fails with any error, warn the user with the error message and continue: `⚠️ Failed to create PR: <error message>. You can create it manually on GitHub.`
+   - This is a best-effort feature — do not block execution if PR creation fails
+
+6. **Store PR URL**: If PR is created successfully, store the URL for use in Step 7 completion summary
+
+**Branch Naming Convention**:
+
+Feature branches follow the pattern: `feat/<sanitized-feature-name>`
+
+Sanitization rules:
+- Convert to lowercase
+- Replace spaces with hyphens
+- Replace special characters (`/`, `\`, `.`, `@`, etc.) with hyphens (except leading/trailing)
+- Collapse consecutive hyphens into a single hyphen
+- Trim leading and trailing hyphens
+- Result must be a valid git branch name
+
+**PR Metadata**:
+
+- **Title**: `feat: <plan-name>` — descriptive, follows conventional commits
+- **Body**: Structured markdown with Overview and Completed Phases sections
+- **Base branch**: Either from `.flowconfig` `branch` setting or detected default
+- **Head branch**: `feat/<sanitized-feature-name>`
+
+**Notification Enrichment**:
+
+When a PR is successfully created, the completion notification event message should be enriched with the PR URL:
+- Without PR: `"All done — plan execution complete"`
+- With PR: `"All done — PR: https://github.com/owner/repo/pull/123"`
+
+This allows users to quickly jump to the PR from notifications without needing to search for it.
+
 ---
 
 ### Step 7: Completion - Build and Test Verification
@@ -312,33 +622,65 @@ See `.claude/resources/core/pattern-capture.md` for the full end-of-skill review
 
 After ALL phases are complete (including Tests phase):
 
-1. **Run final verification**:
+1. **Clean up shared context**: If `flow/.wave-context.jsonl` exists, delete it. This file is ephemeral and should not persist after execution completes.
+
+2. **Run final verification**:
 
 ```bash
 npm run build && npm run test
 ```
 
-2. **Handle failures**:
+3. **Handle failures**:
    - If build fails: Fix the issue, re-run verification
    - If tests fail: Fix the issue, re-run verification
    - Only proceed after everything passes
 
-3. **Present summary** of completed work, including model routing info if enabled:
+4. **Present summary** of completed work, including model routing and wave execution info if enabled:
+
+**Sequential mode summary**:
 
 ```markdown
-| Phase | Complexity | Model | Status |
-|-------|-----------|-------|--------|
-| 1. Setup types | 2/10 | haiku | Done |
-| 2. Core logic | 5/10 | sonnet | Done |
-| 3. Integration | 7/10 | opus | Done |
-| 4. Tests | 4/10 | sonnet | Done |
+| Phase | Complexity | Model | Verification | Status |
+|-------|-----------|-------|--------------|--------|
+| 1. Setup types | 2/10 | haiku | 2/2 passed | Done |
+| 2. Core logic | 5/10 | sonnet | 3/3 passed (1 repair) | Done |
+| 3. Integration | 7/10 | opus | 1/2 passed (1 failed) | Partial |
+| 4. Tests | 4/10 | sonnet | — | Done |
+
+**Task verification totals**: 8 verified, 7 passed, 1 failed, 1 repair applied
+**Commits**: 8 atomic commits (per-task)
+**Model routing**: Saved ~X% vs all-opus execution
+**PR**: https://github.com/owner/repo/pull/123
+```
 
+**Wave mode summary** (when wave execution was used):
+
+```markdown
+| Wave | Phases | Parallel | Status |
+|------|--------|----------|--------|
+| 1 | Phase 1: Types (haiku), Phase 2: Utilities (haiku) | Yes (2 parallel) | Done |
+| 2 | Phase 3: API Integration (opus) | No | Done |
+| 3 | Phase 4: Config Updates (sonnet) | No | Done |
+| 4 | Phase 5: Tests (sonnet) | No | Done |
+
+**Wave execution stats**:
+- Sequential phases: 5
+- Waves executed: 4
+- Parallel phases: 2 (in Wave 1)
+- File conflicts: 0
+- Contract conflicts: 0
+- Failed phases: 0
+- Estimated speedup: ~20%
+
+**Task verification totals**: 8 verified, 7 passed, 1 failed, 1 repair applied
+**Commits**: 8 atomic commits (per-task)
 **Model routing**: Saved ~X% vs all-opus execution
+**PR**: https://github.com/owner/repo/pull/123
 ```
 
-4. **List all key changes** made
+5. **List all key changes** made
 
-5. **Ask if the plan should be archived**:
+6. **Ask if the plan should be archived**:
 
 ```bash
 mv flow/plans/plan_feature_name_v1.md flow/archive/
@@ -348,6 +690,8 @@ mv flow/plans/plan_feature_name_v1.md flow/archive/
 
 ## Execution Flow Within a Group
 
+### Sequential Mode
+
 ```
 Group 1: Phase 1 + Phase 2 (combined complexity: 5)
 |
@@ -366,6 +710,39 @@ Group 1: Phase 1 + Phase 2 (combined complexity: 5)
 +-- Continue to next group (NO BUILD HERE)
 ```
 
+### Wave Mode
+
+```
+Wave 1: Phase 1 + Phase 2 (parallel, no dependencies)
+|
++-- APPROVAL PHASE (sequential):
+|   +-- AUTO-SWITCH to Plan Mode for Phase 1
+|   +-- Present Phase 1 details (Wave 1 of 4, parallel with Phase 2)
+|   +-- Get user approval
+|   |
+|   +-- AUTO-SWITCH to Plan Mode for Phase 2
+|   +-- Present Phase 2 details (Wave 1 of 4, parallel with Phase 1)
+|   +-- Get user approval
+|
++-- EXECUTION PHASE (parallel):
+|   +-- Create flow/.wave-context.jsonl (if not exists)
+|   +-- Read shared context from sibling phases (if multi-phase wave)
+|   +-- Spawn Agent: Phase 1 (model: haiku, + shared context)  ──┐
+|   +-- Spawn Agent: Phase 2 (model: haiku, + shared context)  ──┤ (running simultaneously)
+|   +-- Wait for all to return                                  ──┘
+|
++-- POST-WAVE PROCESSING (sequential):
+|   +-- Collect JSON returns
+|   +-- Collect context_entries → append to .wave-context.jsonl
+|   +-- Check for file conflicts
+|   +-- Check for contract conflicts (same name, different signature)
+|   +-- Process Phase 1 result → update plan → git commit per task
+|   +-- Process Phase 2 result → update plan → git commit per task
+|   +-- Report wave completion
+|
++-- Continue to Wave 2 (NO BUILD HERE)
+```
+
 ---
 
 ## Complexity-Based Behavior
@@ -398,6 +775,21 @@ Group 1: Phase 1 + Phase 2 (combined complexity: 5)
 
 ---
 
+## Per-Task Verification
+
+When plans include tasks with `<verify>` tags, phase sub-agents run targeted verification after each task. If verification fails, a debug sub-agent (haiku) diagnoses the issue and the implementation sub-agent applies repairs automatically (up to `max_verify_retries` attempts, default: 2).
+
+The execute-plan skill processes verification results at two levels:
+
+1. **Phase level** (Steps 4/4c): After each sub-agent returns, display per-phase verification summaries and present failed tasks to the user
+2. **Completion level** (Step 7): Aggregate verification stats across all phases in the final summary
+
+Verification is internal to phase sub-agents — the coordinator and main session see only the `task_verifications` array in the JSON return. Plans without `<verify>` tags work unchanged (backward compatible).
+
+See `.claude/resources/core/per-task-verification.md` for the full system reference: verify tag syntax, debug sub-agent prompt template, verification loop flow, JSON schemas, and configuration.
+
+---
+
 ## Error Handling
 
 ### Build Failures (at Completion)
@@ -429,6 +821,8 @@ If the user wants to stop execution:
 3. The plan can be resumed later from the last completed phase
 4. When resuming, run build verification first
 
+**Wave mode cancellation**: If cancelled mid-wave, all running sub-agents complete (cannot be interrupted), but their results are discarded. Progress is saved up to the last fully completed wave.
+
 ---
 
 ## Summary of Key Rules
@@ -438,8 +832,16 @@ If the user wants to stop execution:
 | **Auto-switch to Plan mode** | Switch immediately for each phase, no asking                |
 | **Build ONLY at end**        | `npm run build && npm run test` runs once, after ALL phases |
 | **No intermediate builds**   | Never run build between phases or groups                    |
-| **Tests phase separate**     | Always execute Tests phase individually                     |
+| **Tests phase separate**     | Always execute Tests phase individually, in its own final wave |
 | **Update progress**          | Mark tasks complete in plan file after each phase           |
+| **Wave fallback**            | When wave_execution disabled or all phases dependent, execute sequentially (no behavior change) |
+| **Approve then spawn**       | In wave mode, approve ALL wave phases before spawning any   |
+| **Deterministic commits**    | Git commits happen per-task in phase/task order after wave completes: `feat(phase-N.task-M): <desc> — <feature>` |
+| **Failures are isolated**    | One failed phase does not cancel sibling phases in the same wave |
+| **File conflicts presented** | Never silently resolve file conflicts, always ask the user  |
+| **Shared context injected**  | Multi-phase waves inject sibling context entries; single-phase waves skip |
+| **Contract conflicts detected** | Same API name with different signatures triggers user resolution |
+| **Wave context is ephemeral** | `.wave-context.jsonl` accumulates across waves, deleted after execution completes |
 
 ---
 
@@ -449,6 +851,10 @@ If the user wants to stop execution:
 | ------------------------------------------- | -------------------------------- |
 | `.claude/resources/patterns/plans-patterns.md` | Plan patterns and rules          |
 | `.claude/resources/core/complexity-scoring.md`  | Complexity scoring system        |
+| `.claude/resources/core/wave-execution.md`  | Wave-based parallel execution system |
+| `.claude/resources/core/phase-isolation.md` | Phase isolation and sub-agent spawning |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification system and debug sub-agents |
 | `.claude/resources/tools/plan-mode-tool.md` | Plan mode switching instructions |
 | `flow/plans/`                               | Input plan documents             |
+| `flow/.wave-context.jsonl`                  | Ephemeral shared context between wave phases (deleted after execution) |
 | `flow/archive/`                             | Completed plans destination      |