planflow-ai 1.2.0 → 1.3.2

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

@@ -0,0 +1,227 @@
+
+# Pattern Capture System
+
+## Purpose
+
+Silent, automatic capture of coding patterns and anti-patterns during skill execution. Patterns are buffered during work and presented for user approval at the end of the skill. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+**Buffer Location**: `flow/resources/pending-patterns.md`
+**Target Files**: `.claude/rules/core/allowed-patterns.md` (allowed) | `.claude/rules/core/forbidden-patterns.md` (forbidden)
+
+---
+
+## Behavior
+
+### During Skill Execution (Silent Capture)
+
+While executing `/execute-plan`, `/discovery-plan`, or `/review-code`, watch for patterns that meet the capture triggers below. When you identify a pattern worth capturing:
+
+1. **Do NOT interrupt the user** — continue the current work
+2. **Append the pattern** to `flow/resources/pending-patterns.md` using the buffer format below
+3. **Skip trivially obvious patterns** (e.g., "use semicolons") and patterns already documented in the target files
+
+### Capture Triggers
+
+| Trigger | Category | Example |
+|---------|----------|---------|
+| Recurring convention across 3+ files | allowed | All API routes use `withAuth()` wrapper |
+| Anti-pattern found during code review | forbidden | Nested callbacks in async code |
+| Workaround applied during execution | forbidden | Manual type assertion to fix broken generic |
+| User correction of approach | allowed/forbidden | "Don't use `any` here, use the generic" |
+| Pattern conflict between new and existing code | either | New code uses barrel exports, existing doesn't |
+| Convention discovered in existing codebase | allowed | All hooks follow `useXxx` naming with return tuple |
+
+### What NOT to Capture
+
+- Patterns already in `allowed-patterns.md` or `forbidden-patterns.md`
+- Generic language/framework best practices (these belong in `/setup` pattern files)
+- One-off decisions that won't recur
+- Patterns with no clear code example
+
+---
+
+## Buffer Format
+
+File: `flow/resources/pending-patterns.md`
+
+```markdown
+# Pending Patterns
+
+Patterns captured during skill execution. Review at end of skill.
+
+---
+
+## Entry: {pattern-name}
+
+- **Category**: allowed | forbidden
+- **Confidence**: high | medium | low
+- **Source**: {skill-name} {phase or step}
+- **Description**: {one-line description}
+
+### Code Example
+
+\`\`\`{language}
+// {GOOD or BAD} - {brief explanation}
+{code example}
+\`\`\`
+
+### Rationale
+
+{Why this pattern matters for this project}
+
+---
+```
+
+Each entry is separated by `---`. Multiple entries accumulate during execution.
+
+---
+
+## End-of-Skill Review Protocol
+
+After a skill completes its primary work (but before brain-capture), run the pattern review:
+
+### Step 1: Check Buffer
+
+Read `flow/resources/pending-patterns.md`. If empty or doesn't exist, skip the review entirely.
+
+### Step 2: Group and Present
+
+Group entries by category (allowed / forbidden) and present a numbered list:
+
+```markdown
+## Pattern Review
+
+The following patterns were identified during execution:
+
+### Allowed Patterns (to add to allowed-patterns.md)
+
+1. **{pattern-name}** — {description} (Confidence: {level})
+2. **{pattern-name}** — {description} (Confidence: {level})
+
+### Forbidden Patterns (to add to forbidden-patterns.md)
+
+3. **{pattern-name}** — {description} (Confidence: {level})
+
+**Options**: Enter numbers to approve (e.g., "1,3"), "all" to approve all, or "none" to skip.
+```
+
+### Step 3: Process User Selection
+
+- **"all"**: Write all patterns to their target files
+- **"none"**: Clear the buffer and continue
+- **Numbers (e.g., "1,3")**: Write only selected patterns
+- **Skip/ignore**: Treat as "none"
+
+### Step 4: Write Approved Patterns
+
+For each approved pattern:
+
+1. **Run conflict detection** (see below)
+2. **Append** to the `## Project Patterns` or `## Project Anti-Patterns` section of the target file
+3. **Use the auto-captured entry format** (see below)
+
+### Step 5: Clear Buffer
+
+After review (regardless of outcome), clear `flow/resources/pending-patterns.md` by writing an empty file with just the header:
+
+```markdown
+# Pending Patterns
+
+Patterns captured during skill execution. Review at end of skill.
+```
+
+---
+
+## Auto-Captured Entry Format
+
+Patterns written to the target files use the same structure as existing patterns, plus a metadata footer:
+
+### For `allowed-patterns.md`
+
+```markdown
+### {Pattern Name}
+
+{Description of what this pattern accomplishes.}
+
+\`\`\`{language}
+// GOOD - {brief explanation}
+{code example}
+\`\`\`
+
+**Why**: {Explanation of benefits.}
+
+_Auto-captured on {YYYY-MM-DD} from {source skill/phase}. Confidence: {level}._
+```
+
+### For `forbidden-patterns.md`
+
+```markdown
+### DON'T: {Pattern Name}
+
+**Problem**: {Brief description of why this is problematic.}
+
+\`\`\`{language}
+// BAD - {brief explanation}
+{code example}
+\`\`\`
+
+**Why This is Wrong**:
+
+- {Reason 1}
+- {Reason 2}
+
+**Fix**: {Description of the correct approach.}
+
+_Auto-captured on {YYYY-MM-DD} from {source skill/phase}. Confidence: {level}._
+```
+
+---
+
+## Conflict Detection
+
+Before writing an approved pattern, scan the target file for contradictions:
+
+### Detection Rules
+
+1. **Name match**: Pattern with the same or very similar name already exists
+2. **Semantic contradiction**: New pattern says "do X", existing pattern says "don't do X" (or vice versa)
+3. **Overlapping scope**: Both patterns address the same code construct but recommend different approaches
+
+### When Conflict Found
+
+Present the conflict to the user:
+
+```markdown
+**Conflict detected** with existing pattern "{existing pattern name}":
+
+- **Existing**: {summary of existing pattern}
+- **New**: {summary of new pattern}
+
+**Options**:
+1. **Add + Deprecate old** — Add new pattern and deprecate the existing one
+2. **Skip** — Don't add the new pattern
+3. **Add both** — Keep both patterns (they may apply in different contexts)
+```
+
+### Deprecation Format
+
+When deprecating a pattern, modify the existing entry's heading:
+
+```markdown
+### ~~Pattern Name~~ (DEPRECATED: {YYYY-MM-DD} — Superseded by "{new pattern name}")
+```
+
+The heading gets strikethrough. The body stays intact for historical reference. Do NOT delete deprecated patterns.
+
+---
+
+## Rules
+
+1. **Silent during execution**: Never interrupt work to discuss a captured pattern
+2. **Buffer is a file**: Always write to `flow/resources/pending-patterns.md` — never keep patterns only in conversation memory
+3. **User gate required**: Every pattern needs explicit user approval before being written to rule files
+4. **Check before capture**: Read target files before adding to buffer — skip already-documented patterns
+5. **One review per skill**: Present the review once at the end, not after each phase
+6. **Never delete rule entries**: Deprecated patterns stay with strikethrough for history
+7. **Metadata footer required**: Every auto-captured entry must include the `_Auto-captured on...` line
+8. **Clean buffer after review**: Always clear pending-patterns.md after the review step

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 |