planflow-ai 1.2.0 → 1.3.0

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/patterns/_index.md

@@ -5,7 +5,7 @@
 
 Pattern files provide templates, examples, and guidelines for specific workflows. This is the largest category covering discovery, planning, testing, code review, and contracts.
 
-**Total Files**: 10 files, ~3,320 lines
+**Total Files**: 11 files, ~3,420 lines
 **Reference Codes**: PTN-BR-1 through PTN-PR-6
 
 ---
@@ -21,6 +21,13 @@ Pattern files provide templates, examples, and guidelines for specific workflows
 | PTN-BR-3 | Feature status lifecycle and index update rules | brain-patterns.md | 162-210 |
 | PTN-BR-4 | Learning subdirectory for teaching curricula | brain-patterns.md | 12-14 |
 
+### Brainstorm Templates (`brainstorm-templates.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| PTN-BST-1 | Brainstorm document template with "For Discovery" bridge | brainstorm-templates.md | 5-75 |
+| PTN-BST-2 | Status definitions and file naming conventions | brainstorm-templates.md | 77-105 |
+
 ### Contract Patterns (`contract-patterns.md`)
 
 | Code | Description | Source | Lines |
@@ -186,5 +193,8 @@ Pattern files provide templates, examples, and guidelines for specific workflows
 - **PTN-REV-***: Code review templates
 - **PTN-PR-***: PR review patterns
 
+### Brainstorm
+- **PTN-BST-***: Brainstorm output templates
+
 ### Contracts
 - **PTN-CON-***: Integration contract patterns

package/.claude/resources/patterns/brainstorm-templates.md

@@ -0,0 +1,132 @@
+
+## Brainstorm Document Template
+
+Use this template when generating brainstorm output files:
+
+```markdown
+# Brainstorm: {Topic Name}
+
+**Date**: {YYYY-MM-DD}
+**Participants**: User + AI
+**Status**: {crystallized | exploratory | early-stage}
+
+---
+
+## Core Idea
+
+{The central thesis as it evolved during the conversation. This should be
+a clear, concise description of what the idea IS — not how to build it.}
+
+---
+
+## Key Decisions
+
+Forks that were discussed and resolved during the brainstorm.
+
+| # | Decision | Reasoning |
+|---|----------|-----------|
+| 1 | {What was decided} | {Why this choice was made} |
+| 2 | {What was decided} | {Why this choice was made} |
+
+---
+
+## Open Questions
+
+Things raised during the brainstorm that remain unresolved.
+
+- {Question 1}
+- {Question 2}
+
+---
+
+## Constraints Discovered
+
+Limitations that surfaced during the conversation.
+
+- {Constraint 1 — where it came from}
+- {Constraint 2 — where it came from}
+
+---
+
+## Inspirations & References
+
+Existing tools, patterns, code, or external ideas that came up.
+
+- {Reference 1} — {how it relates to the idea}
+- {Reference 2} — {how it relates to the idea}
+
+---
+
+## Rejected Alternatives
+
+Things considered and explicitly discarded, with reasoning preserved.
+
+| Alternative | Why Rejected |
+|-------------|-------------|
+| {Option A} | {Reasoning for rejection} |
+| {Option B} | {Reasoning for rejection} |
+
+---
+
+## For Discovery
+
+This section bridges the brainstorm into the discovery phase. Feed this file
+to `/discovery-plan` to ground the idea in the project's codebase.
+
+### Resolved During Brainstorm
+
+These decisions are settled. Discovery should NOT re-ask them.
+
+- {Decision 1}
+- {Decision 2}
+
+### Still Open (Discovery Should Investigate)
+
+These questions need codebase analysis and technical grounding.
+
+- {Question 1 — what discovery should look for}
+- {Question 2 — what discovery should look for}
+
+### Rejected (Do Not Revisit)
+
+These were explicitly considered and rejected. Discovery should not re-propose them.
+
+- {Rejected alternative 1}
+- {Rejected alternative 2}
+```
+
+---
+
+## Status Definitions
+
+| Status | Meaning |
+|--------|---------|
+| `crystallized` | Idea is clear and well-defined — ready for discovery |
+| `exploratory` | Idea has shape but still has open questions |
+| `early-stage` | Initial exploration — needs more brainstorming or research |
+
+---
+
+## File Naming
+
+- **Format**: `brainstorm_{kebab-case-topic}_v{version}.md`
+- **Location**: `flow/brainstorms/`
+- **Examples**:
+  - `brainstorm_plugin-system_v1.md`
+  - `brainstorm_real-time-notifications_v1.md`
+  - `brainstorm_error-recovery-strategy_v2.md`
+
+---
+
+## Usage with Discovery
+
+The brainstorm file is designed to be fed directly into `/discovery-plan`:
+
+```bash
+/discovery-plan @flow/brainstorms/brainstorm_plugin-system_v1.md
+```
+
+Discovery will:
+1. Read the brainstorm and inherit resolved decisions
+2. Use "Still Open" questions as starting points for codebase investigation
+3. Respect "Rejected" alternatives and not re-propose them

package/.claude/resources/patterns/discovery-templates.md

@@ -102,6 +102,50 @@ Use this template when creating discovery documents:
 
 [Identified difficulties]
 
