planflow-ai 1.3.4 → 1.4.1

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

@@ -21,7 +21,9 @@ This skill is **strictly for creating plan documents**. The process:
 1. **Reads** the discovery document or gathers requirements
 2. **Analyzes** complexity and scope
 3. **Structures** phases with complexity scores
-4. **Generates** a plan markdown file
+4. **Analyzes** phase independence for parallel execution
+5. **Generates** verify sections for applicable tasks
+6. **Generates** a plan markdown file
 
 **No code, no implementation, no source file modifications.**
 
@@ -96,8 +98,10 @@ Create phases following these guidelines:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: [None | Phase N, Phase M | omit for sequential default]
 
 - [ ] Task 1
+  <verify>npx tsc --noEmit src/path/to/file.ts</verify>
 - [ ] Task 2
 
 **Build Verification**: Run `npm run build`
@@ -122,9 +126,64 @@ Create phases following these guidelines:
 | 7-8   | High      | Complex, multiple considerations |
 | 9-10  | Very High | Significant complexity/risk      |
 
+#### Auto-Generating Verify Sections
+
+When creating tasks within phases, auto-generate `<verify>` tags based on the task type using these heuristics:
+
+| Task Type | Verify Command | When to Apply |
+|-----------|---------------|---------------|
+| File creation (`.ts`, `.tsx`) | `npx tsc --noEmit <file>` | Task creates or modifies a TypeScript source file |
+| Test writing | `npx jest <test-file> --no-coverage` | Task creates or modifies a test file |
+| Schema/type definition | `npx tsc --noEmit <type-file>` | Task creates or modifies type definitions or schemas |
+| Config file changes | No verify | Task modifies `.flowconfig`, `tsconfig.json`, or similar config files |
+| Documentation/markdown | No verify | Task creates or updates `.md` files |
+| Generic/ambiguous tasks | No verify | Task description does not clearly indicate a verifiable output file |
+
+**Rules for auto-generation:**
+
+1. Only generate `<verify>` when the task clearly references a specific file path
+2. Use the file path from the task description in the verify command
+3. Prefer `npx tsc --noEmit` for source files and `npx jest --no-coverage` for test files
+4. When in doubt, omit the `<verify>` tag — false verification commands are worse than no verification
+5. Never generate full-build commands (`npm run build`) as verify tags — those belong in Build Verification
+
+---
+
+### Step 4: Analyze Phase Dependencies
+
+After structuring phases, analyze which phases are independent and can run in parallel:
+
+1. **For each phase**, determine its data and code dependencies on other phases:
+   - Does this phase use types/interfaces defined in another phase?
+   - Does this phase call functions or APIs created in another phase?
+   - Does this phase modify files that another phase also modifies?
+
+2. **Mark independent phases** with `**Dependencies**: None` when they:
+   - Only depend on pre-existing code (not created in this plan)
+   - Have no shared file modifications with other phases in the same wave
+   - Can be implemented and verified independently
+
+3. **Mark dependent phases** with explicit dependency lists:
+   - `**Dependencies**: Phase 1` — depends on one phase
+   - `**Dependencies**: Phase 1, Phase 3` — depends on multiple phases
+   - List only **direct** dependencies (not transitive ones)
+
+4. **Default to sequential** (omit the field) when:
+   - Unsure whether phases are truly independent
+   - Phases touch overlapping files
+   - The dependency relationship is ambiguous
+
+5. **Tests phase**: Always list ALL prior phases as dependencies. The Tests phase is never parallelized.
+
+**Common independence patterns**:
+- Types/schemas phase is often `Dependencies: None` (foundational, no prior phases needed)
+- Backend API and CLI commands may be independent if they don't share code
+- Store and UI phases often depend on types but may be independent of each other
+- Integration phases typically depend on multiple prior phases
+
 ---
 
-### Step 4: Add Key Changes Summary
+### Step 5: Add Key Changes Summary
 
 Document the most important modifications:
 
@@ -137,7 +196,7 @@ Document the most important modifications:
 
 ---
 
-### Step 5: Generate Plan Document
+### Step 6: Generate Plan Document
 
 Create the plan markdown file:
 
