planflow-ai 1.2.0 → 1.3.0

package/.claude/commands/brainstorm.md

@@ -0,0 +1,228 @@
+---
+description: Free-form conversational exploration of an idea. The LLM collaborates one-question-at-a-time to crystallize vague ideas before discovery. Optionally generates an MD file for /discovery-plan.
+---
+
+# Brainstorm
+
+## Command Description
+
+This command starts a free-form brainstorm session where the LLM collaborates conversationally to explore an idea. Unlike `/discovery-plan` (structured, project-aware), brainstorm is pure ideation — exploring the what and why through rapid back-and-forth dialogue.
+
+**Output**: Conversational exploration, plus an optional markdown file at `flow/brainstorms/brainstorm_{topic}_v{version}.md`
+
+---
+
+
+## Help
+
+**If the user invokes this command with `-help`, display only this section and stop:**
+
+```
+/brainstorm - Collaborative Idea Exploration
+
+DESCRIPTION:
+  Free-form brainstorm session where the LLM acts as a collaborative
+  thinking partner. Explores ideas through one-question-at-a-time dialogue
+  before formalizing into discovery.
+
+USAGE:
+  /brainstorm <idea>
+  /brainstorm -help
+
+ARGUMENTS:
+  idea   Free-text description of the idea to explore
+
+EXAMPLES:
+  /brainstorm I want to add a plugin system to plan-flow
+  /brainstorm "Real-time notifications triggered by user actions"
+  /brainstorm We need a better way to handle error recovery in the API
+
+OUTPUT:
+  - Conversational exploration of the idea
+  - Optional: flow/brainstorms/brainstorm_{topic}_v{version}.md
+  - Optional: tasklist entry (only if requested)
+
+WORKFLOW:
+  1. You share your idea
+  2. LLM presents batched questions with options (3-4 per round, with recommended choices)
+  3. You pick options or type custom answers, LLM reacts with insights
+  4. You say "done" / "wrap up" / "summarize" when ready
+  5. LLM presents structured summary
+  6. Optionally generates MD file for /discovery-plan
+  7. Optionally adds to tasklist
+
+WHAT IT IS:
+  - A thinking partner — challenges, suggests, connects, presents structured options
+  - Pure ideation — explores the what and why
+  - Lightweight — no brain, no memory, no auto-tasklist
+
+WHAT IT IS NOT:
+  - Not /discovery-plan — no codebase scanning, no requirements docs
+  - Not /brain — no knowledge capture, no wiki-links
+  - Not a plan — no phases, no complexity scores
+
+RECOMMENDED MODEL:
+  Claude Opus 4.6 or Sonnet 4.5 for best results
+
+RELATED COMMANDS:
+  /discovery-plan   Ground the brainstorm idea into the project
+  /create-plan      Create plan from discovery document
+  /brain            Capture knowledge (different purpose)
+```
+
+---
+
+## Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| **Structured Exploration** | Questions in batches of 3-4 with options via `AskUserQuestion`. Commentary between batches. |
+| **No Code** | NEVER write, edit, or generate source code |
+| **No Brain** | Do NOT write to `flow/brain/` or update brain index |
+| **No Memory** | Do NOT write to `flow/memory.md` |
+| **No Auto-Tasklist** | Only update tasklist if user explicitly requests |
+| **Codebase on Request** | Only read codebase files when user explicitly asks |
+| **User Ends It** | Never auto-end the brainstorm. User controls when it's done. |
+| **Complete and Stop** | After completion, STOP and wait for user |
+
+---
+
+## Instructions
+
+### Step 1: Validate Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `idea` | Yes | Free-text description of the idea to explore |
+
+If no idea is provided, ask:
+
+```markdown
+What idea would you like to explore? Just describe it in your own words —
+it can be as vague or specific as you want.
+```
+
+---
+
+### Step 2: Check for Existing Brainstorms
+
+Check `flow/brainstorms/` for existing brainstorm documents on a similar topic:
+
+1. If found, mention it: "There's an existing brainstorm on {topic} (v{N}). Want to build on that or start fresh?"
+2. If starting fresh, increment version number
+3. If building on existing, read it first for context
+
+---
+
+### Step 3: Invoke Brainstorm Skill
+
+The skill will:
+
+1. Parse the idea and open the conversation
+2. Run the conversational loop (one question per turn)
+3. Detect when the user wants to end
+4. Present a structured summary
+5. Offer to generate an MD file
+6. Offer to add a tasklist entry
+
+See: `.claude/resources/skills/brainstorm-skill.md`
+
+---
+
+### Step 4: Handle Completion
+
+After the skill completes:
+
+- If MD file was generated: report the file path
+- If no MD file: just acknowledge completion
+- Do NOT auto-chain to `/discovery-plan`
+
+---
+
+## Flow Diagram
+
+```
++------------------------------------------+
+|        /brainstorm COMMAND               |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 1: Validate Inputs                  |
+| - Check for idea text                    |
+| - Ask if not provided                    |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 2: Check Existing Brainstorms       |
+| - Look in flow/brainstorms/              |
+| - Offer to build on or start fresh       |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 3: Invoke Brainstorm Skill          |
+| - Conversational loop                    |
+| - One question per turn                  |
+| - Silent thread tracking                 |
+| - See brainstorm-skill.md              |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 4: Handle Completion                |
+| - Summary presented                      |
+| - Optional MD file generated             |
+| - Optional tasklist entry                |
+| - STOP (no auto-chain)                   |
++------------------------------------------+
+```
+
+---
+
+## Context Optimization
+
+### Recommended Loading Order
+
+1. **Always load first**: This command file (`commands/brainstorm.md`)
+2. **Expand on-demand**: Load skill file when entering conversational loop
+
+### Reference Codes for Brainstorm
+
+| Code | Description | When to Expand |
+|------|-------------|----------------|
+| SKL-BS-1 | Brainstorm skill restrictions and inputs | Understanding allowed actions |
+| SKL-BS-2 | Conversational loop and tracking | During the brainstorm |
+| SKL-BS-3 | End detection, summary, and output | When wrapping up |
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `resources/skills/_index.md` | Index of skills with reference codes |
+| `brainstorm-skill.md` | Skill that runs the brainstorm |
+| `brainstorm-templates.md` | Output file template |
+| `/discovery-plan` command | Next step after brainstorm |
+
+---
+
+## Resource Capture
+
+During this skill's execution, watch for valuable reference materials worth preserving. See `.claude/resources/core/resource-capture.md` for capture rules, file format, and naming conventions.
+
+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.
+
+---
+
+## Pattern Capture
+
+During the brainstorm, silently watch for conventions, anti-patterns, and patterns that emerge from the discussion. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting the conversation.
+
+After the brainstorm completes, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

