planflow-ai 1.3.5 → 1.4.3

package/.claude/commands/brainstorm.md

@@ -179,22 +179,15 @@ After the skill completes:
 +------------------------------------------+
 ```
 
----
-
-## Context Optimization
-
-### Recommended Loading Order
+## Context Loading
 
-1. **Always load first**: This command file (`commands/brainstorm.md`)
-2. **Expand on-demand**: Load skill file when entering conversational loop
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-### Reference Codes for Brainstorm
+**Queries**:
+- `planflow-ai state-query "brainstorm workflow" --scope resources`
+- `planflow-ai state-query "interactive questions" --scope resources`
 
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-BS-1 | Brainstorm skill restrictions and inputs | Understanding allowed actions |
-| SKL-BS-2 | Conversational loop and tracking | During the brainstorm |
-| SKL-BS-3 | End detection, summary, and output | When wrapping up |
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -202,7 +195,6 @@ After the skill completes:
 
 | Resource | Purpose |
 |----------|---------|
-| `resources/skills/_index.md` | Index of skills with reference codes |
 | `brainstorm-skill.md` | Skill that runs the brainstorm |
 | `brainstorm-templates.md` | Output file template |
 | `/discovery-plan` command | Next step after brainstorm |

package/.claude/commands/create-contract.md

@@ -193,44 +193,15 @@ The user will read the `.md` file themselves and decide when to proceed.
 4. Present contract summary
 5. User reviews and proceeds to `/discovery-plan`
 
----
-
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/create-contract.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Contract Creation
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/patterns/_index.md` | To find contract patterns |
-| `resources/skills/_index.md` | To understand skill workflow |
-| `resources/tools/_index.md` | When using interactive questions |
-
-### Reference Codes for Contract Creation
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| PTN-CON-1 | Contract document structure | Creating new contract |
-| PTN-CON-2 | Endpoint documentation format | Documenting API endpoints |
-| SKL-CON-1 | Contract skill workflow | Understanding full process |
-| TLS-IQ-2 | How to switch to Plan mode | Before asking questions |
-| TLS-IQ-3 | How to ask questions | When gathering scope info |
+## Context Loading
 
-### Expansion Instructions
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-When executing this command:
+**Queries**:
+- `planflow-ai state-query "contract creation" --scope resources`
+- `planflow-ai state-query "contract patterns" --scope resources`
 
-1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/skills/_index.md`
-2. **Identify needed codes**: Based on current step, identify which codes are relevant
-3. **Expand as needed**: Use the Read tool with specific line ranges from the index
-4. **Don't expand everything**: Only load content required for the current step
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -238,9 +209,6 @@ When executing this command:
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `resources/skills/_index.md`      | Index of skills with reference codes   |
-| `resources/patterns/_index.md`    | Index of patterns with reference codes |
-| `resources/tools/_index.md`       | Index of tools with reference codes    |
 | `create-contract-skill.md`    | Skill that creates the contract        |
 | `contract-patterns.md`        | Rules and patterns for contracts       |
 | `interactive-questions-tool.md` | Interactive Questions UI workflow    |

package/.claude/commands/create-plan.md

@@ -221,44 +221,16 @@ The user will read the `.md` file themselves and decide when to proceed.
 5. Present plan summary
 6. User reviews and proceeds to `/execute-plan`
 
----
-
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/create-plan.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Plan Creation
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/patterns/_index.md` | To find plan patterns and templates |
-| `resources/skills/_index.md` | To understand skill workflow |
-| `resources/core/_index.md` | For complexity scoring reference |
+## Context Loading
 
-### Reference Codes for Plan Creation
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| PTN-PLN-1 | Plan document structure | Creating new plan |
-| PTN-PLN-2 | Phase organization | Structuring phases |
-| PTN-PLNT-1 | Plan template | Creating output file |
-| SKL-PLN-1 | Create plan skill workflow | Understanding full process |
-| COR-CS-1 | Complexity scoring table | Assigning complexity scores |
+**Queries**:
+- `planflow-ai state-query "plan creation" --scope resources`
+- `planflow-ai state-query "complexity scoring" --scope resources`
+- `planflow-ai state-query "phase structure" --scope resources`
 
