planflow-ai 1.2.0 → 1.3.2

package/.claude/commands/brainstorm.md

@@ -0,0 +1,228 @@
+---
+description: Free-form conversational exploration of an idea. The LLM collaborates one-question-at-a-time to crystallize vague ideas before discovery. Optionally generates an MD file for /discovery-plan.
+---
+
+# Brainstorm
+
+## Command Description
+
+This command starts a free-form brainstorm session where the LLM collaborates conversationally to explore an idea. Unlike `/discovery-plan` (structured, project-aware), brainstorm is pure ideation — exploring the what and why through rapid back-and-forth dialogue.
+
+**Output**: Conversational exploration, plus an optional markdown file at `flow/brainstorms/brainstorm_{topic}_v{version}.md`
+
+---
+
+
+## Help
+
+**If the user invokes this command with `-help`, display only this section and stop:**
+
+```
+/brainstorm - Collaborative Idea Exploration
+
+DESCRIPTION:
+  Free-form brainstorm session where the LLM acts as a collaborative
+  thinking partner. Explores ideas through one-question-at-a-time dialogue
+  before formalizing into discovery.
+
+USAGE:
+  /brainstorm <idea>
+  /brainstorm -help
+
+ARGUMENTS:
+  idea   Free-text description of the idea to explore
+
+EXAMPLES:
+  /brainstorm I want to add a plugin system to plan-flow
+  /brainstorm "Real-time notifications triggered by user actions"
+  /brainstorm We need a better way to handle error recovery in the API
+
+OUTPUT:
+  - Conversational exploration of the idea
+  - Optional: flow/brainstorms/brainstorm_{topic}_v{version}.md
+  - Optional: tasklist entry (only if requested)
+
+WORKFLOW:
+  1. You share your idea
+  2. LLM presents batched questions with options (3-4 per round, with recommended choices)
+  3. You pick options or type custom answers, LLM reacts with insights
+  4. You say "done" / "wrap up" / "summarize" when ready
+  5. LLM presents structured summary
+  6. Optionally generates MD file for /discovery-plan
+  7. Optionally adds to tasklist
+
+WHAT IT IS:
+  - A thinking partner — challenges, suggests, connects, presents structured options
+  - Pure ideation — explores the what and why
+  - Lightweight — no brain, no memory, no auto-tasklist
+
+WHAT IT IS NOT:
+  - Not /discovery-plan — no codebase scanning, no requirements docs
+  - Not /note — no knowledge capture, no wiki-links
+  - Not a plan — no phases, no complexity scores
+
+RECOMMENDED MODEL:
+  Claude Opus 4.6 or Sonnet 4.5 for best results
+
+RELATED COMMANDS:
+  /discovery-plan   Ground the brainstorm idea into the project
+  /create-plan      Create plan from discovery document
+  /note             Capture knowledge (different purpose)
+```
+
+---
+
+## Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| **Structured Exploration** | Questions in batches of 3-4 with options via `AskUserQuestion`. Commentary between batches. |
+| **No Code** | NEVER write, edit, or generate source code |
+| **No Brain** | Do NOT write to `flow/brain/` or update brain index |
+| **No Memory** | Do NOT write to `flow/memory.md` |
+| **No Auto-Tasklist** | Only update tasklist if user explicitly requests |
+| **Codebase on Request** | Only read codebase files when user explicitly asks |
+| **User Ends It** | Never auto-end the brainstorm. User controls when it's done. |
+| **Complete and Stop** | After completion, STOP and wait for user |
+
+---
+
+## Instructions
+
+### Step 1: Validate Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `idea` | Yes | Free-text description of the idea to explore |
+
+If no idea is provided, ask:
+
+```markdown
+What idea would you like to explore? Just describe it in your own words —
+it can be as vague or specific as you want.
+```
+
+---
+
+### Step 2: Check for Existing Brainstorms
+
+Check `flow/brainstorms/` for existing brainstorm documents on a similar topic:
+
+1. If found, mention it: "There's an existing brainstorm on {topic} (v{N}). Want to build on that or start fresh?"
+2. If starting fresh, increment version number
+3. If building on existing, read it first for context
+
+---
+
+### Step 3: Invoke Brainstorm Skill
+
+The skill will:
+
+1. Parse the idea and open the conversation
+2. Run the conversational loop (one question per turn)
+3. Detect when the user wants to end
+4. Present a structured summary
+5. Offer to generate an MD file
+6. Offer to add a tasklist entry
+
+See: `.claude/resources/skills/brainstorm-skill.md`
+
+---
+
+### Step 4: Handle Completion
+
+After the skill completes:
+
+- If MD file was generated: report the file path
+- If no MD file: just acknowledge completion
+- Do NOT auto-chain to `/discovery-plan`
+
+---
+
+## Flow Diagram
+
+```
++------------------------------------------+
+|        /brainstorm COMMAND               |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 1: Validate Inputs                  |
+| - Check for idea text                    |
+| - Ask if not provided                    |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 2: Check Existing Brainstorms       |
+| - Look in flow/brainstorms/              |
+| - Offer to build on or start fresh       |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 3: Invoke Brainstorm Skill          |
+| - Conversational loop                    |
+| - One question per turn                  |
+| - Silent thread tracking                 |
+| - See brainstorm-skill.md              |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 4: Handle Completion                |
+| - Summary presented                      |
+| - Optional MD file generated             |
+| - Optional tasklist entry                |
+| - STOP (no auto-chain)                   |
++------------------------------------------+
+```
+
+---
+
+## Context Optimization
+
+### Recommended Loading Order
+
+1. **Always load first**: This command file (`commands/brainstorm.md`)
+2. **Expand on-demand**: Load skill file when entering conversational loop
+
+### Reference Codes for Brainstorm
+
+| 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 |
+
+---
+
+## Related Resources
+
+| 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 |
+
+---
+
+## Resource Capture
+
+During this skill's execution, watch for valuable reference materials worth preserving. See `.claude/resources/core/resource-capture.md` for capture rules, file format, and naming conventions.
+
+At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
+
+Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Pattern Capture
+
+During the brainstorm, silently watch for conventions, anti-patterns, and patterns that emerge from the discussion. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting the conversation.
+
+After the brainstorm completes, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

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

