planflow-ai 1.3.4 → 1.4.1

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

@@ -301,6 +301,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

@@ -355,6 +355,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        |
 +------------------------------------------+
 ```
@@ -347,6 +392,15 @@ This command uses hierarchical context loading to reduce context consumption. In
 | 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 |
+| COR-WAVE-1 | Wave execution architecture and dependency syntax | Need wave execution architecture or dependency declaration syntax |
+| COR-WAVE-2 | Wave grouping algorithm (topological sort) | Need wave grouping algorithm or backward compatibility rules |
+| COR-WAVE-3 | Parallel spawning rules and wave summary format | Need parallel spawning rules or wave execution summary format |
+| COR-WAVE-4 | Wave coordinator behavior and failure handling | Need wave coordinator behavior, file conflict detection, or failure handling |
+| COR-WAVE-5 | Wave execution configuration and interaction matrix | Need wave execution configuration, interaction matrix, or aggregation rules |
+| COR-PTV-1 | Per-task verification architecture and verify tag syntax | Need verification system overview or `<verify>` tag parsing rules |
+| COR-PTV-2 | Debug sub-agent prompt template and return schema | Need debug sub-agent configuration or diagnosis JSON format |
+| COR-PTV-3 | Verification loop flow and retry behavior | Need verification loop details or retry/escalation rules |
+| COR-PTV-4 | Task verifications JSON return field schema | Need `task_verifications` array format or field descriptions |
 
 ### Expansion Instructions
 
@@ -366,6 +420,7 @@ When executing this command:
 | `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 +430,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 +555,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
@@ -39,8 +39,13 @@ SETTINGS:
   commit=true|false      Auto-commit after each completed phase (default: false)
   push=true|false        Auto-push after all phases + build/test pass (default: false)
   branch=<name>          Target branch for git operations (default: current branch)
-  model_routing=true|false  Auto-select model per phase based on complexity (default: true)
+  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
@@ -111,8 +123,13 @@ Parse the user input to determine what action to take:
 | `commit` | `true`, `false` | `false` | Auto-commit after each phase |
 | `push` | `true`, `false` | `false` | Auto-push after completion |
 | `branch` | any string | current branch | Target branch for git ops |
-| `model_routing` | `true`, `false` | `true` | Auto-select model per phase based on complexity |
+| `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.
 
 ---
 
@@ -242,8 +262,13 @@ autopilot: false
 commit: false
 push: false
 branch: ""
-model_routing: true
+model_routing: false
 phase_isolation: true
+max_verify_retries: 2
+pr: false
+webhook_url: ""
+telegram_bot_token: ""
+telegram_chat_id: ""
 ```
 
 **Location**: `flow/.flowconfig`

package/.claude/commands/resume-work.md