-### Expansion Instructions
-
-When executing this command:
-
-1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/core/_index.md`
-2. **Identify needed codes**: Based on current step, identify which codes are relevant
-3. **Expand as needed**: Use the Read tool with specific line ranges from the index
-4. **Don't expand everything**: Only load content required for the current step
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -266,9 +238,6 @@ When executing this command:
 
 | Resource                    | Purpose                           |
 | --------------------------- | --------------------------------- |
-| `resources/skills/_index.md`   | Index of skills with reference codes |
-| `resources/patterns/_index.md` | Index of patterns with reference codes |
-| `resources/core/_index.md`     | Index of core rules with reference codes |
 | `create-plan-skill.md`     | Skill that creates the plan       |
 | `plans-patterns.md`        | Rules and patterns for plans      |
 | `plans-templates.md`       | Plan templates                    |
@@ -301,6 +270,17 @@ Present recommendations after the plan summary.
 
 ---
 
+## STATE.md Updates
+
+Update `flow/STATE.md` at these transition points to enable session resumability.
+
+| Transition Point | Action |
+|-----------------|--------|
+| **Plan creation start** | Create `flow/STATE.md` with `Active Skill: create-plan`, `Active Plan: none`, `Current Phase: none`, `Current Task: creating plan from discovery`, `Next Action: Extract requirements and structure phases` |
+| **Plan complete** | Delete `flow/STATE.md` (skill is done, no state to preserve) |
+
+---
+
 ## Brain Capture
 
 After plan creation completes successfully, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.

package/.claude/commands/discovery-plan.md

@@ -248,55 +248,16 @@ The user will read the `.md` file themselves and decide when to proceed.
 6. User reviews and requests refinements (if any)
 7. User invokes `/create-plan` when ready
 
----
-
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/discovery-plan.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Discovery
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/patterns/_index.md` | To find discovery templates and patterns |
-| `resources/skills/_index.md` | To understand skill workflow |
-| `resources/tools/_index.md` | When using interactive questions |
-
-### Reference Codes for Discovery
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| PTN-DIS-1 | Discovery document structure | Creating new discovery doc |
-| PTN-DIS-2 | Requirements gathering example | Need example format |
-| PTN-DIST-1 | Discovery template | Creating output file |
-| SKL-DIS-1 | Discovery skill workflow | Understanding full process |
-| TLS-IQ-2 | How to switch to Plan mode | Before asking questions |
-| TLS-IQ-3 | How to ask questions | When gathering requirements |
-| COR-CG-1 | Compaction guide | Load when compacting mid-discovery |
+## Context Loading
 
-### Expansion Instructions
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-When executing this command:
+**Queries**:
+- `planflow-ai state-query "discovery workflow" --scope resources`
+- `planflow-ai state-query "requirements gathering" --scope resources`
+- `planflow-ai state-query "codebase analysis" --scope resources`
 
-1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/skills/_index.md`
-2. **Identify needed codes**: Based on current step, identify which codes are relevant
-3. **Expand as needed**: Use the Read tool with specific line ranges from the index
-4. **Don't expand everything**: Only load content required for the current step
-
-**Example expansion**:
-```
-# To get the discovery template
-Read: resources/patterns/discovery-templates.md (lines from PTN-DIST-1)
-
-# To understand question workflow
-Read: resources/tools/interactive-questions-tool.md (lines from TLS-IQ-3)
-```
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -304,9 +265,6 @@ Read: resources/tools/interactive-questions-tool.md (lines from TLS-IQ-3)
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `resources/skills/_index.md`      | Index of skills with reference codes   |
-| `resources/patterns/_index.md`    | Index of patterns with reference codes |
-| `resources/tools/_index.md`       | Index of tools with reference codes    |
 | `discovery-skill.md`          | Skill that executes the discovery      |
 | `discovery-patterns.md`       | Rules and patterns for discovery       |
 | `discovery-templates.md`      | Document templates                     |
@@ -355,6 +313,18 @@ These are optional but recommended to reduce implementation friction.
 
 ---
 
+## STATE.md Updates
+
+Update `flow/STATE.md` at these transition points to enable session resumability.
+
+| Transition Point | Action |
+|-----------------|--------|
+| **Discovery start** | Create `flow/STATE.md` with `Active Skill: discovery-plan`, `Active Plan: none`, `Current Phase: none`, `Current Task: gathering requirements`, `Next Action: Read references and ask clarifying questions` |
+| **Question batch complete** | Append answered questions to `## Decisions`: `{question} → {answer} (reason: user response)` |
+| **Discovery complete** | Delete `flow/STATE.md` (skill is done, no state to preserve) |
+
+---
+
 ## Brain Capture
 
 After discovery completes successfully, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.