@@ -55,6 +55,7 @@ EXAMPLES:
   /discovery-plan @flow/contracts/api_contract.md
   /discovery-plan "User authentication with OAuth2"
   /discovery-plan @docs/feature-spec.md "Focus on the payment flow"
+  /discovery-plan @flow/brainstorms/brainstorm_plugin-system_v1.md
 
 OUTPUT:
   Creates: flow/discovery/discovery_<feature_name>_v<version>.md
@@ -145,9 +146,14 @@ Check `flow/discovery/` for existing discovery documents for this feature:
 
 ### Step 4: Invoke Discovery Skill
 
+**Brainstorm files as input**: If the reference document is a brainstorm file (`flow/brainstorms/brainstorm_*.md`), the skill should:
+- Treat "Resolved During Brainstorm" decisions as settled — do NOT re-ask
+- Use "Still Open (Discovery Should Investigate)" as starting investigation points
+- Respect "Rejected (Do Not Revisit)" — do NOT re-propose these alternatives
+
 The skill will:
 
-1. Read all referenced documents
+1. Read all referenced documents (including brainstorm files)
 2. Find all related code references in the codebase
 3. Ask clarifying questions via Interactive Questions Tool
 4. Track question status
@@ -380,3 +386,21 @@ During this skill's execution, watch for valuable reference materials worth pres
 At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
 
 Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Design Awareness