@@ -152,7 +211,7 @@ Create the plan markdown file:
 3. Non-Goals
 4. Requirements Summary (FR, NFR, Constraints)
 5. Risks
-6. Phases (with complexity scores)
+6. Phases (with complexity scores and optional dependency declarations)
 7. Key Changes
 
 ---
@@ -217,8 +276,10 @@ The plan document should follow the template in `.claude/resources/patterns/plan
 
 **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`
@@ -227,8 +288,10 @@ The plan document should follow the template in `.claude/resources/patterns/plan
 
 **Scope**: Write comprehensive tests
 **Complexity**: X/10
+**Dependencies**: Phase 1, Phase 2, ..., Phase N-1
 
 - [ ] Unit tests
+  <verify>npx jest src/path/to/test.ts --no-coverage</verify>
 - [ ] Integration tests
 
 **Build Verification**: Run `npm run build && npm run test`
@@ -247,9 +310,12 @@ Before completing the plan, verify:
 - [ ] Plan is saved in `flow/plans/` folder
 - [ ] File uses snake_case naming: `plan_<feature>_v<version>.md`
 - [ ] All phases have complexity scores (X/10)
-- [ ] Tests are the LAST phase
+- [ ] Phase dependencies are analyzed and declared where appropriate
+- [ ] Tests are the LAST phase with dependencies on ALL prior phases
 - [ ] Key Changes section is populated
 - [ ] Discovery document is referenced (discovery is required, never skipped)
+- [ ] Verify sections are generated for applicable tasks (file creation, test writing, schema/type tasks)
+- [ ] Verify sections are omitted for config, documentation, and generic tasks
 - [ ] **NO implementation code is included**
 - [ ] **NO source files were created or modified**
 

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,16 +247,18 @@ 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
 2. **Present phase details** - Show scope, tasks, and approach
 3. **Wait for approval** - Get user confirmation
-4. **Select model tier** - If `model_routing` is enabled in `flow/.flowconfig` (default: `true`):
+4. **Select model tier** - If `model_routing` is enabled in `flow/.flowconfig` (default: `false` — uses the most capable session model):
    - Read the phase's complexity score
    - Look up model tier: **0-3 → Fast (haiku)**, **4-5 → Standard (sonnet)**, **6-10 → Powerful (opus)**
    - For aggregated phases, use the **highest individual phase complexity** to determine the tier
-   - If `model_routing` is `false` or key is missing, skip routing (use session model)
+   - If `model_routing` is `false` or key is missing, skip routing (use the most capable model from the active provider — e.g., opus for Anthropic, o3 for OpenAI)
    - See `.claude/resources/core/model-routing.md` for full tier table, platform mappings, and rules
 5. **Inject design context** - Before implementing, check if the discovery doc (from plan's "Based on Discovery" field) has a `## Design Context` section. If present and the phase involves UI work (see UI Phase Detection Heuristics in `.claude/resources/core/design-awareness.md`), include the Design Context in the implementation prompt. If no Design Context or phase is not UI-related, skip this step.
 6. **Implement (with phase isolation)** - Check `phase_isolation` in `flow/.flowconfig` (default: `true`):
@@ -206,10 +271,106 @@ 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. **No cross-phase awareness**: Sub-agents within the same wave do NOT know about each other. They receive no information about sibling phases.
+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.
+
+##### 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. **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
+4. **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
+5. **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
+6. **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 +379,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 +403,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 +428,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 +441,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 +473,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 +488,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
@@ -323,17 +583,46 @@ npm run build && npm run test
    - 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:
+3. **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
+- 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
@@ -348,6 +637,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 +657,35 @@ 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):
+|   +-- Spawn Agent: Phase 1 (model: haiku)  ──┐
+|   +-- Spawn Agent: Phase 2 (model: haiku)  ──┤ (running simultaneously)
+|   +-- Wait for all to return               ──┘
+|
++-- POST-WAVE PROCESSING (sequential):
+|   +-- Collect JSON returns
+|   +-- Check for file conflicts
+|   +-- 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 +718,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 +764,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 +775,13 @@ 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  |
 
 ---
 
@@ -449,6 +791,9 @@ 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/archive/`                             | Completed plans destination      |