planflow-ai 1.3.0 → 1.3.2

package/.claude/commands/brainstorm.md

@@ -58,7 +58,7 @@ WHAT IT IS:
 
 WHAT IT IS NOT:
   - Not /discovery-plan — no codebase scanning, no requirements docs
-  - Not /brain — no knowledge capture, no wiki-links
+  - Not /note — no knowledge capture, no wiki-links
   - Not a plan — no phases, no complexity scores
 
 RECOMMENDED MODEL:
@@ -67,7 +67,7 @@ RECOMMENDED MODEL:
 RELATED COMMANDS:
   /discovery-plan   Ground the brainstorm idea into the project
   /create-plan      Create plan from discovery document
-  /brain            Capture knowledge (different purpose)
+  /note             Capture knowledge (different purpose)
 ```
 
 ---

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
 
@@ -241,6 +253,47 @@ 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.

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.

package/.claude/resources/core/_index.md

@@ -5,8 +5,8 @@
 
 Core rules define the foundational coding standards that apply across the entire project. These include best practices to follow (allowed patterns), anti-patterns to avoid (forbidden patterns), and complexity scoring for implementation planning.
 
-**Total Files**: 14 files, ~2310 lines
-**Reference Codes**: COR-AP-1 through COR-DA-3
+**Total Files**: 18 files, ~3020 lines
+**Reference Codes**: COR-AP-1 through COR-AD-4
 
 ---
 
@@ -118,6 +118,40 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-DA-2 | Token extraction and UI detection rules | design-awareness.md | 182-260 |
 | COR-DA-3 | Discovery question flow and execution injection | design-awareness.md | 262-350 |
 
+### Review Verification (`review-verification.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-RV-1 | Verification logic, questions, and classification criteria | review-verification.md | 1-120 |
+| COR-RV-2 | Output format and insertion points | review-verification.md | 122-200 |
+
+### Review Multi-Agent (`review-multi-agent.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-MA-1 | Subagent definitions (security, logic, performance, patterns) with prompts and models | review-multi-agent.md | 30-130 |
+| COR-MA-2 | Coordinator behavior (spawn, collect, deduplicate, verify, rank, output) | review-multi-agent.md | 132-195 |
+| COR-MA-3 | Subagent input rules and diff splitting for very large changesets | review-multi-agent.md | 100-130 |
+| COR-MA-4 | Insertion points for review-code and review-pr skills | review-multi-agent.md | 197-220 |
+
+### Review Severity Re-Ranking (`review-severity-ranking.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-SR-1 | Ranking algorithm (severity → confidence → complexity) | review-severity-ranking.md | 14-26 |
+| COR-SR-2 | Grouping related findings (patterns, rules, format) | review-severity-ranking.md | 28-88 |
+| COR-SR-3 | Executive summary trigger and risk level derivation | review-severity-ranking.md | 90-120 |
+| COR-SR-4 | Output structure and insertion points | review-severity-ranking.md | 122-150 |
+
+### Review Adaptive Depth (`review-adaptive-depth.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-AD-1 | Size detection, line counting rules, and tier definitions | review-adaptive-depth.md | 14-47 |
+| COR-AD-2 | Lightweight review mode (< 50 lines) — checks, skips, output | review-adaptive-depth.md | 51-101 |
+| COR-AD-3 | Deep review mode (500+ lines) — categorization, passes, executive summary | review-adaptive-depth.md | 103-187 |
+| COR-AD-4 | Insertion points for review-code and review-pr skills | review-adaptive-depth.md | 189-205 |
+
 ---
 
 ## When to Expand
@@ -160,6 +194,20 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-DA-1 | Need design context template or personality options |
 | COR-DA-2 | Need token extraction or UI detection heuristics |
 | COR-DA-3 | Need design question flow or execution injection rules |
+| COR-RV-1 | Need verification questions or classification criteria |
+| COR-RV-2 | Need verification output format or skill insertion points |
+| COR-MA-1 | Need subagent definitions or prompt templates for deep review |
+| COR-MA-2 | Need coordinator dedup/merge behavior |
+| COR-MA-3 | Need subagent input rules or diff splitting strategy |
+| COR-MA-4 | Need multi-agent insertion points for review skills |
+| COR-SR-1 | Need ranking algorithm for review findings |
+| COR-SR-2 | Need grouping rules for related findings |
+| COR-SR-3 | Need executive summary trigger conditions |
+| COR-SR-4 | Need severity re-ranking output structure or insertion points |
+| COR-AD-1 | Need size detection thresholds or line counting rules |
+| COR-AD-2 | Need lightweight review mode behavior |
+| COR-AD-3 | Need deep review mode behavior (categorization, passes, executive summary) |
+| COR-AD-4 | Need insertion points for adaptive depth in review skills |
 
 ---
 