+
+During discovery, always ask whether the feature involves UI work. If confirmed, follow the design question flow to capture structured design tokens (colors, typography, spacing, component patterns) into a `## Design Context` section in the discovery document.
+
+See `.claude/resources/core/design-awareness.md` for the full question flow, personality options, token extraction rules, and Design Context template.
+
+---
+
+## Pattern Capture
+
+During discovery, silently watch for conventions found in existing code, anti-patterns in referenced documents, and patterns identified during technical analysis. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting work.
+
+After generating the discovery document, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

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

@@ -85,6 +85,7 @@ RELATED COMMANDS:
 | ------------------------ | -------------------------------------------------------- |
 | **Build ONLY at End**    | Do NOT run build after each phase - only at the very end |
 | **No Direct DB/ORM**     | NEVER run ORM or database commands directly              |
+| **Compact at Boundaries**| After each phase, if context is heavy, run `/compact` with execution state (see Step 5b in skill) |
 | **Complete and Stop**    | After execution, STOP and wait for user (unless autopilot ON) |
 
 ---
@@ -430,3 +431,37 @@ At natural break points, if you encounter information that could be useful for f
 
 Only save if the user approves. Do not re-ask if declined.
 
+---
+
+## Pattern Capture
+
+During execution, silently watch for recurring conventions, anti-patterns, workarounds, and user corrections. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting work.
+
+After all phases complete (before brain-capture), present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.
+
+---
+
+## Design Awareness
+
+During execution, when a phase involves UI work and the discovery document contains a `## Design Context` section, auto-inject the design tokens into the phase implementation prompt. This ensures UI phases follow the established design system.
+
+See `.claude/resources/core/design-awareness.md` for UI phase detection heuristics and injection rules.
+
+---
+
+## Model Routing
+
+When `model_routing: true` in `flow/.flowconfig` (default), each phase is automatically routed to the most cost-effective model based on its complexity score:
+
+| Complexity | Tier | Claude Code Model |
+|-----------|------|-------------------|
+| 0-3 | Fast | haiku |
+| 4-5 | Standard | sonnet |
+| 6-10 | Powerful | opus |
+
+Routing happens at Step 4 of the execution skill — the phase implementation is spawned as an Agent subagent with the appropriate `model` parameter. Planning/approval steps always use the session model.
+
+Disable with `/flow model_routing=false`. See `.claude/resources/core/model-routing.md` for full tier table, platform mappings, and aggregation rules.
+

package/.claude/commands/flow.md

@@ -29,6 +29,7 @@ DESCRIPTION:
 USAGE:
   /flow <key>=<value> [key=value ...]   Set one or more settings
   /flow <prompt>                         Enable autopilot and start flow with prompt
+  /flow cost [--today|--week|--month]   Show token usage and cost report
   /flow -status                          Show all current settings
   /flow -reset                           Reset all settings to defaults
   /flow -help                            Show this help
@@ -38,6 +39,16 @@ 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)
+
+COST REPORTING:
+  /flow cost                             Last 7 days summary (default)
+  /flow cost --today                     Today's usage only
+  /flow cost --week                      Last 7 days
+  /flow cost --month                     Last 30 days
+  /flow cost --project <name>            Filter by project name
+  /flow cost --session <id>              Show single session detail
+  /flow cost --detail                    Include model breakdown
 
 EXAMPLES:
   /flow autopilot=true                    # Enable autopilot
@@ -45,6 +56,9 @@ EXAMPLES:
   /flow autopilot=true commit=true        # Enable both
   /flow branch=development                # Set target branch
   /flow commit=false push=false           # Disable git control
+  /flow model_routing=false               # Disable model routing (use session model for all phases)
+  /flow cost                              # Show cost report (last 7 days)
+  /flow cost --today --detail             # Today's costs with model breakdown
   /flow -status                           # Show current config
   /flow -reset                            # Reset everything
 
@@ -82,9 +96,10 @@ CONFIG FILE:
 
 Parse the user input to determine what action to take:
 