package/.claude/commands/discovery-plan.md

@@ -55,6 +55,7 @@ EXAMPLES:
   /discovery-plan @flow/contracts/api_contract.md
   /discovery-plan "User authentication with OAuth2"
   /discovery-plan @docs/feature-spec.md "Focus on the payment flow"
+  /discovery-plan @flow/brainstorms/brainstorm_plugin-system_v1.md
 
 OUTPUT:
   Creates: flow/discovery/discovery_<feature_name>_v<version>.md
@@ -145,9 +146,14 @@ Check `flow/discovery/` for existing discovery documents for this feature:
 
 ### Step 4: Invoke Discovery Skill
 
+**Brainstorm files as input**: If the reference document is a brainstorm file (`flow/brainstorms/brainstorm_*.md`), the skill should:
+- Treat "Resolved During Brainstorm" decisions as settled — do NOT re-ask
+- Use "Still Open (Discovery Should Investigate)" as starting investigation points
+- Respect "Rejected (Do Not Revisit)" — do NOT re-propose these alternatives
+
 The skill will:
 
-1. Read all referenced documents
+1. Read all referenced documents (including brainstorm files)
 2. Find all related code references in the codebase
 3. Ask clarifying questions via Interactive Questions Tool
 4. Track question status
@@ -380,3 +386,21 @@ 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.
+
+---
+
+## Design Awareness
+
+During discovery, always ask whether the feature involves UI work. If confirmed, follow the design question flow to capture structured design tokens (colors, typography, spacing, component patterns) into a `## Design Context` section in the discovery document.
+
+See `.claude/resources/core/design-awareness.md` for the full question flow, personality options, token extraction rules, and Design Context template.
+
+---
+
+## Pattern Capture
+
+During discovery, silently watch for conventions found in existing code, anti-patterns in referenced documents, and patterns identified during technical analysis. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting work.
+
+After generating the discovery document, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

package/.claude/commands/execute-plan.md