package/.claude/commands/execute-plan.md

@@ -1,14 +1,14 @@
 ---
-description: This command executes an implementation plan phase by phase, using complexity scores to determine ex
+description: This command executes an implementation plan phase by phase, using complexity scores and wave-based parallel execution to determine ex
 ---
 
 # Execute Implementation Plan
 
 ## Command Description
 
-This command executes an implementation plan phase by phase, using complexity scores to determine execution strategy. The command validates inputs and orchestrates the execution process by invoking the `execute-plan` skill.
+This command executes an implementation plan phase by phase, using complexity scores to determine execution strategy. When `wave_execution: true` in `.flowconfig` (default), phases are analyzed for dependencies, grouped into **waves** of independent phases, and executed in parallel within each wave using Agent sub-agents. Tasks with `<verify>` tags are verified immediately after completion — failures are auto-diagnosed by debug sub-agents and repaired in place (up to `max_verify_retries` attempts). The command validates inputs and orchestrates the execution process by invoking the `execute-plan` skill.
 
-**Output**: Implements all phases from the plan, updates progress, and auto-archives the completed plan and its discovery document.
+**Output**: Implements all phases from the plan (sequentially or in parallel waves), updates progress, and auto-archives the completed plan and its discovery document.
 
 ---
 
@@ -22,7 +22,9 @@ This command executes an implementation plan phase by phase, using complexity sc
 
 DESCRIPTION:
   Executes an implementation plan phase by phase, using complexity scores
-  to determine execution strategy. Switches to Plan mode for each phase.
+  to determine execution strategy. Analyzes phase dependencies and groups
+  independent phases into parallel waves for faster execution. Switches
+  to Plan mode for each phase.
 
 USAGE:
   /execute-plan <plan_file>
@@ -44,13 +46,15 @@ OUTPUT:
 WORKFLOW:
   1. Reads and parses the plan file
   2. Groups phases by complexity score
-  3. For EACH phase:
-     - Auto-switches to Plan mode
-     - Presents phase details for approval
-     - Implements after approval
-     - Updates progress in plan file
-  4. Runs npm run build && npm run test (ONLY at the end)
-  5. Auto-archives plan and discovery to flow/archive/
+  2b. Analyzes dependencies and groups into waves (if wave_execution enabled)
+  3. Presents wave execution summary (waves, parallelism, estimated speedup)
+  4. For EACH wave:
+     - Approves each phase in Plan mode (sequential)
+     - Executes wave phases in parallel (or sequential if single phase)
+     - Collects results, detects file conflicts
+     - Commits per-task in phase/task order (if git enabled)
+  5. Runs npm run build && npm run test (ONLY at the end)
+  6. Auto-archives plan and discovery to flow/archive/
 
 EXECUTION STRATEGIES:
   Combined Score <= 6   Aggregate phases together
@@ -141,6 +145,24 @@ Please run this command and let me know when it's complete.
 
 ---
 
+## Per-Task Verification
+
+When plan phases include tasks with `<verify>` tags, each task is verified immediately after completion using targeted commands (e.g., `npx tsc --noEmit <file>`). Failed verifications trigger a debug sub-agent (haiku) for diagnosis, and the implementation sub-agent applies repairs automatically.
+
+### Configuration
+
+| Setting | Default | Range | Description |
+|---------|---------|-------|-------------|
+| `max_verify_retries` | `2` | `1-5` | Max repair attempts per task verification failure |
+
+Set via `/flow max_verify_retries=3` or directly in `flow/.flowconfig`.
+
+Plans without `<verify>` tags work unchanged — verification is fully backward compatible.
+
+See `.claude/resources/core/per-task-verification.md` for verify tag syntax, debug sub-agent details, and JSON schemas.
+
+---
+
 ## Git Control
 
 On execution start, check if `flow/.flowconfig` exists — if yes, read git control settings (`commit`, `push`, `branch`) from it. Fallback: check `flow/.gitcontrol` for backward compatibility. If neither exists, no git operations are performed.