-1. **Scan for `key=value` pairs**: Extract all `key=value` tokens from the input
-2. **Check for flags**: `-status`, `-reset`, `-help`
-3. **Remaining text**: Anything left after extracting keys and flags is a prompt
+1. **Check for `cost` subcommand**: If input starts with `cost`, route to cost reporting (see Step 6)
+2. **Scan for `key=value` pairs**: Extract all `key=value` tokens from the input
+3. **Check for flags**: `-status`, `-reset`, `-help`
+4. **Remaining text**: Anything left after extracting keys and flags is a prompt
 
 **Valid keys**:
 
@@ -94,6 +109,7 @@ 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 |
 
 ---
 
@@ -184,6 +200,23 @@ This is a **feature request with autopilot**:
 
 ---
 
+### Step 6: Cost Reporting (`/flow cost`)
+
+If the input starts with `cost`, route to the cost reporting flow:
+
+1. **Load the skill**: Read `.claude/resources/skills/flow-cost.md` for full implementation details
+2. **Parse cost flags**: `--today`, `--week`, `--month`, `--project <name>`, `--session <id>`, `--detail`
+3. **Read metrics file**: `~/.claude/metrics/costs.jsonl`
+4. **Filter and aggregate**: Apply time/project/session filters, group by project
+5. **Display summary table**: Format tokens (K/M), costs ($X.XX), present as markdown table
+6. **STOP**: After showing the report, wait for user input
+
+**Default behavior** (no flags): Show last 7 days summary grouped by project.
+
+See `.claude/resources/skills/flow-cost.md` for detailed formatting rules and examples.
+
+---
+
 ## Critical Rules
 
 | Rule | Description |

package/.claude/commands/heartbeat.md

@@ -53,7 +53,7 @@ TASKLIST INTEGRATION:
 
 RELATED COMMANDS:
   /flow           Configure plan-flow settings
-  /brain          Manual brain entry
+  /note           Manual brain entry
 ```
 
 ---

package/.claude/commands/learn.md

@@ -81,7 +81,7 @@ TEACHING MODE (/learn about <topic>):
   Index:  ~/plan-flow/brain/learns/_index.md (LRN-* codes)
 
 RELATED COMMANDS:
-  /brain           Capture meeting notes, ideas, brainstorms
+  /note            Capture meeting notes, ideas, brainstorms
   /setup           Generate project pattern files
   /review-code     Review local uncommitted changes
 ```

package/.claude/commands/{brain.md → note.md}

@@ -1,8 +1,8 @@
 ---
-description: Manual brain entry - capture meeting notes, ideas, brainstorms, and insights into the project brain
+description: Manual note entry - capture meeting notes, ideas, brainstorms, and insights into the project brain
 ---
 
-# Brain: Manual Knowledge Capture
+# Note: Manual Knowledge Capture
 
 ## Command Description
 
@@ -18,25 +18,25 @@ This command allows manual brain entries for capturing meeting notes, brainstorm
 **If the user invokes this command with `-help`, display only this section and stop:**
 
 ```
-/brain - Manual Brain Entry
+/note - Manual Brain Entry
 
 DESCRIPTION:
   Capture meeting notes, brainstorms, ideas, and insights into the
   project brain. Creates Obsidian-compatible markdown with [[wiki-links]].
 
 USAGE:
-  /brain <free text>        Free-text mode (default)
-  /brain -guided            Guided mode with structured questions
-  /brain -help              Show this help
+  /note <free text>        Free-text mode (default)
+  /note -guided            Guided mode with structured questions
+  /note -help              Show this help
 
 ARGUMENTS:
   free text     Unstructured text to parse and categorize
   -guided       Triggers structured question mode
 
 EXAMPLES:
-  /brain Had a call with the team about auth flow. Decision: use JWT with refresh tokens.
-  /brain Discovered that the API rate limits at 100 req/min. Need to add throttling.
-  /brain -guided
+  /note Had a call with the team about auth flow. Decision: use JWT with refresh tokens.
+  /note Discovered that the API rate limits at 100 req/min. Need to add throttling.
+  /note -guided
 
 OUTPUT:
   - Writes to appropriate flow/brain/ subdirectory
@@ -90,7 +90,7 @@ If no content and no `-guided` flag, ask:
 ```markdown
 What would you like to capture? You can:
 1. Type free text and I'll categorize it automatically