@@ -0,0 +1,261 @@
+# Resume Work
+
+## Command Description
+
+This command reads `flow/STATE.md` and reconstructs full session context after a context reset (compaction, new session, crash). It identifies the active work, reads the relevant plan/discovery file, and outputs a structured summary that puts the LLM back in context.
+
+**Output**: Structured context summary displayed in chat — no files created or modified.
+
+---
+
+## Help
+
+**If the user invokes this command with `-help`, display only this section and stop:**
+
+```
+/resume-work - Resume Work from Saved State
+
+DESCRIPTION:
+  Reads flow/STATE.md and reconstructs session context after a context
+  reset. Identifies active work, reads relevant plan files, and outputs
+  a structured summary to resume where you left off.
+
+USAGE:
+  /resume-work
+  /resume-work -help
+
+ARGUMENTS:
+  None — reads STATE.md automatically.
+
+EXAMPLES:
+  /resume-work
+
+OUTPUT:
+  Displays structured context summary with:
+  - Active skill and plan
+  - Current phase and task
+  - Decisions made so far
+  - Blockers encountered
+  - Files modified
+  - Next action to take
+
+WORKFLOW:
+  1. Validates flow/STATE.md exists
+  2. Reads and parses STATE.md
+  3. Checks staleness (warns if >24h old)
+  4. Reads active plan file (if any)
+  5. Identifies next task/phase
+  6. Outputs structured context summary
+
+RELATED COMMANDS:
+  /execute-plan    Continue executing a plan
+  /flow            Check flow configuration
+```
+
+---
+
+## Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| **Read-Only** | This command does NOT create, modify, or delete any files |
+| **No Auto-Chaining** | After presenting the summary, STOP and wait for user (unless autopilot ON) |
+| **No Code Execution** | Do NOT run build, test, or any implementation commands |
+| **STATE.md Required** | If STATE.md doesn't exist, inform the user — do NOT create it |
+| **Plan File is Truth** | If STATE.md references a plan, read the plan file for authoritative task status |
+
+---
+
+## Instructions
+
+### Step 1: Validate STATE.md Exists
+
+Check if `flow/STATE.md` exists.
+
+**If it does NOT exist**:
+```markdown
+No active session state found (`flow/STATE.md` does not exist).
+
+This means either:
+- No skill was in progress when the session ended
+- The previous skill completed successfully and cleared its state
+
+Use `/execute-plan`, `/discovery-plan`, or another command to start new work.
+```
+**STOP** — do not proceed.
+
+---
+
+### Step 2: Read and Parse STATE.md
+
+Read `flow/STATE.md` and extract:
+- **Active Skill**: The skill that was running
+- **Active Plan**: Path to the plan file being executed
+- **Current Phase**: Phase number and name
+- **Current Task**: The specific task in progress
+- **Completed Phases**: List of completed phases with outcomes
+- **Decisions**: Decisions made during the session
+- **Blockers**: Issues encountered and their status
+- **Files Modified**: Files changed during the session
+- **Next Action**: What to do immediately
+
+---
+
+### Step 3: Staleness Check
+
+Parse the `**Updated**` timestamp from STATE.md.
+
+**If the timestamp is more than 24 hours old**:
+```markdown
+> **Stale State Warning**: STATE.md was last updated {time_ago} ({timestamp}).
+> The session state may be outdated.
+>
+> Options:
+> 1. **Resume anyway** — continue from where STATE.md left off
+> 2. **Start fresh** — delete STATE.md and begin new work
+```
+
+Wait for user response before proceeding.
+
+**If the timestamp is within 24 hours**: Continue silently.
+
+---
+
+### Step 4: Read Active Plan File
+
+If STATE.md references an active plan (`Active Plan` is not "none"):
+1. Read the plan file
+2. Cross-reference completed phases in STATE.md with task checkboxes in the plan
+3. Identify the next uncompleted task
+
+If the plan file doesn't exist, note this as a warning.
+
+---
+
+### Step 5: Output Context Summary
+
+Present the reconstructed context:
+
+```markdown
+## Session Resumed
+
+**Active Skill**: {skill name}
+**Active Plan**: `{plan file path}`
+**Progress**: Phase {N} of {total} — {phase name}
+
+### Completed Phases
+{list of completed phases with outcomes}
+
+### Decisions Made
+{list of decisions with rationale}
+
+### Blockers
+{list of blockers with status}
+
+### Files Modified
+{list of files changed}
+
+### Next Action
+> {next action from STATE.md}
+
+---
+
+Ready to continue. Run the active skill command or describe what you'd like to do next.
+```
+
+---
+
+### Step 6: Stop and Wait
+
+After presenting the summary, **STOP**. Do not auto-invoke any commands.
+
+---
+
+## Flow Diagram
+
+```
++------------------------------------------+
+|         /resume-work COMMAND             |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 1: Validate STATE.md Exists         |
+| - If missing: inform user and stop       |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 2: Read and Parse STATE.md          |
+| - Extract all sections                   |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 3: Staleness Check                  |
+| - Warn if >24h old                       |
+| - Ask user: resume or start fresh        |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 4: Read Active Plan File            |
+| - Cross-reference with STATE.md          |
+| - Identify next task                     |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 5: Output Context Summary           |
+| - Structured markdown with all state     |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 6: Stop and Wait                    |
+| - User decides next action               |
++------------------------------------------+
+```
+
+---
+
+## STATE.md Updates
+
+This command does NOT update STATE.md. It is read-only.
+
+---
+
+## Brain Capture
+
+After resume completes, append a brain-capture block:
+
+```
+<!-- brain-capture
+skill: resume-work
+feature: [feature from active plan]
+status: completed
+data:
+  active_skill: [skill being resumed]
+  active_plan: [plan file path]
+  phase_resumed: [phase number]
+  staleness_hours: [hours since last update]
+-->
+```
+
+---
+
+## Tasklist Updates
+
+This command does NOT update the tasklist. It is read-only.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `resources/skills/resume-work-skill.md` | Skill implementation details |
+| `resources/core/compaction-guide.md` | What to preserve during compaction |
+| `resources/core/session-scratchpad.md` | Complementary session notes |
+| `/execute-plan` command | Continue plan execution |
+| `/flow` command | Check flow configuration |

package/.claude/commands/review-code.md

@@ -225,6 +225,17 @@ Run any of these to build structured understanding before or after merging.
 
 ---
 
+## STATE.md Updates
+
+Update `flow/STATE.md` at these transition points to enable session resumability.
+
+| Transition Point | Action |
+|-----------------|--------|
+| **Review start** | Create `flow/STATE.md` with `Active Skill: review-code`, `Active Plan: none`, `Current Phase: none`, `Current Task: reviewing {scope}`, `Next Action: Analyze changes and generate review` |
+| **Review complete** | Delete `flow/STATE.md` (skill is done, no state to preserve) |
+
+---
+
 ## Brain Capture
 
 After code review completes, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.

package/.claude/commands/review-pr.md

@@ -225,6 +225,17 @@ Run any of these to build structured understanding before or after merging.
 
 ---
 
+## STATE.md Updates
+
+Update `flow/STATE.md` at these transition points to enable session resumability.
+
+| Transition Point | Action |
+|-----------------|--------|
+| **Review start** | Create `flow/STATE.md` with `Active Skill: review-pr`, `Active Plan: none`, `Current Phase: none`, `Current Task: reviewing PR #{number}`, `Next Action: Authenticate, fetch PR, and analyze` |
+| **Review complete** | Delete `flow/STATE.md` (skill is done, no state to preserve) |
+
+---
+
 ## Brain Capture
 
 After PR review completes, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.