@@ -149,20 +171,23 @@ On execution start, check if `flow/.flowconfig` exists — if yes, read git cont
 
 ```yaml
 # flow/.gitcontrol
-commit: true     # Auto-commit after each completed phase
+commit: true     # Auto-commit after each completed task (per-task atomic commits)
 push: true       # Auto-push after all phases complete (requires commit: true)
 branch: develop  # Target branch (optional, defaults to current branch)
+pr: true         # Auto-create PR via gh after push (requires push: true)
 ```
 
 ### Git Behavior During Execution
 
 | Setting | Behavior |
 |---------|----------|
-| `commit: true` | After each phase completes successfully, run `git add -A && git commit -m "Phase N: <phase name> — <feature>"` |
+| `commit: true` | After each task completes successfully, commit: `git add -A && git commit -m "feat(phase-N.task-M): <desc> — <feature>"` |
 | `commit: false` or no `.gitcontrol` | No automatic git operations (default behavior) |
 | `push: true` | After ALL phases complete AND build/test pass, run `git push origin <branch>` |
 | `push: false` or not set | No automatic push |
 | `branch: <name>` | Use this branch for push (default: current branch) |
+| `pr: true` | After push, create feature branch feat/<feature> and open PR via gh pr create |
+| `pr: false` or not set | No automatic PR creation |
 
 ### Git Safety Rules
 
@@ -171,21 +196,31 @@ branch: develop  # Target branch (optional, defaults to current branch)
 | **Commit only on success** | Only commit after a phase completes successfully. Never commit broken code. |
 | **Push only after build+test** | Push only after `npm run build && npm run test` pass at the very end. |
 | **No force push** | NEVER use `--force`. If push fails, stop and ask the user. |
-| **Commit message format** | `Phase N: <phase name> — <feature>` (e.g., "Phase 2: API endpoints — user-auth") |
+| **Commit message format** | `feat(phase-N.task-M): <desc> — <feature>` (e.g., "feat(phase-2.task-1): Implement auth middleware — user-auth") |
 | **Final commit** | After build+test pass, make one final commit: `Complete: <feature> — all phases done, build passing` |
 | **Include flow artifacts** | Commits should include updated plan files with progress markers |
+| **PR best-effort** | If gh CLI is missing or PR creation fails, warn and continue. Never block completion. |
+| **Branch naming** | Feature branches use feat/<sanitized-feature-name> (lowercase, hyphens only) |
 
-### Example Flow with `commit=true push=true`
+### Example Flow with `commit=true push=true pr=true`
 
 ```
-Phase 1: Setup types → completes → git commit "Phase 1: Setup types — user-auth"
-Phase 2: API endpoints → completes → git commit "Phase 2: API endpoints — user-auth"
-Phase 3: Frontend UI → completes → git commit "Phase 3: Frontend UI — user-auth"
-Phase 4: Tests → completes → git commit "Phase 4: Tests — user-auth"
-Build + Test → pass → git commit "Complete: user-auth — all phases done, build passing"
+Phase 1: Setup types (2 tasks)
+  → git commit "feat(phase-1.task-1): Define user and session types — user-auth"
+  → git commit "feat(phase-1.task-2): Create user schema with Prisma — user-auth"
+Phase 2: API endpoints (2 tasks)
+  → git commit "feat(phase-2.task-1): Implement auth middleware — user-auth"
+  → git commit "feat(phase-2.task-2): Add rate limiting to API routes — user-auth"
+Phase 3: Frontend UI (1 task)
+  → git commit "feat(phase-3.task-1): Create login form component — user-auth"
+Phase 4: Tests (1 task)
+  → git commit "feat(phase-4.task-1): Add unit tests for auth flow — user-auth"
+Build + Test → pass → git commit "Complete: user-auth — all phases done, build passing (vX.Y.Z)"
                      → git push origin development
+                     → git checkout -b feat/user-auth
+                     → git push -u origin feat/user-auth
+                     → gh pr create --title "feat: user-auth" --body "..."
 ```