-2. Use `/brain -guided` for structured prompts
+2. Use `/note -guided` for structured prompts
 ```
 
 ---
@@ -175,7 +175,7 @@ Brain entry captured!
 
 ```
 +------------------------------------------+
-|           /brain COMMAND                 |
+|           /note COMMAND                  |
 +------------------------------------------+
                     |
                     v
@@ -214,7 +214,7 @@ Brain entry captured!
 
 ### Recommended Loading Order
 
-1. **Always load first**: This command file (`commands/brain.md`)
+1. **Always load first**: This command file (`commands/note.md`)
 2. **Load indexes**: Load `_index.md` files for relevant folders
 3. **Expand on-demand**: Use reference codes to load specific sections when needed
 

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

@@ -46,6 +46,11 @@ WORKFLOW:
   4. Compares against existing patterns
   5. Generates review document with findings
 
+ADAPTIVE DEPTH:
+  < 50 lines    Lightweight (security, logic bugs, breaking changes only)
+  50-500 lines  Standard (full review)
+  500+ lines    Deep (multi-pass, severity-grouped, executive summary)
+
 REVIEW CATEGORIES:
   - Pattern compliance
   - Code quality issues
@@ -149,6 +154,13 @@ This command uses hierarchical context loading to reduce context consumption. In
 | PTN-REV-1 | Review document structure | Creating review output |
 | COR-AP-1 | Allowed patterns overview | Checking pattern compliance |
 | COR-FP-1 | Forbidden patterns overview | Identifying anti-patterns |
+| COR-MA-1 | Multi-agent subagent definitions | Deep mode parallel review setup |
+| COR-MA-2 | Coordinator dedup and merge | Deep mode result processing |
+| COR-SR-1 | Severity re-ranking algorithm | Ordering findings by impact |
+| COR-SR-2 | Finding grouping rules | Grouping related findings |
+| COR-AD-1 | Adaptive depth size detection | Determining review mode |
+| COR-AD-2 | Lightweight review mode | Changeset < 50 lines |
+| COR-AD-3 | Deep review mode | Changeset 500+ lines |
 
 ### Expansion Instructions
 
@@ -238,3 +250,54 @@ During this skill's execution, watch for valuable reference materials worth pres
 At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
 
 Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Multi-Agent Parallel Review
+
+For Deep mode reviews (500+ lines), the review is split into 4 specialized subagents running in parallel:
+
+| Agent | Focus | Model |
+|-------|-------|-------|
+| Security | Vulnerabilities, secrets, injection, auth bypass | sonnet |
+| Logic & Bugs | Edge cases, null handling, race conditions, wrong logic | sonnet |
+| Performance | N+1 queries, memory leaks, blocking I/O, re-renders | sonnet |
+| Pattern Compliance | Forbidden/allowed patterns, naming, consistency | haiku |
+
+The coordinator merges results, deduplicates overlapping findings, then runs verification and re-ranking.
+
+See `.claude/resources/core/review-multi-agent.md` for full rules.
+
+---
+
+## Adaptive Depth
+
+Review depth scales automatically based on changeset size:
+
+| Lines Changed | Mode | Behavior |
+|--------------|------|----------|
+| < 50 | **Lightweight** | Quick-scan for security, logic bugs, breaking changes only. Skips pattern loading, similar implementations, verification pass. |
+| 50–500 | **Standard** | Full review (current behavior, no changes). |
+| 500+ | **Deep** | Multi-pass review with file categorization, severity-grouped output, executive summary, and mandatory verification pass. |
+
+Thresholds are hardcoded. The detected mode is displayed before the review starts.
+
+See `.claude/resources/core/review-adaptive-depth.md` for full rules and `.claude/resources/patterns/review-code-templates.md` for lightweight and deep templates.
+
+---
+
+## Verification Pass
+
+After initial analysis, all findings undergo a second-pass verification. Each finding is re-examined against 15 lines of surrounding context and classified as Confirmed, Likely, or Dismissed. False positives are filtered before output. A Verification Summary shows filter stats.
+
+See `.claude/resources/core/review-verification.md` for classification criteria, category-specific questions, and output format.
+
+---
+
+## Pattern Capture
+
+During code review, silently watch for anti-patterns found in changed code, good patterns that should be documented, and pattern conflicts between new and existing code. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting work.
+
+After analysis, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

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