package/.claude/resources/core/resource-capture.md

@@ -13,7 +13,7 @@ During any skill execution, the LLM watches for information that could be valuab
 
 ### During Any Skill Execution
 
-While executing any plan-flow skill (`/setup`, `/discovery-plan`, `/create-plan`, `/execute-plan`, `/review-code`, `/review-pr`, `/write-tests`, `/create-contract`, `/brain`), watch for information that meets the capture criteria below.
+While executing any plan-flow skill (`/setup`, `/discovery-plan`, `/create-plan`, `/execute-plan`, `/review-code`, `/review-pr`, `/write-tests`, `/create-contract`, `/note`), watch for information that meets the capture criteria below.
 
 When you identify something worth preserving:
 

package/.claude/resources/core/review-adaptive-depth.md

@@ -0,0 +1,217 @@
+
+# Review Adaptive Depth
+
+## Purpose
+
+Scale review depth based on changeset size. Small changes get a fast lightweight pass, large changes get a deeper multi-category review with severity-grouped output and executive summary. Medium changes use the standard review (no behavior change).
+
+**Scope**: `/review-code` (Step 1b) and `/review-pr` (Step 1b). Applied after identifying changed files, before loading patterns.
+
+**Goal**: Save tokens on trivial PRs and improve quality on complex ones. A 5-line typo fix shouldn't get the same depth as a 2000-line refactor.
+
+---
+
+## Size Detection
+
+### Line Counting Rules
+
+Count total lines changed (additions + deletions) from the diff.
+
+**Exclude** from the count:
+- Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`, `go.sum`
+- Generated files: any path containing `.generated.`, `dist/`, `build/`, `.min.js`, `.min.css`
+- Pure whitespace/formatting changes (lines where only indentation changed)
+
+**For review-code**: Use `git diff --stat` to get line counts, then subtract excluded files.
+
+**For review-pr**: Use PR diff stats from `gh pr diff --stat` or Azure DevOps diff API, then subtract excluded files.
+
+### Display Format
+
+Always show the detected mode before starting the review:
+
+```markdown
+**Review mode**: {Lightweight|Standard|Deep} ({N} lines changed across {M} files)
+```
+
+---
+
+## Tier Definitions
+
+| Tier | Lines Changed | Review Mode |
+|------|--------------|-------------|
+| **Small** | < 50 | Lightweight |
+| **Medium** | 50–500 | Standard (current behavior, no changes) |
+| **Large** | 500+ | Deep |
+
+Thresholds are hardcoded. No configuration needed.
+
+---
+
+## Lightweight Review Mode (Small, < 50 lines)
+
+For changesets under 50 lines, perform a focused quick-scan review.
+
+### What to Check (ONLY these)
+
+1. **Security issues** — hardcoded secrets, injection vulnerabilities, auth bypass, exposed credentials
+2. **Obvious logic bugs** — wrong condition, off-by-one, null/undefined access, infinite loops
+3. **Breaking changes** — API signature changes, removed exports, changed return types
+
+### What to Skip
+
+- Naming suggestions
+- Pattern compliance
+- Performance optimization
+- Test coverage analysis
+- Similar implementation search
+- Pattern conflict detection
+
+### Verification Pass
+
+**Skip entirely.** Lightweight reviews produce few findings — verification adds overhead with minimal value on small changesets.
+
+### Output
+
+If no issues found, output a short **LGTM review**:
+
+```markdown
+## Review Summary
+
+| Metric | Value |
+|--------|-------|
+| **Review Mode** | Lightweight (< 50 lines) |
+| **Total Findings** | 0 |
+| **Status** | LGTM |
+
+## Positive Highlights
+
+- {Highlight 1}
+- {Highlight 2}
+- {Highlight 3}
+
+## Commit Readiness
+
+| Status | Ready to Commit |
+|--------|-----------------|
+| Reason | No issues found in lightweight review |
+```
+
+If issues ARE found, use the standard finding format but keep the compact template (no Reference Implementations, no Pattern Conflicts sections).
+
+---
+
+## Deep Review Mode (Large, 500+ lines)
+
+For changesets over 500 lines, perform a structured multi-pass review.
+
+### Step 1: Categorize Changed Files
+
+Group all changed files by type:
+
+| Category | Heuristics |
+|----------|-----------|
+| **Core Logic** | `src/`, `lib/`, `app/` (excluding UI paths), service files, utility files, business logic |
+| **Infrastructure** | Config files, CI/CD (`.github/`, `.gitlab-ci`), build config, Docker, env files |
+| **UI/Presentation** | Components, pages, layouts, styles, templates — detected by path (`components/`, `pages/`, `views/`) or extension (`.tsx`, `.jsx`, `.vue`, `.svelte`, `.css`, `.scss`) |
+| **Tests** | Any file in `__tests__/`, `test/`, `tests/`, `spec/`, or files ending in `.test.*`, `.spec.*` |
+
+Files that don't match any heuristic → default to **Core Logic**.
+
+### Step 2: Prioritize Review Order
+
+Review in this order: **Core Logic → Infrastructure → UI → Tests**
+
+Core logic gets the deepest review. Tests get a quick coverage-adequacy scan.
+
+### Step 3: Focused Passes per Category
+
+| Category | Focus Areas |
+|----------|-------------|
+| **Core Logic** | Bugs, edge cases, security, error handling, null safety |
+| **Infrastructure** | Security (secrets, permissions), breaking changes, compatibility |
+| **UI/Presentation** | Accessibility, performance (re-renders, large bundles), state management |
+| **Tests** | Coverage adequacy, test quality (quick scan only — not a full analysis) |
+
+### Step 4: Always Run Verification Pass
+
+All findings from deep review must go through the standard verification pass (see `review-verification.md`).
+
+### Step 5: Severity-Grouped Output
+
+Group findings by severity instead of by file:
+
+```markdown
+## Critical Findings
+### Finding 1: ...
+### Finding 2: ...
+
+## Major Findings
+### Finding 3: ...
+
+## Minor Findings
+### Finding 4: ...
+
+## Suggestions
+### Finding 5: ...
+```
+
+### Step 6: Executive Summary
+
+Add an executive summary at the top of the review document, before the findings:
+
+```markdown
+## Executive Summary
+
+### Files Changed by Category
+
+| Category | Files | Lines Changed |
+|----------|-------|--------------|
+| Core Logic | {N} | +{add}/-{del} |
+| Infrastructure | {N} | +{add}/-{del} |
+| UI/Presentation | {N} | +{add}/-{del} |
+| Tests | {N} | +{add}/-{del} |
+
+### Risk Assessment
+
+**Overall Risk**: {Low | Medium | High}
+
+{1-2 sentence justification based on scope, categories affected, and finding severity distribution}
+
+### Top 3 Findings
+
+1. **[{Severity}]** {Finding title} — {one-line description} (`{file}:{line}`)
+2. **[{Severity}]** {Finding title} — {one-line description} (`{file}:{line}`)
+3. **[{Severity}]** {Finding title} — {one-line description} (`{file}:{line}`)
+```
+
+---
+
+## Insertion Points
+
+### For review-code-skill.md
+
+Insert as **Step 1b: Determine Review Depth** — after Step 1 (Identify Changed Files), before Step 2 (Load Review Patterns).
+
+**Lightweight shortcut**: If Small tier, skip Steps 2-5 (pattern loading, similar implementations, full analysis, pattern conflicts). Perform abbreviated analysis checking only security/logic/breaking changes. Skip verification pass. Generate lightweight template.
+
+**Deep expansion**: If Large tier, in Step 3 categorize files by type. In Step 4 run focused passes per category. In Step 5b apply verification to all findings. In Step 6 use deep template with severity grouping + executive summary.
+
+### For review-pr-skill.md
+
+Insert as **Step 1b: Determine Review Depth** — after Step 1 (Fetch PR Information), before Step 2 (Load Review Patterns).
+
+Same lightweight shortcut and deep expansion logic as review-code.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/skills/review-code-skill.md` | Add Step 1b (Determine Review Depth) |
+| `.claude/resources/skills/review-pr-skill.md` | Add Step 1b (Determine Review Depth) |
+| `.claude/resources/patterns/review-code-templates.md` | Add lightweight and deep templates |
+| `.claude/resources/core/review-verification.md` | Verification pass (skipped for lightweight, required for deep) |
+| `.claude/commands/review-code.md` | Add Adaptive Depth section |
+| `.claude/commands/review-pr.md` | Add Adaptive Depth section |