planflow-ai 1.3.0 → 1.3.4

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 |

package/.claude/resources/core/review-multi-agent.md

@@ -0,0 +1,289 @@
+
+# Review Multi-Agent Parallel Review
+
+## Purpose
+
+For large changesets (500+ lines, Deep mode), split the review into specialized subagents running in parallel. Each subagent focuses on a single concern, producing deeper findings than a single-pass review. A coordinator merges, deduplicates, verifies, and ranks the results.
+
+**Scope**: `/review-code` and `/review-pr` — activated only when adaptive depth selects **Deep** mode (500+ lines).
+
+**Goal**: Higher quality reviews for large PRs by eliminating context-switching between security, logic, performance, and pattern compliance concerns.
+
+---
+
+## When to Activate
+
+| Review Mode | Multi-Agent? |
+|-------------|-------------|
+| Lightweight (< 50 lines) | No |
+| Standard (50–500 lines) | No |
+| Deep (500+ lines) | **Yes** |
+
+Multi-agent is part of the Deep mode pipeline. It replaces the single-pass analysis steps with parallel subagent execution.
+
+---
+
+## Architecture
+
+```
+Coordinator (main agent)
+    │
+    ├─► Subagent: Security Review        (parallel)
+    ├─► Subagent: Logic & Bugs Review    (parallel)
+    ├─► Subagent: Performance Review     (parallel)
+    └─► Subagent: Pattern Compliance     (parallel)
+    │
+    ▼
+Coordinator: Collect → Deduplicate → Verify → Re-Rank → Output
+```
+
+---
+
+## Subagent Definitions
+
+### 1. Security Review Agent
+
+**Focus**: Vulnerabilities, hardcoded secrets, auth bypass, injection (SQL/XSS/command), OWASP top 10, exposed credentials, insecure deserialization, missing CSRF protection.
+
+**Model**: sonnet
+
+**Prompt template**:
+```
+You are a security-focused code reviewer. Analyze the provided diff ONLY for security vulnerabilities.
+
+Check for:
+- Hardcoded secrets, API keys, tokens
+- SQL/NoSQL injection
+- XSS vulnerabilities
+- Command injection
+- Authentication/authorization bypass
+- Insecure deserialization
+- Missing CSRF protection
+- Exposed sensitive data in logs or responses
+- Insecure cryptographic practices
+
+IGNORE: code style, performance, naming conventions, test coverage.
+
+Return findings as a JSON array. Each finding must have:
+- file: string (file path)
+- line: number (line number)
+- severity: "Critical" | "Major" | "Minor"
+- title: string (short finding name)
+- description: string (detailed explanation)
+- suggested_fix: string (code suggestion)
+- confidence: number (0.0-1.0)
+```
+
+### 2. Logic & Bugs Review Agent
+
+**Focus**: Edge cases, null/undefined handling, off-by-one errors, race conditions, incorrect boolean logic, infinite loops, unreachable code, wrong return types, missing error handling.
+
+**Model**: sonnet
+
+**Prompt template**:
+```
+You are a logic-focused code reviewer. Analyze the provided diff ONLY for logic bugs and edge cases.
+
+Check for:
+- Null/undefined access without guards
+- Off-by-one errors in loops and slicing
+- Race conditions in async code
+- Incorrect boolean logic (wrong operator, inverted condition)
+- Infinite loops or recursion without base case
+- Unreachable code paths
+- Wrong return types or missing returns
+- Unhandled promise rejections
+- Missing error handling on fallible operations
+
+IGNORE: security vulnerabilities, performance, code style, naming.
+
+Return findings as a JSON array. Each finding must have:
+- file: string (file path)
+- line: number (line number)
+- severity: "Critical" | "Major" | "Minor"
+- title: string (short finding name)
+- description: string (detailed explanation)
+- suggested_fix: string (code suggestion)
+- confidence: number (0.0-1.0)
+```
+
+### 3. Performance Review Agent
+
+**Focus**: N+1 queries, memory leaks, unnecessary re-renders, blocking I/O on main thread, excessive allocations, missing pagination, inefficient algorithms, large bundle impacts.
+
+**Model**: sonnet
+
+**Prompt template**:
+```
+You are a performance-focused code reviewer. Analyze the provided diff ONLY for performance issues.
+
+Check for:
+- N+1 database queries
+- Memory leaks (event listeners not removed, unclosed resources)
+- Unnecessary re-renders (React) or recomputations
+- Blocking I/O on main thread
+- Excessive object/array allocations in hot paths
+- Missing pagination on unbounded queries
+- O(n²) or worse algorithms where O(n) is possible
+- Large synchronous operations that should be async
+- Bundle size impacts (large imports that could be lazy-loaded)
+
+IGNORE: security vulnerabilities, logic bugs, code style, naming.
+
+Return findings as a JSON array. Each finding must have:
+- file: string (file path)
+- line: number (line number)
+- severity: "Major" | "Minor" | "Suggestion"
+- title: string (short finding name)
+- description: string (detailed explanation)
+- suggested_fix: string (code suggestion)
+- confidence: number (0.0-1.0)
+```
+
+### 4. Pattern Compliance Review Agent
+
+**Focus**: Violations of `forbidden-patterns.md`, deviations from `allowed-patterns.md`, naming inconsistencies, structural pattern conflicts with existing codebase.
+
+**Model**: haiku
+
+**Prompt template**:
+```
+You are a pattern compliance reviewer. Analyze the provided diff against the project's coding standards.
+
+Forbidden patterns to check (violations of these are findings):
+{contents of forbidden-patterns.md Project Anti-Patterns section}
+
+Allowed patterns to verify (deviations from these are findings):
+{contents of allowed-patterns.md Project Patterns section}
+
+Also check for:
+- Naming inconsistencies with existing codebase conventions
+- Import organization deviations
+- Error handling pattern deviations
+- Export pattern inconsistencies
+
+IGNORE: security vulnerabilities, logic bugs, performance issues.
+
+Return findings as a JSON array. Each finding must have:
+- file: string (file path)
+- line: number (line number)
+- severity: "Minor" | "Suggestion"
+- title: string (short finding name)
+- description: string (detailed explanation with pattern reference)
+- suggested_fix: string (code suggestion)
+- confidence: number (0.0-1.0)
+```
+
+---
+
+## Subagent Input
+
+Each subagent receives:
+
+1. **The diff** — For review-code: output of `git diff`. For review-pr: output of `gh pr diff` or Azure DevOps diff.
+2. **File categorization** — The file-to-category mapping from adaptive depth Step 1 (Core Logic, Infrastructure, UI, Tests)
+3. **Category-specific context** — Only the pattern files relevant to the subagent's focus
+4. **Instructions** — The subagent-specific prompt template above
+
+For very large diffs (2000+ lines), the coordinator may split the diff by file category and send each subagent only its most relevant files:
+- Security agent → all files (security issues can be anywhere)
+- Logic agent → Core Logic + Infrastructure files
+- Performance agent → Core Logic + UI files
+- Pattern agent → all files
+
+---
+
+## Coordinator Behavior
+
+The coordinator (main agent) orchestrates the entire flow:
+
+### Step 1: Spawn Subagents
+
+Launch all 4 subagents in parallel using the Agent tool. Each subagent uses `subagent_type: "general-purpose"` with the appropriate model override.
+
+```
+Launch in parallel:
+- Agent(model: "sonnet", prompt: security_prompt)
+- Agent(model: "sonnet", prompt: logic_prompt)
+- Agent(model: "sonnet", prompt: performance_prompt)
+- Agent(model: "haiku", prompt: patterns_prompt)
+```
+
+### Step 2: Collect Results
+
+Wait for all subagents to complete. Parse the JSON findings arrays from each.
+
+### Step 3: Deduplicate
+
+Scan for overlapping findings (same file + line range within ±5 lines + similar description):
+
+| Overlap Type | Resolution |
+|-------------|------------|
+| Exact match (same file, same line, same issue) | Merge into one finding, note both categories |
+| Near match (same file, ±5 lines, similar issue) | Merge if clearly the same root cause |
+| Different aspects of same code | Keep as separate findings |
+
+When merging:
+- Use the **higher severity** from the overlapping findings
+- Use the **higher confidence** score
+- Combine descriptions from both agents
+- Note all contributing categories in the finding
+
+### Step 4: Verify
+
+Run the standard verification pass on all deduplicated findings. See `.claude/resources/core/review-verification.md`.
+
+### Step 5: Re-Rank and Group
+
+Run the standard severity re-ranking. See `.claude/resources/core/review-severity-ranking.md`.
+
+### Step 6: Generate Output
+
+Use the deep review template with severity-grouped findings and executive summary. Add a Multi-Agent Summary section after Review Information:
+
+```markdown
+## Review Agents
+
+| Agent | Model | Findings | After Dedup |
+|-------|-------|----------|-------------|
+| Security | sonnet | {N} | {N} |
+| Logic & Bugs | sonnet | {N} | {N} |
+| Performance | sonnet | {N} | {N} |
+| Pattern Compliance | haiku | {N} | {N} |
+| **Total** | | **{N}** | **{N}** |
+
+Duplicates removed: {N}
+```
+
+---
+
+## Insertion Points
+
+### For review-code-skill.md
+
+In the **Deep mode** path of Step 1b, replace the instruction "Proceed with all steps" with:
+
+> **If Deep**: Activate multi-agent parallel review. See `.claude/resources/core/review-multi-agent.md`. Spawn 4 specialized subagents (security, logic, performance, patterns) in parallel. Coordinator collects results, deduplicates, then proceeds to Step 5b (verification), Step 5c (re-ranking), Step 6b (pattern review), and Step 6 (output using deep template).
+
+Steps 2–5 (pattern loading, similar implementations, analysis, pattern conflicts) are handled by the subagents instead of the main agent.
+
+### For review-pr-skill.md
+
+In the **Deep mode** path of Step 1b, replace the instruction "Proceed with all steps" with:
+
+> **If Deep**: Activate multi-agent parallel review. See `.claude/resources/core/review-multi-agent.md`. Spawn 4 specialized subagents (security, logic, performance, patterns) in parallel. Coordinator collects results, deduplicates, then proceeds to Step 3b (verification), Step 3c (re-ranking), and Step 4 (output using deep template with severity grouping and executive summary).
+
+Steps 2–3 (pattern loading, analysis) are handled by the subagents instead of the main agent.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/core/review-adaptive-depth.md` | Triggers Deep mode (prerequisite) |
+| `.claude/resources/core/review-verification.md` | Verification pass (run by coordinator after dedup) |
+| `.claude/resources/core/review-severity-ranking.md` | Re-ranking (run by coordinator after verification) |
+| `.claude/resources/skills/review-code-skill.md` | Update Deep mode path in Step 1b |
+| `.claude/resources/skills/review-pr-skill.md` | Update Deep mode path in Step 1b |
+| `.claude/resources/patterns/review-code-templates.md` | Deep template gets Review Agents section |

package/.claude/resources/core/review-severity-ranking.md

@@ -0,0 +1,149 @@
+
+# Review Severity Re-Ranking
+
+## Purpose
+
+After all findings are collected and verified, re-rank them by actual impact rather than listing in file order. Group related findings across files and present critical issues first. This applies to **all review modes** (lightweight findings are already minimal, but if multiple issues are found, they should still be severity-ordered).
+
+**Scope**: `/review-code` (Step 5c) and `/review-pr` (Step 3c). Applied after verification, before generating the output document.
+
+**Goal**: Ensure the most impactful findings appear first. Reviewers should never have to scan past 10 minor style issues to find a critical security bug.
+
+---
+
+## Ranking Algorithm
+
+After verification classifies findings as Confirmed or Likely, sort using this priority:
+
+1. **Severity** (primary): Critical → Major → Minor → Suggestion
+2. **Confidence** (secondary, within same severity): Confirmed → Likely
+3. **Fix complexity** (tertiary, within same confidence): Lower complexity first (quick wins surface earlier)
+
+This ranking applies regardless of which file the finding came from.
+
+---
+
+## Grouping Related Findings
+
+Before final output, scan the sorted findings for groupable patterns:
+
+| Pattern | Group Condition | Example Group Title |
+|---------|----------------|---------------------|
+| Same issue type in multiple files | ≥ 2 findings with matching issue category | "Missing input validation in 3 API endpoints" |
+| Same root cause | ≥ 2 findings traceable to one underlying problem | "Inconsistent error handling (5 occurrences)" |
+| Causal chain | Findings where one enables/causes another | "Auth bypass: missing check → unprotected route → data exposure" |
+
+### Grouping Rules
+
+- **Only group when genuinely related** — don't force-group unrelated findings just because they share a severity level
+- **Small reviews (1-3 findings)**: No grouping. Keep findings individual.
+- **Use the highest severity in the group** as the group's severity level
+- **Show individual occurrences** within the group with `file:line` references
+- **Provide a single suggested fix** that addresses all occurrences when possible
+
+### Grouped Finding Format
+
+```markdown
+### Finding N: {Group Title} ({count} occurrences)
+
+| Field          | Value                                            |
+| -------------- | ------------------------------------------------ |
+| Severity       | {Highest severity in group}                      |
+| Fix Complexity | {Average complexity}/10 - {Level}                |
+| Pattern        | {Reference to pattern from rules, if applicable} |
+
+**Occurrences**:
+
+| # | File | Line | Status |
+|---|------|------|--------|
+| 1 | `{file_path}` | {line} | {Confirmed/Likely} |
+| 2 | `{file_path}` | {line} | {Confirmed/Likely} |
+| 3 | `{file_path}` | {line} | {Confirmed/Likely} |
+
+**Description**:
+{Explanation of the shared issue pattern}
+
+**Suggested Fix**:
+\`\`\`{language}
+// Single fix pattern that addresses all occurrences
+\`\`\`
+```
+
+---
+
+## Executive Summary Trigger
+
+| Review Mode | Trigger |
+|-------------|---------|
+| **Lightweight** | Never (too few findings to warrant) |
+| **Standard** | When total findings ≥ 5 |
+| **Deep** | Always (built into deep template) |
+
+When triggered in standard mode, prepend this before the findings section:
+
+```markdown
+## Executive Summary
+
+**Risk level**: {Low | Medium | High}
+
+**Top issues to address**:
+
+1. {Finding title} ({Severity}) — `{file}:{line}`
+2. {Finding title} ({Severity}) — `{file}:{line}`
+3. {Finding title} ({Severity}) — `{file}:{line}`
+```
+
+Show up to 3 top findings. Derive risk level from:
+- **High**: Any Critical finding, or ≥ 3 Major findings
+- **Medium**: Any Major finding, or ≥ 5 Minor findings
+- **Low**: Only Minor/Suggestion findings, fewer than 5 total
+
+---
+
+## Output Structure
+
+All review modes now use severity-grouped output instead of per-file ordering:
+
+```markdown
+## Critical Findings
+### 1. {Finding title}
+...
+
+## Major Findings
+### 2. {Finding title}
+...
+
+## Minor Findings
+### 3. {Finding title}
+...
+
+## Suggestions
+### 4. {Finding title}
+...
+```
+
+**Empty sections**: Omit severity sections that have no findings (e.g., if no Critical findings, skip the "Critical Findings" heading entirely).
+
+---
+
+## Insertion Points
+
+### For review-code-skill.md
+
+Insert as **Step 5c: Re-Rank and Group Findings** — after Step 5b (Verify Findings), before Step 6b (Pattern Review).
+
+### For review-pr-skill.md
+
+Insert as **Step 3c: Re-Rank and Group Findings** — after Step 3b (Verify Findings), before Step 4 (Generate Document).
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/skills/review-code-skill.md` | Add Step 5c (Re-Rank and Group) |
+| `.claude/resources/skills/review-pr-skill.md` | Add Step 3c (Re-Rank and Group) |
+| `.claude/resources/patterns/review-code-templates.md` | Standard template uses severity grouping |
+| `.claude/resources/core/review-adaptive-depth.md` | Deep mode already severity-groups; this extends to standard |
+| `.claude/resources/core/review-verification.md` | Verification runs before re-ranking |