+## Design Context
+
+> Include this section only when UI work is confirmed during discovery.
+
+### Design Personality
+{personality name} — {brief description of the visual style}
+
+### Color Palette
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | #XXXXXX | Main actions, CTAs |
+| Secondary | #XXXXXX | Supporting elements |
+| Background | #XXXXXX | Page/card backgrounds |
+| Surface | #XXXXXX | Elevated surfaces |
+| Text Primary | #XXXXXX | Main body text |
+| Text Secondary | #XXXXXX | Secondary/muted text |
+| Error | #XXXXXX | Error states |
+| Success | #XXXXXX | Success states |
+
+### Typography
+| Element | Font | Size | Weight |
+|---------|------|------|--------|
+| Heading 1 | {font} | {size} | {weight} |
+| Heading 2 | {font} | {size} | {weight} |
+| Body | {font} | {size} | {weight} |
+| Caption | {font} | {size} | {weight} |
+
+### Spacing Scale
+| Token | Value |
+|-------|-------|
+| xs | {value} |
+| sm | {value} |
+| md | {value} |
+| lg | {value} |
+| xl | {value} |
+
+### Component Patterns
+- {Pattern 1}: {description}
+- {Pattern 2}: {description}
+
+### Design Source
+- **Source**: {screenshots / Figma export / design personality / existing system.md}
+- **Files**: {list of provided design files, if any}
+
 ## Proposed Approach
 
 [High-level approach recommendation based on findings]

package/.claude/resources/skills/_index.md

@@ -5,15 +5,29 @@
 
 Skills implement the workflow logic for commands. Each skill orchestrates a specific process like discovery, planning, execution, or code review.
 
-**Total Files**: 10 files, ~3,100 lines
+**Total Files**: 12 files, ~3,500 lines
 **Reference Codes**: SKL-BR-1 through SKL-TEST-5
 
 > **Note**: All skills (except brain and flow) include a Resource Capture section. During execution, the LLM watches for valuable reference materials and asks the user before saving to `flow/resources/`. See `.claude/resources/core/resource-capture.md` for full rules.
+>
+> **Note**: The execute-plan, discovery, and review-code skills also include Pattern Capture. During execution, the LLM silently buffers coding patterns and anti-patterns, then presents them for user approval at the end. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `forbidden-patterns.md`. See `.claude/resources/core/pattern-capture.md` for full rules.
+>
+> **Note**: The execute-plan skill supports **Model Routing** — automatic model selection per phase based on complexity scores (0-3 → haiku, 4-5 → sonnet, 6-10 → opus). Controlled by `model_routing` in `flow/.flowconfig`. See `.claude/resources/core/model-routing.md` for full rules.
+>
+> **Note**: The discovery skill also includes **Design Awareness**. During discovery, the LLM asks whether the feature involves UI work and captures structured design tokens (colors, typography, spacing) into a `## Design Context` section. During execution, these tokens are auto-injected into UI phase prompts. See `.claude/resources/core/design-awareness.md` for full rules.
 
 ---
 
 ## Reference Codes
 
+### Brainstorm Skill (`brainstorm-skill.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-BS-1 | Purpose, restrictions, and inputs | brainstorm-skill.md | 8-60 |
+| SKL-BS-2 | Conversational loop, question types, and silent tracking | brainstorm-skill.md | 62-150 |
+| SKL-BS-3 | End detection, summary, output generation, and tasklist offer | brainstorm-skill.md | 152-220 |
+
 ### Brain Skill (`brain-skill.md`)
 
 | Code | Description | Source | Lines |
@@ -58,6 +72,15 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 | SKL-LRN-3 | Teaching mode restrictions and curriculum generation | learn-skill.md | 140-175 |
 | SKL-LRN-4 | Step confirmation flow and storage rules | learn-skill.md | 177-210 |
 
+### Flow Cost Skill (`flow-cost.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-COST-1 | Usage and filter flags | flow-cost.md | 7-18 |
+| SKL-COST-2 | Implementation steps (read, filter, aggregate, format) | flow-cost.md | 20-85 |
+| SKL-COST-3 | Output format examples (default, detail, session) | flow-cost.md | 87-145 |
+| SKL-COST-4 | JSONL schema and error handling | flow-cost.md | 147-195 |
+
 ### Execute Plan Skill (`execute-plan-skill.md`)
 
 | Code | Description | Source | Lines |
@@ -164,7 +187,9 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 
 | Command | Skill | Key Codes |
 |---------|-------|-----------|
+| `/brainstorm` | brainstorm-skill | SKL-BS-1 through SKL-BS-3 |
 | `/brain` | brain-skill | SKL-BR-1 through SKL-BR-3 |
+| `/flow cost` | flow-cost | SKL-COST-1 through SKL-COST-4 |
 | `/learn` | learn-skill | SKL-LRN-1 through SKL-LRN-4 |
 | `/discovery-plan` | discovery-skill | SKL-DIS-1 through SKL-DIS-4 |
 | `/create-plan` | create-plan-skill | SKL-PLN-1 through SKL-PLN-4 |
@@ -186,7 +211,9 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 | execute-plan-skill | 388 | 6 | High - phase execution logic |
 | review-code-skill | 308 | 5 | Medium - pattern matching |
 | discovery-skill | 295 | 4 | Medium - requirements gathering |
+| brainstorm-skill | 280 | 3 | Medium - structured exploration with interactive questions |
 | write-tests-skill | 294 | 5 | Medium - iterative testing |
 | create-plan-skill | 271 | 4 | Low - plan structuring |
 | learn-skill | 185 | 4 | Medium - pattern extraction + teaching mode |
+| flow-cost | 195 | 4 | Low - JSONL parsing and reporting |
 | create-contract-skill | 239 | 4 | Low - contract generation |