-
 ---
 
 ## Instructions
@@ -249,6 +284,7 @@ Execution Complete!
 - X phases completed
 - All tests passing
 - Build successful
+- PR: <url> (or "PR creation skipped" if pr=false)
 - Archived: plan and discovery moved to flow/archive/
 ```
 
@@ -276,15 +312,24 @@ Execution Complete!
                     |
                     v
 +------------------------------------------+
+| Step 2b: Wave Analysis (if enabled)      |
+| - Parse Dependencies from each phase     |
+| - Build dependency graph                 |
+| - Group independent phases into waves    |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
 | Step 3: Invoke Execute Plan Skill        |
-| - Skill handles all execution logic      |
+| - Present wave execution summary         |
+| - Execute waves (parallel or sequential) |
 | - See execute-plan-skill.md             |
 +------------------------------------------+
                     |
                     v
 +------------------------------------------+
 | Step 4: Handle Completion                |
-| - Present summary                        |
+| - Present summary with wave stats        |
 | - Auto-archive plan and discovery        |
 +------------------------------------------+
 ```
@@ -304,58 +349,18 @@ Execution Complete!
 5. Final build and test verification
 6. Auto-archive plan and discovery to flow/archive/
 
----
+## Context Loading
 
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/execute-plan.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Plan Execution
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand execution workflow |
-| `resources/core/_index.md` | For complexity scoring reference |
-| `resources/tools/_index.md` | When switching to Plan mode |
-
-### Reference Codes for Plan Execution
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-EXEC-2 | Critical rules (build, DB) | Need build/DB command restrictions |
-| SKL-EXEC-4 | Analyze complexity | Determining execution strategy |
-| SKL-EXEC-6 | Execute phase with Plan mode | Running a specific phase |
-| SKL-EXEC-8 | Phase-boundary compaction | Compacting between phases |
-| SKL-EXEC-9 | Handle tests phase | Executing the tests phase |
-| SKL-EXEC-10 | Build and test verification | Final verification step |
-| SKL-EXEC-11 | Complexity-based behavior | Need low/medium/high behavior details |
-| SKL-EXEC-12 | Error handling | Build/test failure or cancellation |
-| COR-CS-1 | Complexity scoring table | Interpreting phase complexity |
-| TLS-PLN-1 | Plan mode switching | Before each phase |
-| TLS-PLN-2 | Plan mode workflow | Presenting phase details |
-| COR-CG-1 | Compaction guide purpose | When compacting at phase boundaries |
-| COR-CG-2 | Preserve rules | Crafting compact summary — what to keep |
-| COR-CG-3 | Discard rules | Crafting compact summary — what to drop |
-| COR-CG-4 | Compact summary template | Structuring compact instructions |
-| COR-PI-1 | Phase isolation architecture | Understanding isolated sub-agent flow |
-| COR-PI-2 | Sub-agent context template | Preparing focused prompt for sub-agent |
-| COR-PI-3 | Return format schema | Parsing sub-agent JSON response |
-| COR-PI-4 | Coordinator processing rules | Handling success/failure/partial returns |
-
-### Expansion Instructions
-
-When executing this command:
-
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/core/_index.md`
-2. **Identify needed codes**: Based on current phase, identify which codes are relevant
-3. **Expand as needed**: Use the Read tool with specific line ranges from the index
-4. **Don't expand everything**: Only load content required for the current phase
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
+
+**Queries**:
+- `planflow-ai state-query "phase execution" --scope resources`
+- `planflow-ai state-query "wave execution" --scope resources`
+- `planflow-ai state-query "phase isolation" --scope resources`
+- `planflow-ai state-query "per-task verification" --scope resources`
+- `planflow-ai state-query "atomic commits" --scope resources`
+
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -363,9 +368,7 @@ When executing this command:
 
 | Resource                   | Purpose                           |
 | -------------------------- | --------------------------------- |
-| `resources/skills/_index.md`  | Index of skills with reference codes |
-| `resources/core/_index.md`    | Index of core rules with reference codes |
-| `resources/tools/_index.md`   | Index of tools with reference codes |
+| `per-task-verification.md` | Per-task verification system, debug sub-agents, JSON schemas |
 | `execute-plan-skill.md`   | Skill that executes the plan      |
 | `plans-patterns.md`       | Rules and patterns for plans      |
 | `complexity-scoring.md`   | Complexity scoring system         |
@@ -375,6 +378,25 @@ When executing this command:
 
 ---
 
+## STATE.md Updates
+
+Update `flow/STATE.md` at these transition points to enable session resumability. Use the Edit tool for single-field updates; overwrite the file on skill start.
+
+| Transition Point | Action |
+|-----------------|--------|
+| **Plan start** | Create `flow/STATE.md` with `Active Skill: execute-plan`, `Active Plan: {plan file path}`, `Current Phase: none`, empty Decisions/Blockers/Files Modified, `Next Action: Begin phase execution` |
+| **Phase start** | Update `Current Phase: {N} — {Phase Name}`, `Current Task: first task description`, `Next Action: Implement phase {N}` |
+| **Phase complete** | Append to `Completed Phases` list: `Phase N: Name — {outcome}`, set `Current Phase: none`, `Current Task: none`, `Next Action: Begin next phase` |
+| **Decision made** | Append to `## Decisions`: `{description} (reason: {rationale})` |
+| **Blocker encountered** | Append to `## Blockers`: `{description} (status: open, tried: {what was attempted})` |
+| **Files modified** | Append new file paths to `## Files Modified` (deduplicate) |
+| **Plan complete** | Delete `flow/STATE.md` (execution is done, no state to preserve) |
+| **User cancellation** | Update `Next Action: Resume from phase {N}`, keep STATE.md intact for resumability |
+
+**Wave mode**: Update STATE.md before each wave starts (set current wave info) and after each wave completes (update completed phases for all wave phases).
+
+---
+
 ## Brain Capture
 
 After each phase completes (and after full execution), append brain-capture blocks. See `.claude/resources/core/brain-capture.md` for processing rules.