@@ -85,6 +85,7 @@ RELATED COMMANDS:
 | ------------------------ | -------------------------------------------------------- |
 | **Build ONLY at End**    | Do NOT run build after each phase - only at the very end |
 | **No Direct DB/ORM**     | NEVER run ORM or database commands directly              |
+| **Compact at Boundaries**| After each phase, if context is heavy, run `/compact` with execution state (see Step 5b in skill) |
 | **Complete and Stop**    | After execution, STOP and wait for user (unless autopilot ON) |
 
 ---
@@ -430,3 +431,37 @@ At natural break points, if you encounter information that could be useful for f
 
 Only save if the user approves. Do not re-ask if declined.
 
+---
+
+## Pattern Capture
+
+During execution, silently watch for recurring conventions, anti-patterns, workarounds, and user corrections. Append captured patterns to `flow/resources/pending-patterns.md` without interrupting work.
+
+After all phases complete (before brain-capture), present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.
+
+---
+
+## Design Awareness
+
+During execution, when a phase involves UI work and the discovery document contains a `## Design Context` section, auto-inject the design tokens into the phase implementation prompt. This ensures UI phases follow the established design system.
+
+See `.claude/resources/core/design-awareness.md` for UI phase detection heuristics and injection rules.
+
+---
+
+## Model Routing
+
+When `model_routing: true` in `flow/.flowconfig` (default), each phase is automatically routed to the most cost-effective model based on its complexity score:
+
+| Complexity | Tier | Claude Code Model |
+|-----------|------|-------------------|
+| 0-3 | Fast | haiku |
+| 4-5 | Standard | sonnet |
+| 6-10 | Powerful | opus |
+
+Routing happens at Step 4 of the execution skill — the phase implementation is spawned as an Agent subagent with the appropriate `model` parameter. Planning/approval steps always use the session model.
+
+Disable with `/flow model_routing=false`. See `.claude/resources/core/model-routing.md` for full tier table, platform mappings, and aggregation rules.
+

package/.claude/commands/flow.md

@@ -29,6 +29,7 @@ DESCRIPTION:
 USAGE:
   /flow <key>=<value> [key=value ...]   Set one or more settings
   /flow <prompt>                         Enable autopilot and start flow with prompt
+  /flow cost [--today|--week|--month]   Show token usage and cost report
   /flow -status                          Show all current settings
   /flow -reset                           Reset all settings to defaults
   /flow -help                            Show this help
@@ -38,6 +39,16 @@ SETTINGS:
   commit=true|false      Auto-commit after each completed phase (default: false)
   push=true|false        Auto-push after all phases + build/test pass (default: false)
   branch=<name>          Target branch for git operations (default: current branch)
+  model_routing=true|false  Auto-select model per phase based on complexity (default: true)
+
+COST REPORTING:
+  /flow cost                             Last 7 days summary (default)
+  /flow cost --today                     Today's usage only
+  /flow cost --week                      Last 7 days
+  /flow cost --month                     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
 
 EXAMPLES:
   /flow autopilot=true                    # Enable autopilot
@@ -45,6 +56,9 @@ EXAMPLES:
   /flow autopilot=true commit=true        # Enable both
   /flow branch=development                # Set target branch
   /flow commit=false push=false           # Disable git control
+  /flow model_routing=false               # Disable model routing (use session model for all phases)
+  /flow cost                              # Show cost report (last 7 days)
+  /flow cost --today --detail             # Today's costs with model breakdown
   /flow -status                           # Show current config
   /flow -reset                            # Reset everything
 
@@ -82,9 +96,10 @@ CONFIG FILE:
 
 Parse the user input to determine what action to take:
 
-1. **Scan for `key=value` pairs**: Extract all `key=value` tokens from the input
-2. **Check for flags**: `-status`, `-reset`, `-help`
-3. **Remaining text**: Anything left after extracting keys and flags is a prompt
+1. **Check for `cost` subcommand**: If input starts with `cost`, route to cost reporting (see Step 6)
+2. **Scan for `key=value` pairs**: Extract all `key=value` tokens from the input
+3. **Check for flags**: `-status`, `-reset`, `-help`
+4. **Remaining text**: Anything left after extracting keys and flags is a prompt
 
 **Valid keys**:
 
@@ -94,6 +109,7 @@ Parse the user input to determine what action to take:
 | `commit` | `true`, `false` | `false` | Auto-commit after each phase |
 | `push` | `true`, `false` | `false` | Auto-push after completion |
 | `branch` | any string | current branch | Target branch for git ops |
