planflow-ai 1.2.0 → 1.3.0

package/.claude/resources/skills/brainstorm-skill.md

@@ -0,0 +1,284 @@
+
+# Brainstorm Skill
+
+## Purpose
+
+Facilitate a **free-form, conversational exploration** of an idea through collaborative dialogue. The LLM acts as a sharp coworker at a whiteboard — asking one question at a time, challenging assumptions, suggesting angles, and silently tracking the emerging structure.
+
+This skill is the **pre-discovery phase** — pure ideation before requirements formalization. It does NOT:
+
+- Write any source code
+- Modify any source files
+- Create implementation plans
+- Execute any implementation
+- Scan the codebase (unless user explicitly asks)
+- Write to `flow/brain/` or `flow/memory.md`
+- Automatically update `flow/tasklist.md`
+
+---
+
+## Restrictions
+
+### Allowed Actions
+
+| Action | Purpose |
+|--------|---------|
+| Conversational dialogue | Core brainstorm interaction |
+| Read codebase files | **Only when user explicitly asks** (e.g., "check how X works") |
+| Write to `flow/brainstorms/` | Save brainstorm output document |
+| Read `flow/brainstorms/` | Check for existing brainstorms on same topic |
+| Edit `flow/tasklist.md` | **Only when user explicitly requests** at the end |
+
+### Forbidden Actions
+
+| Action | Reason |
+|--------|--------|
+| Write source code | Brainstorm is ideation only |
+| Write to `flow/brain/` | No brain integration |
+| Write to `flow/memory.md` | No memory integration |
+| Auto-update `flow/tasklist.md` | Only on explicit user request |
+| Deep codebase scanning | That's discovery's job — brainstorm stays in idea space |
+| Create plans or discovery docs | Brainstorm only produces brainstorm files |
+| Run build/test commands | No execution commands |
+
+---
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `idea` | Yes | Free-text description of the idea to explore |
+| `topic_name` | Optional | Short name for the topic (derived from idea if not provided) |
+
+---
+
+## Workflow
+
+### Step 1: Parse Idea and Open the Conversation
+
+1. Read the user's idea
+2. **Show understanding** — restate the core concept in your own words to confirm alignment
+3. **Add an initial insight** — offer a first reaction, angle, or connection
+4. **Ask one focused question** — the first question that would most help shape the idea
+
+**Tone**: Casual, collaborative, curious. Like a coworker who just heard your idea and is genuinely interested.
+
+**Example**:
+
+```
+User: /brainstorm I want to add a plugin system to plan-flow
+
+LLM: A plugin system — so users could extend plan-flow with custom skills
+or hooks without forking the repo. That could unlock a whole ecosystem.
+
+The first thing I'd want to understand: are you thinking plugins that
+add new slash commands, or something lower-level like middleware that
+hooks into the existing skill execution pipeline?
+```
+
+---
+
+### Step 2: Structured Exploration Loop
+
+This is the core of the brainstorm. After the open-ended first round (Step 1), switch to structured batched questions using the `AskUserQuestion` tool. Repeat until the user signals they're done.
+
+**Per Round Behavior**:
+
+1. **Formulate questions** — create 3-4 questions based on the current state of the brainstorm, each with 2-4 options
+2. **Present via `AskUserQuestion`** — call the tool with the batch of questions (see `.claude/resources/tools/interactive-questions-tool.md` for tool usage)
+3. **Wait for responses** — user picks options or types custom answers via "Other"
+4. **Process answers** — update silent tracking with the user's choices
+5. **Commentary** — react to the answers in regular chat: connect dots, surface insights, challenge assumptions, make suggestions. This is what keeps it feeling like a brainstorm, not a form.
+6. **Check for end signals** — if user typed "done", "wrap up", etc. in any "Other" field or in response to commentary, proceed to Step 3
+7. **Repeat** — formulate next batch based on what was learned
+
+**Question Formulation Rules**:
+
+- Each question must have a **recommended option** as the first option with "(Recommended)" suffix on the label
+- Mix question types across each batch — don't ask 4 clarifying questions in a row
+- When the idea is too vague for structured options on a particular point, ask that question as regular chat within the commentary instead — not everything needs to go through `AskUserQuestion`
+- Cap at **3-4 questions per `AskUserQuestion` call** (tool limit is 4)
+- Each option needs a `label` (1-5 words) and `description` (explanation of what it means)
+
+**Question Types to Mix**:
+
+| Type | Purpose | Example Question |
+|------|---------|---------|
+| Clarifying | Understand the concept deeper | "What scope should this feature cover?" with options like "MVP only (Recommended)" / "Full feature" / "Phased rollout" |
+| Challenging | Push back on assumptions | "Is this the right approach?" with options presenting alternatives |
+| Expanding | Broaden scope or find connections | "What else could this enable?" with options for related features |
+| Constraining | Find the MVP / simplest version | "What can we cut from v1?" with options for scope reduction |
+| Connecting | Link to existing knowledge | "Which existing pattern fits best?" with options for known patterns |
+
+**Commentary Between Batches**:
+
+The commentary is what makes this a brainstorm and not a survey. After processing each batch of answers:
+
+- **React** — show you understood the choices and what they mean together
+- **Connect** — link answers across questions ("Your choice of X combined with Y suggests...")
+- **Challenge** — if an answer seems contradictory or surprising, call it out
+- **Suggest** — offer an insight the user might not have considered ("What if we also...")
+- **Transition** — naturally lead into why the next batch of questions matters
+
+Keep commentary concise (2-4 sentences). Don't lecture — think sharp coworker at a whiteboard.
+
+**Silent Tracking**:
+
+While processing responses and writing commentary, maintain an internal running tally of:
+
+| Category | What to Track |
+|----------|--------------|
+| **Core Idea** | The central thesis — evolves as options are selected |
+| **Key Decisions** | Options chosen by the user (with reasoning from descriptions) |
+| **Open Questions** | Things raised but not yet resolved |
+| **Constraints** | Limitations that surfaced (technical, time, scope, etc.) |
+| **Inspirations / References** | Existing code, patterns, tools, or external ideas mentioned |
+| **Rejected Alternatives** | Options NOT chosen — preserve as rejected alternatives with reasoning |
+
+Do NOT show this tracking to the user during the conversation. It's used to generate the summary and output file.
+
+---
+
+### Step 3: End Detection
+
+The brainstorm ends when the user signals they're done. Watch for:
+
+**Clear End Signals** (transition immediately):
+- "I'm done"
+- "Let's wrap up"
+- "That's enough"
+- "Summarize"
+- "Let's move on"
+- "I think we've covered it"
+- "Generate the file"
+
+**Ambiguous Signals** (ask to confirm):
+- Long pause with a short response like "yeah" or "ok"
+- "I think so" or "maybe"
+- Response: "Sounds like we might be reaching a natural stopping point — should I summarize what we've discussed, or is there another angle you want to explore?"
+
+**Never End Signals** (keep going):
+- User asks a new question
+- User introduces a new angle
+- User says "what about..." or "also..."
+- User is mid-thought
+
+**Default**: When in doubt, keep the brainstorm going. It's better to explore one more angle than to cut short.
+
+---
+
+### Step 4: Present Summary
+
+When the brainstorm ends, present a structured summary of what was discussed:
+
+```markdown
+## Brainstorm Summary: {topic}
+
+### Core Idea
+{The central thesis as it evolved during the conversation}
+
+### Key Decisions
+- {Decision 1} — {reasoning}
+- {Decision 2} — {reasoning}
+
+### Open Questions
+- {Question still unresolved}
+
+### Constraints
+- {Limitation that surfaced}
+
+### Inspirations & References
+- {Tool, pattern, or idea that came up}
+
+### Rejected Alternatives
+- {Alternative considered and discarded} — {why}
+```
+
+Present this as a chat message (not a file yet).
+
+---
+
+### Step 5: Offer MD File Generation
+
+After presenting the summary, ask:
+
+```markdown
+Would you like me to save this as a brainstorm document? It can be used as
+input for `/discovery-plan` later.
+```
+
+- **If yes**: Proceed to Step 6
+- **If no**: Proceed to Step 7 (skip file generation)
+
+---
+
+### Step 6: Generate Output File
+
+**Location**: `flow/brainstorms/brainstorm_{topic}_v{version}.md`
+
+**Topic naming**: kebab-case derived from the idea (e.g., "plugin system" → `plugin-system`)
+
+**Versioning**: Check `flow/brainstorms/` for existing files with the same topic. Increment version if found.
+
+**Template**: Use the template from `.claude/resources/patterns/brainstorm-templates.md`
+
+The output file must include all tracked categories plus the **"For Discovery" bridge section** that makes the handoff to `/discovery-plan` seamless.
+
+After writing, report:
+
+```markdown
+Brainstorm saved.
+
+**Created**: `flow/brainstorms/brainstorm_{topic}_v{version}.md`
+
+To continue: `/discovery-plan @flow/brainstorms/brainstorm_{topic}_v{version}.md`
+```
+
+---
+
+### Step 7: Offer Tasklist Entry (Optional)
+
+After the brainstorm completes (whether or not an MD file was generated):
+
+```markdown
+Want me to add this to the tasklist?
+```
+
+- **If yes**: Add "Discovery: {topic}" to the **To Do** section of `flow/tasklist.md`
+- **If no**: Done — do not add anything
+
+---
+
+## Output Format
+
+See `.claude/resources/patterns/brainstorm-templates.md` for the full output template.
+
+---
+
+## Validation Checklist
+
+Before completing the brainstorm, verify:
+
+- [ ] Questions presented in batches with options via `AskUserQuestion`
+- [ ] Commentary provided between question batches
+- [ ] Open-ended first round (Step 1) before structured batches
+- [ ] User signaled end (not auto-ended by LLM)
+- [ ] Summary presented before offering file generation
+- [ ] If file generated: saved to `flow/brainstorms/` with correct naming
+- [ ] If file generated: includes "For Discovery" bridge section
+- [ ] Tasklist only updated if user explicitly requested
+- [ ] No source code written
+- [ ] No brain entries created
+- [ ] No memory entries created
+- [ ] Codebase only read when user explicitly asked
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/commands/brainstorm.md` | Command file that invokes this skill |
+| `.claude/resources/patterns/brainstorm-templates.md` | Output file template |
+| `.claude/resources/skills/discovery-skill.md` | Discovery skill that consumes brainstorm output |
+| `flow/brainstorms/` | Output directory for brainstorm documents |

package/.claude/resources/skills/discovery-skill.md

@@ -49,7 +49,7 @@ This skill is **strictly for gathering and documenting requirements**. The proce
 | Write to `flow/discovery/`             | Save discovery document              |
 | Read project rule files                | Understand patterns to follow        |
 
-> **Important**: The ONLY writable location is `flow/discovery/`. No source code, configuration files, or any other project files should be modified.
+> **Important**: The ONLY writable locations are `flow/discovery/`, `flow/resources/pending-patterns.md`, and `.claude/rules/core/*.md` (for approved patterns). No source code, configuration files, or any other project files should be modified.
 
 ---
 
@@ -74,8 +74,10 @@ This skill is **strictly for gathering and documenting requirements**. The proce
 
 1. Identify references (look for @mentions, file paths, URLs)
 2. Read each file using the Read tool
-3. Extract key information (requirements, constraints, contracts)
-4. Summarize findings for each source
+3. **If a brainstorm file** (`flow/brainstorms/brainstorm_*.md`): parse the "For Discovery" section — inherit resolved decisions, use open questions as investigation starting points, and skip rejected alternatives
+4. Extract key information (requirements, constraints, contracts)
+5. Summarize findings for each source
+6. **Capture patterns**: While reading existing code and documents, watch for recurring conventions and established patterns. Silently append to `flow/resources/pending-patterns.md`. See `.claude/resources/core/pattern-capture.md` for buffer format and capture triggers.
 
 **Document Analysis Format**:
 
@@ -109,6 +111,20 @@ Ask questions about gaps identified in documents and unclear requirements.
 | Technical  | Architecture, dependencies         |
 | UI/UX      | User interface and experience      |
 
+**Design Awareness Questions**:
+
+After standard clarifying questions, check for UI work. See `.claude/resources/core/design-awareness.md` for the full question flow.
+
+1. **Always ask** (as part of the standard question batch): "Does this feature involve any UI or visual interface work?"
+   - If **Yes** or **Partially**: Add a follow-up question batch via `AskUserQuestion`:
+     - "Do you have an existing design to follow?" (screenshots/mockups, existing design system, or need new design direction)
+     - "What design personality fits this feature?" (only if no existing design — Stark, Aura, Neo, Zen, Flux, Terra)
+     - "What's the primary layout pattern?" (dashboard, content+sidebar, form workflow, data table)
+   - If **No**: Skip design questions entirely
+2. **If user provides screenshots**: Analyze visually and extract structured design tokens (colors, typography, spacing, component patterns). See token extraction rules in `.claude/resources/core/design-awareness.md`.
+3. **If user picks a personality**: Use the personality's default tokens from `.claude/resources/core/design-awareness.md`.
+4. **Plugin detection**: Check if `.interface-design/system.md` exists. If found, offer to use it as the design source.
+
 **Use Interactive Questions Tool**:
 
 Follow `.claude/resources/tools/interactive-questions-tool.md`:
@@ -170,7 +186,9 @@ Categorize requirements as they are gathered:
 
 ### Step 5: Identify Technical Considerations
 
-Document high-level technical insights (NO implementation code):
+Document high-level technical insights (NO implementation code).
+
+**While analyzing technical considerations**, watch for conventions in the existing codebase that should be captured as patterns. Silently append to `flow/resources/pending-patterns.md`.
 
 ```markdown
 ## Technical Considerations
@@ -230,6 +248,19 @@ Capture risks discovered:
 
 ---
 
+### Step 8b: Pattern Review
+
+After generating the discovery document but before completing the skill, run the pattern review protocol:
+
+1. Read `flow/resources/pending-patterns.md`
+2. If the buffer has entries, present grouped patterns for user approval
+3. Write approved patterns to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`
+4. Clear the buffer
+
+See `.claude/resources/core/pattern-capture.md` for the full end-of-skill review protocol.
+
+---
+
 ### Step 8: Generate Discovery Document
 
 Create the discovery markdown file:
@@ -249,6 +280,8 @@ Create the discovery markdown file:
 7. Risks and Unknowns
 8. Next Steps
 
+**Design Context**: If UI work was confirmed during questioning, append a `## Design Context` section to the discovery document using the template from `.claude/resources/core/design-awareness.md`. Populate with extracted tokens (from screenshots), personality defaults, or existing design system values.
+
 ---
 
 ## Output Format
@@ -276,6 +309,7 @@ Before completing discovery, verify:
 - [ ] Risks and unknowns are identified
 - [ ] Proposed approach is documented (high-level only)
 - [ ] Next steps are defined (pointing to `/create-plan`)
+- [ ] If UI work detected: `## Design Context` section included with structured tokens
 - [ ] **NO implementation code is included**
 - [ ] **NO source files were created or modified**
 

package/.claude/resources/skills/execute-plan-skill.md

@@ -189,9 +189,20 @@ Wait for user confirmation before proceeding.
 1. **Auto-switch to Plan mode** - Call `SwitchMode` tool
 2. **Present phase details** - Show scope, tasks, and approach
 3. **Wait for approval** - Get user confirmation
-4. **Implement** - Execute the phase following approved approach
-5. **Update progress** - Mark tasks complete in plan file
-6. **Continue to next phase** - NO BUILD between phases
+4. **Select model tier** - If `model_routing` is enabled in `flow/.flowconfig` (default: `true`):
+   - Read the phase's complexity score
+   - Look up model tier: **0-3 → Fast (haiku)**, **4-5 → Standard (sonnet)**, **6-10 → Powerful (opus)**
+   - For aggregated phases, use the **highest individual phase complexity** to determine the tier
+   - Spawn implementation as an **Agent subagent** with `model={tier}` parameter
+   - Include in Agent prompt: plan file path, current phase details, files modified so far, allowed/forbidden patterns
+   - If `model_routing` is `false` or key is missing, skip routing and implement directly (use session model)
+   - See `.claude/resources/core/model-routing.md` for full tier table, platform mappings, and rules
+5. **Inject design context** - Before implementing, check if the discovery doc (from plan's "Based on Discovery" field) has a `## Design Context` section. If present and the phase involves UI work (see UI Phase Detection Heuristics in `.claude/resources/core/design-awareness.md`), prepend the Design Context to the implementation prompt with: "Follow these design tokens when implementing UI elements. Use the exact color values, typography, and spacing from the Design Context." If no Design Context or phase is not UI-related, skip this step.
+6. **Implement** - Execute the phase following approved approach (via subagent if model routing is active, or directly if not)
+7. **Capture patterns** - While implementing, watch for recurring conventions, anti-patterns, and workarounds. Silently append to `flow/resources/pending-patterns.md`. See `.claude/resources/core/pattern-capture.md` for buffer format and capture triggers.
+8. **Update progress** - Mark tasks complete in plan file
+9. **Record model used** - Track which model tier was used for this phase (for the completion summary)
+10. **Continue to next phase** - NO BUILD between phases
 
 **Phase Presentation Template**:
 
@@ -200,6 +211,7 @@ Wait for user confirmation before proceeding.
 
 **Complexity**: X/10
 **Scope**: [Phase scope description]
+**Design Context**: Available / Not applicable
 
 ### Tasks to Complete:
 - [ ] Task 1
@@ -213,6 +225,7 @@ Wait for user confirmation before proceeding.
 - [ ] Following allowed patterns
 - [ ] Avoiding forbidden patterns
 - [ ] Using appropriate language patterns
+- [ ] Following design tokens from Design Context (if applicable)
 
 ---
 
@@ -234,6 +247,31 @@ Then continue to the next phase (NO BUILD HERE).
 
 ---
 
+### Step 5b: Phase-Boundary Context Check
+
+**After each phase completes**, check context window usage by looking at the token count from the last response. If you notice the conversation is getting long (many phases completed, lots of file reads/edits), **proactively run `/compact`** with a summary of remaining work.
+
+**When to compact** (at phase boundaries):
+- Context feels heavy (many tool calls, large file reads accumulated)
+- Multiple phases completed and more remain
+- You're about to start a complex phase (complexity >= 6)
+
+**How to compact at a phase boundary**:
+
+Run `/compact` with instructions that preserve execution state:
+
+```
+/compact Executing plan: [plan file path]. Completed phases: [list]. Next phase: [name and scope]. Key files modified: [list]. Active tasklist items: [list from flow/tasklist.md]. Resume execution from phase [N].
+```
+
+**Rules**:
+- NEVER compact mid-phase — only at phase boundaries (between phases)
+- Always include enough context in the compact instructions to resume
+- After compaction, re-read the plan file and continue from the next phase
+- In autopilot mode, compact automatically without asking — this is a maintenance action, not a user decision
+
+---
+
 ### Step 6: Handle Tests Phase
 
 The Tests phase is **always executed separately**, regardless of complexity score:
@@ -247,6 +285,19 @@ The Tests phase is **always executed separately**, regardless of complexity scor
 
 ---
 
+### Step 7b: Pattern Review
+
+After all phases are complete but **before** build/test verification, run the pattern review protocol:
+
+1. Read `flow/resources/pending-patterns.md`
+2. If the buffer has entries, present grouped patterns for user approval
+3. Write approved patterns to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`
+4. Clear the buffer
+
+See `.claude/resources/core/pattern-capture.md` for the full end-of-skill review protocol.
+
+---
+
 ### Step 7: Completion - Build and Test Verification
 
 **This is the ONLY place where build and tests are run.**
@@ -264,7 +315,18 @@ npm run build && npm run test
    - If tests fail: Fix the issue, re-run verification
    - Only proceed after everything passes
 
-3. **Present summary** of completed work
+3. **Present summary** of completed work, including model routing info if enabled:
+
+```markdown
+| Phase | Complexity | Model | Status |
+|-------|-----------|-------|--------|
+| 1. Setup types | 2/10 | haiku | Done |
+| 2. Core logic | 5/10 | sonnet | Done |
+| 3. Integration | 7/10 | opus | Done |
+| 4. Tests | 4/10 | sonnet | Done |
+
+**Model routing**: Saved ~X% vs all-opus execution
+```
 
 4. **List all key changes** made
 

package/.claude/resources/skills/flow-cost.md

@@ -0,0 +1,153 @@
+# Flow Cost: Token Usage Reporting
+
+## Overview
+
+The `/flow cost` subcommand reads `~/.claude/metrics/costs.jsonl` and displays token usage and estimated cost summaries. It supports time-based and project-based filtering.
+
+## Usage
+
+```
+/flow cost                       Show last 7 days summary
+/flow cost --today               Show today's usage
+/flow cost --week                Show last 7 days (default)
+/flow cost --month               Show 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
+```
+
+## Implementation
+
+When the user runs `/flow cost`, follow these steps:
+
+### Step 1: Read Metrics File
+
+1. Read `~/.claude/metrics/costs.jsonl`
+2. If the file doesn't exist, display: "No cost data found. Cost tracking hooks will start recording after your next Claude response."
+3. Parse each line as JSON, skip malformed lines
+4. Also read any rotated files (`costs.*.jsonl`) in the same directory if the time range extends beyond the current file
+
+### Step 2: Filter Entries
+
+Apply filters based on flags:
+
+| Flag | Filter Logic |
+|------|-------------|
+| `--today` | Entries where `timestamp` is today (local date) |
+| `--week` | Entries from the last 7 days (default) |
+| `--month` | Entries from the last 30 days |
+| `--project <name>` | Entries where `project` matches `<name>` |
+| `--session <id>` | Entries where `session_id` matches `<id>` |
+
+**Exclude** entries with `type: "session_summary"` from the main table — these are aggregated separately.
+
+### Step 3: Aggregate Data
+
+Group filtered entries by `project` and compute:
+
+- **Sessions**: Count unique `session_id` values
+- **Responses**: Count of entries (each entry = one response)
+- **Input Tokens**: Sum of `input_tokens`
+- **Output Tokens**: Sum of `output_tokens`
+- **Cache Creation**: Sum of `cache_creation_tokens`
+- **Cache Read**: Sum of `cache_read_tokens`
+- **Cost**: Sum of `estimated_cost_usd`
+
+### Step 4: Format Output
+
+#### Default Summary
+
+```markdown
+**Cost Report** (last 7 days)
+
+| Project    | Sessions | Responses | Input Tokens | Output Tokens | Cost     |
+|------------|----------|-----------|--------------|---------------|----------|
+| parcels    | 12       | 145       | 1.2M         | 320K          | $12.45   |
+| plan-flow  | 8        | 92        | 890K         | 210K          | $8.72    |
+| **Total**  | **20**   | **237**   | **2.1M**     | **530K**      | **$21.17** |
+```
+
+#### With `--detail` (model breakdown)
+
+```markdown
+**Cost Report** (last 7 days)
+
+| Project    | Model            | Responses | Input     | Output    | Cache Read | Cost    |
+|------------|------------------|-----------|-----------|-----------|------------|---------|
+| parcels    | claude-opus-4-6  | 45        | 520K      | 180K      | 1.2M       | $9.30   |
+| parcels    | claude-sonnet-4-6| 100       | 680K      | 140K      | 890K       | $3.15   |
+| plan-flow  | claude-opus-4-6  | 32        | 410K      | 120K      | 780K       | $6.20   |
+| plan-flow  | claude-sonnet-4-6| 60        | 480K      | 90K       | 560K       | $2.52   |
+| **Total**  |                  | **237**   | **2.1M**  | **530K**  | **3.4M**   | **$21.17** |
+```
+
+#### Session Detail (`--session <id>`)
+
+```markdown
+**Session Detail**: abc-123
+
+| # | Timestamp | Model | Input | Output | Cache | Cost |
+|---|-----------|-------|-------|--------|-------|------|
+| 1 | 10:23:15  | opus  | 12K   | 3.2K   | 45K   | $0.24 |
+| 2 | 10:25:42  | opus  | 18K   | 5.1K   | 52K   | $0.38 |
+| ...| ...      | ...   | ...   | ...    | ...   | ...  |
+
+**Session Total**: 23 responses, $4.82, 45 minutes
+```
+
+### Step 5: Token Formatting
+
+Format large numbers for readability:
+
+| Range | Format | Example |
+|-------|--------|---------|
+| < 1,000 | Raw number | 847 |
+| 1,000 - 999,999 | K with 1 decimal | 12.5K |
+| >= 1,000,000 | M with 1 decimal | 2.1M |
+
+Cost formatting: Always show 2 decimal places with `$` prefix (e.g., `$12.45`).
+
+## JSONL Entry Schema
+
+Each line in `costs.jsonl` has this structure:
+
+```json
+{
+  "timestamp": "2026-03-09T14:30:00.000Z",
+  "session_id": "abc-123-def",
+  "project": "plan-flow",
+  "model": "claude-opus-4-6",
+  "input_tokens": 12500,
+  "output_tokens": 3200,
+  "cache_creation_tokens": 9821,
+  "cache_read_tokens": 45000,
+  "estimated_cost_usd": 0.000243,
+  "hook_version": "1.0.0"
+}
+```
+
+Session summary entries (appended by SessionEnd hook):
+
+```json
+{
+  "type": "session_summary",
+  "timestamp": "2026-03-09T15:00:00.000Z",
+  "session_id": "abc-123-def",
+  "project": "plan-flow",
+  "models": ["claude-opus-4-6"],
+  "response_count": 23,
+  "total_input_tokens": 287500,
+  "total_output_tokens": 73600,
+  "total_cache_creation_tokens": 225883,
+  "total_cache_read_tokens": 1035000,
+  "total_cost_usd": 4.823456,
+  "duration_minutes": 45,
+  "hook_version": "1.0.0"
+}
+```
+
+## Error Handling
+
+- If `~/.claude/metrics/costs.jsonl` doesn't exist: Show friendly message, no error
+- If file is empty or all lines malformed: Show "No valid cost data found"
+- If no entries match filter: Show "No entries found for the selected filter"

package/.claude/resources/skills/review-code-skill.md

@@ -51,7 +51,7 @@ This skill is **strictly read-only analysis**. The review process:
 | Write to `flow/reviewed-code/`     | Save review notes locally       |
 | Read project rule files                | Load patterns for analysis      |
 
-> **Important**: The ONLY writable location is `flow/reviewed-code/`. No source code, configuration files, or any other project files should be modified.
+> **Important**: The ONLY writable locations are `flow/reviewed-code/`, `flow/resources/pending-patterns.md`, and `.claude/rules/core/*.md` (for approved patterns). No source code, configuration files, or any other project files should be modified.
 
 ---
 
@@ -158,6 +158,21 @@ When a pattern conflict is found:
    - Suggest additions to `.claude/rules/core/allowed-patterns.md`
    - Suggest additions to `.claude/rules/core/forbidden-patterns.md`
 
+4. **Buffer patterns for capture**: Silently append identified patterns (both good patterns and anti-patterns found during review) to `flow/resources/pending-patterns.md`. See `.claude/resources/core/pattern-capture.md` for buffer format and capture triggers.
+
+### Step 6b: Pattern Review
+
+After analysis but before generating the review document, run the pattern review protocol:
+
+1. Read `flow/resources/pending-patterns.md`
+2. If the buffer has entries, present grouped patterns for user approval
+3. Write approved patterns to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`
+4. Clear the buffer
+
+See `.claude/resources/core/pattern-capture.md` for the full end-of-skill review protocol.
+
+---
+
 ### Step 6: Generate Review Document
 
 Create a markdown file in `flow/reviewed-code/` with the naming convention:

package/.claude/rules/core/allowed-patterns.md

@@ -173,3 +173,9 @@ const example = correctApproach()
 - Guideline 1
 - Guideline 2
 ```
+
+---
+
+## Project Patterns
+
+<!-- auto-captured patterns below this line -->