@@ -481,6 +503,23 @@ Disable with `/flow model_routing=false`. See `.claude/resources/core/model-rout
 
 ---
 
+## Wave Execution
+
+When `wave_execution: true` in `flow/.flowconfig` (default), the coordinator 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.
+
+Key behaviors:
+- **Planning stays sequential** — each phase is approved in Plan mode before wave execution begins
+- **Tests never parallel** — tests phase always runs alone in the final wave
+- **Backward compatible** — plans without `Dependencies` fields execute sequentially (no behavior change)
+- **File conflict detection** — overlapping files_modified between parallel phases are flagged for user resolution
+- **Deterministic commits** — git commits happen per-task in phase/task order after each wave completes: `feat(phase-N.task-M): <desc> — <feature>`
+
+User can always choose sequential execution at the wave summary prompt. Disable globally with `/flow wave_execution=false`.
+
+See `.claude/resources/core/wave-execution.md` for the full dependency analysis rules, wave grouping algorithm, parallel spawning rules, coordinator behavior, and configuration.
+
+---
+
 ## Phase Isolation
 
 When `phase_isolation: true` in `flow/.flowconfig` (default), each phase implementation runs in an **isolated Agent sub-agent** with a clean context window. The sub-agent receives only: phase spec, files modified so far, pattern file paths, and design context (if UI phase). It returns a structured JSON summary (1-2K tokens) with status, files changed, decisions, errors, and captured patterns.

package/.claude/commands/flow.md

@@ -1,5 +1,5 @@
 ---
-description: Configure plan-flow settings — autopilot mode, git control, and other runtime options. Use key=value syntax.
+description: Configure plan-flow settings — autopilot mode, git control, PR creation, and other runtime options. Use key=value syntax.
 ---
 
 # Flow: Plan-Flow Configuration
@@ -41,6 +41,11 @@ SETTINGS:
   branch=<name>          Target branch for git operations (default: current branch)
   model_routing=true|false  Auto-select model per phase based on complexity (default: false)
   phase_isolation=true|false  Run each phase in isolated sub-agent with clean context (default: true)
+  max_verify_retries=1-5     Max repair attempts per task verification failure (default: 2)
+  pr=true|false         Auto-create PR via gh after execution (default: false)
+  webhook_url=<url>     Webhook URL(s) for external notifications, comma-separated (default: "")
+  telegram_bot_token=<token>  Telegram bot token for two-way messaging (default: "")
+  telegram_chat_id=<id>       Telegram chat ID for two-way messaging (default: "")
 
 COST REPORTING:
   /flow cost                             Last 7 days summary (default)
@@ -59,6 +64,12 @@ EXAMPLES:
   /flow commit=false push=false           # Disable git control
   /flow model_routing=false               # Disable model routing (use session model for all phases)
   /flow phase_isolation=false             # Disable phase isolation (inline execution, for debugging)
+  /flow max_verify_retries=3             # Set max repair attempts per task verification to 3
+  /flow pr=true                           # Enable auto-PR creation after execute-plan
+  /flow commit=true push=true pr=true     # Full git control with auto-PR
+  /flow webhook_url=https://hooks.slack.com/services/T.../B.../xxx  # Set Slack webhook
+  /flow webhook_url=https://discord.com/api/webhooks/123/abc,https://hooks.slack.com/services/T.../B.../xxx  # Multiple webhooks
+  /flow telegram_bot_token=123456:ABC-DEF telegram_chat_id=5635356808  # Enable Telegram two-way
   /flow cost                              # Show cost report (last 7 days)
   /flow cost --today --detail             # Today's costs with model breakdown
   /flow -status                           # Show current config
@@ -80,6 +91,7 @@ GIT CONTROL (when commit=true):
   - After all phases + build/test pass: auto-push if push=true
   - If build/test fails: commit is made but push is skipped
   - push=true without commit=true: auto-enables commit=true
+  - If pr=true: after push, create feature branch and open PR via gh pr create
 
 MANDATORY CHECKPOINTS (even in autopilot):
   - Discovery phase: pauses for user Q&A
@@ -113,6 +125,11 @@ Parse the user input to determine what action to take:
 | `branch` | any string | current branch | Target branch for git ops |
 | `model_routing` | `true`, `false` | `false` | Auto-select model per phase based on complexity |
 | `phase_isolation` | `true`, `false` | `true` | Run each phase in isolated sub-agent with clean context |
+| `max_verify_retries` | `1`-`5` | `2` | Max repair attempts per task verification failure |
+| `pr` | `true`, `false` | `false` | Auto-create PR after execution completes (requires push: true) |
+| `webhook_url` | URL string | `""` | Webhook URL(s) for Telegram/Discord/Slack notifications (comma-separated) |
+| `telegram_bot_token` | any string | `""` | Telegram bot token for two-way polling |
+| `telegram_chat_id` | any string | `""` | Telegram chat ID for two-way polling |
 
 ---
 
@@ -130,7 +147,10 @@ Parse the user input to determine what action to take:
 
 1. If `push=true` but `commit` is not `true`, auto-enable `commit=true` and warn:
    > `push=true` requires `commit=true`. Enabling auto-commit as well.
-2. If `autopilot=false` and `commit=false` and no other settings, consider removing `.flowconfig`
+2. If `pr=true` but `push` is not `true`, auto-enable `push=true` and `commit=true` and warn:
+   > `pr=true` requires `push=true` and `commit=true`. Enabling both.
+3. If `autopilot=false` and `commit=false` and no other settings, consider removing `.flowconfig`
+4. If `max_verify_retries` is set, validate it is an integer between 1 and 5 (inclusive). If out of range, warn and clamp to nearest valid value.
 
 ---
 
@@ -244,6 +264,11 @@ push: false
 branch: ""
 model_routing: false
 phase_isolation: true
+max_verify_retries: 2
+pr: false
+webhook_url: ""
+telegram_bot_token: ""
+telegram_chat_id: ""
 ```
 
 **Location**: `flow/.flowconfig`