+| `model_routing` | `true`, `false` | `true` | Auto-select model per phase based on complexity |
 
 ---
 
@@ -184,6 +200,23 @@ This is a **feature request with autopilot**:
 
 ---
 
+### Step 6: Cost Reporting (`/flow cost`)
+
+If the input starts with `cost`, route to the cost reporting flow:
+
+1. **Load the skill**: Read `.claude/resources/skills/flow-cost.md` for full implementation details
+2. **Parse cost flags**: `--today`, `--week`, `--month`, `--project <name>`, `--session <id>`, `--detail`
+3. **Read metrics file**: `~/.claude/metrics/costs.jsonl`
+4. **Filter and aggregate**: Apply time/project/session filters, group by project
+5. **Display summary table**: Format tokens (K/M), costs ($X.XX), present as markdown table
+6. **STOP**: After showing the report, wait for user input
+
+**Default behavior** (no flags): Show last 7 days summary grouped by project.
+
+See `.claude/resources/skills/flow-cost.md` for detailed formatting rules and examples.
+
+---
+
 ## Critical Rules
 
 | Rule | Description |

package/.claude/commands/review-code.md

@@ -238,3 +238,13 @@ 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.
+
+---
+
+## 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.
+
+After analysis, present any buffered patterns for user approval. Approved patterns are written to `.claude/rules/core/allowed-patterns.md` or `.claude/rules/core/forbidden-patterns.md`.
+
+See `.claude/resources/core/pattern-capture.md` for buffer format, capture triggers, conflict detection, and the full review protocol.

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**: 11 files, ~1730 lines
-**Reference Codes**: COR-AP-1 through COR-LR-2
+**Total Files**: 14 files, ~2310 lines
+**Reference Codes**: COR-AP-1 through COR-DA-3
 
 ---
 
@@ -94,6 +94,30 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-LR-1 | Trigger conditions and detection logic | learn-recommendations.md | 10-62 |
 | COR-LR-2 | Recommendation format, rules, and integration points | learn-recommendations.md | 64-170 |
 
+### Pattern Capture (`pattern-capture.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-PC-1 | Capture behavior, triggers, and buffer format | pattern-capture.md | 10-80 |
+| COR-PC-2 | End-of-skill review protocol and user approval flow | pattern-capture.md | 82-140 |
+| COR-PC-3 | Auto-captured entry format and conflict detection | pattern-capture.md | 142-210 |
+
+### Model Routing (`model-routing.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-MR-1 | Model tiers, platform mappings, and routing rules | model-routing.md | 10-60 |
+| COR-MR-2 | Aggregation behavior and plan mode exception | model-routing.md | 62-85 |
+| COR-MR-3 | Cost impact estimates and execution summary format | model-routing.md | 87-115 |
+
+### Design Awareness (`design-awareness.md`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-DA-1 | Design Context template and personalities | design-awareness.md | 14-180 |
+| 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 |
+
 ---
 
 ## When to Expand
@@ -127,6 +151,15 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-RC-2 | Need resource file format and naming conventions |
 | COR-LR-1 | Need learn recommendation trigger conditions |
 | COR-LR-2 | Need learn recommendation format and integration rules |
+| COR-PC-1 | Need pattern capture behavior and buffer format |
+| COR-PC-2 | Need end-of-skill review protocol |
+| COR-PC-3 | Need auto-captured entry format and conflict detection |
+| COR-MR-1 | Need model tier definitions and platform mappings |
+| COR-MR-2 | Need aggregation behavior for model routing |
+| COR-MR-3 | Need cost impact estimates or execution summary format |
+| 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 |
 
 ---
 
@@ -164,6 +197,8 @@ Core rules define the foundational coding standards that apply across the entire
 - `brain-capture.md` is loaded on-demand - processes brain-capture blocks and manages brain index
 - `resource-capture.md` is loaded on-demand - watches for valuable reference materials during skill execution
 - `learn-recommendations.md` is loaded on-demand - detects learning opportunities and recommends `/learn`
+- `pattern-capture.md` is loaded on-demand - silently captures patterns during skill execution and presents for approval
+- `model-routing.md` is loaded on-demand - automatic model selection per phase based on complexity scores during `/execute-plan`
 - `project-tasklist.md` is loaded on-demand - session start tasklist behavior
 - `project-memory.md` is loaded on-demand - artifact tracking and 7-day session loading
 - `heartbeat.md` is loaded on-demand - scheduled task daemon configuration