@@ -49,6 +49,11 @@ WORKFLOW:
   5. Analyzes code changes
   6. Generates review document
 
+ADAPTIVE DEPTH:
+  < 50 lines    Lightweight (security, logic bugs, breaking changes only)
+  50-500 lines  Standard (full review)
+  500+ lines    Deep (multi-pass, severity-grouped, executive summary)
+
 REVIEW INCLUDES:
   - Summary of changes
   - Pattern compliance check
@@ -146,6 +151,13 @@ This command uses hierarchical context loading to reduce context consumption. In
 | PTN-PR-1 | PR review patterns | Creating review output |
 | COR-AP-1 | Allowed patterns overview | Checking pattern compliance |
 | COR-FP-1 | Forbidden patterns overview | Identifying anti-patterns |
+| COR-MA-1 | Multi-agent subagent definitions | Deep mode parallel review setup |
+| COR-MA-2 | Coordinator dedup and merge | Deep mode result processing |
+| COR-SR-1 | Severity re-ranking algorithm | Ordering findings by impact |
+| COR-SR-2 | Finding grouping rules | Grouping related findings |
+| COR-AD-1 | Adaptive depth size detection | Determining review mode |
+| COR-AD-2 | Lightweight review mode | Changeset < 50 lines |
+| COR-AD-3 | Deep review mode | Changeset 500+ lines |
 
 ### Expansion Instructions
 
@@ -238,3 +250,44 @@ During this skill's execution, watch for valuable reference materials worth pres
 At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
 
 Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Multi-Agent Parallel Review
+
+For Deep mode reviews (500+ lines), the review is split into 4 specialized subagents running in parallel:
+
+| Agent | Focus | Model |
+|-------|-------|-------|
+| Security | Vulnerabilities, secrets, injection, auth bypass | sonnet |
+| Logic & Bugs | Edge cases, null handling, race conditions, wrong logic | sonnet |
+| Performance | N+1 queries, memory leaks, blocking I/O, re-renders | sonnet |
+| Pattern Compliance | Forbidden/allowed patterns, naming, consistency | haiku |
+
+The coordinator merges results, deduplicates overlapping findings, then runs verification and re-ranking.
+
+See `.claude/resources/core/review-multi-agent.md` for full rules.
+
+---
+
+## Adaptive Depth
+
+Review depth scales automatically based on changeset size:
+
+| Lines Changed | Mode | Behavior |
+|--------------|------|----------|
+| < 50 | **Lightweight** | Quick-scan for security, logic bugs, breaking changes only. Skips pattern loading, full analysis, verification pass. |
+| 50–500 | **Standard** | Full review (current behavior, no changes). |
+| 500+ | **Deep** | Multi-pass review with file categorization, severity-grouped output, executive summary, and mandatory verification pass. |
+
+Thresholds are hardcoded. The detected mode is displayed before the review starts.
+
+See `.claude/resources/core/review-adaptive-depth.md` for full rules.
+
+---
+
+## Verification Pass
+
+After initial analysis, all findings undergo a second-pass verification. Each finding is re-examined against 15 lines of surrounding context and classified as Confirmed, Likely, or Dismissed. False positives are filtered before output. A Verification Summary shows filter stats.
+
+See `.claude/resources/core/review-verification.md` for classification criteria, category-specific questions, and output format.