flow-cc 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.3] - 2026-02-12
+
+### Changed
+- Lessons system refactored to 2-stage with hard caps — `tasks/lessons.md` max 10 active one-liners, `CLAUDE.md ## Learned Rules` max 15 permanent one-liners
+- Replaced verbose PATTERN/CAUSE/FIX/RULE format with compact one-liner format: `- **[topic]** The rule`
+- Removed 4-stage lifecycle (Capture → Refine → Promote Global → Promote CLAUDE.md), replaced with 2-stage (Capture → Promote to CLAUDE.md when full)
+- Removed all references to `~/.claude/lessons.md` global lessons file
+- `/flow:done` now enforces cap: promotes most battle-tested lesson to CLAUDE.md when lessons.md hits 10
+- `/flow:status` shows `[N]/10 active` instead of `[N] rules`
+- Agent prompts section renamed from "Anti-Patterns to Avoid" to "Lessons (Rules to Follow)"
+- CLAUDE.md template now includes `## Learned Rules` placeholder section
+- Updated DESIGN.md, README.md, and all skill files to reflect 2-stage system
+
+## [0.4.2] - 2026-02-11
+
+### Fixed
+- `/flow:spec` Phase 1 codebase scan now delegates to 3 parallel Explore subagents instead of reading files into main context — saves 200-500 lines of context before the interview starts
+- Added plan mode warnings to `/flow:spec` and `/flow:go` — plan mode's read-only constraint breaks both skills
+- Added Plan Mode Compatibility section to DESIGN.md documenting the design philosophy
+
 ## [0.4.1] - 2026-02-11
 
 ### Fixed

package/README.md

@@ -113,19 +113,17 @@ your-project/
 │   ├── ROADMAP.md         # Milestone phases and progress
 │   └── archive/           # Completed milestones and old PRDs
 └── tasks/
-    └── lessons.md         # Mistake catalog → refined into permanent rules
+    └── lessons.md         # Active lessons (max 10 one-liners) → promoted to CLAUDE.md
 ```
 
 ## The Lessons System
 
 Flow's knowledge compounding is what makes it get better over time:
 
-1. **Capture** — Mistake happens, lesson written to `tasks/lessons.md`
-2. **Refine** — Each `/flow:done` merges duplicates, sharpens rules, removes obvious ones
-3. **Promote** — Universal lessons move to `~/.claude/lessons.md` (all projects)
-4. **Permanence** — Recurring patterns become rules in `CLAUDE.md`
+1. **Capture** — Mistake happens, one-liner written to `tasks/lessons.md` (max 10 active)
+2. **Promote** — When full, most battle-tested lesson moves to `CLAUDE.md ## Learned Rules` (max 15 permanent)
 
-The goal: fewer, sharper lessons over time — not an ever-growing list.
+Hard caps prevent context bloat. Total worst-case: ~30 lines of lessons context per session.
 
 ## Compatible With GSD
 

package/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Structured workflow system for Claude Code — spec interviews, agent-team execution, session handoffs, compounding knowledge",
   "author": "Troy Hoffman",
   "license": "MIT",

package/skills/flow-done.md

@@ -17,7 +17,7 @@ You are executing the `/flow:done` skill. This finalizes the current session by
 Read these files (in parallel where possible):
 - `.planning/STATE.md` — current state
 - `.planning/ROADMAP.md` — milestone/phase progress
-- `tasks/lessons.md` — existing lessons
+- `tasks/lessons.md` — active lessons (max 10)
 - `CLAUDE.md` — project rules
 - `PRD.md` — current spec (if exists)
 
@@ -83,9 +83,14 @@ Structure:
   - "No new lessons"
   - "Yes, let me add some" (user types them)
   - "Use your suggestions" (if you auto-suggested any)
-- Add new lessons in PATTERN/CAUSE/FIX/RULE format
-- **Refine existing lessons:** merge duplicates, sharpen vague rules, delete obvious ones
-- **Promote check:** For lessons that seem universal (not project-specific), ask: "This lesson seems universal. Promote to global lessons (~/.claude/lessons.md)?"
+- Add new lessons as one-liners: `- **[topic]** The rule`
+- **Hard cap enforcement (max 10 active):**
+  - If lessons.md already has 10 items and a new one needs to be added:
+    1. Identify the most battle-tested/internalized lesson
+    2. Promote it to `CLAUDE.md ## Learned Rules` section
+    3. Delete it from lessons.md
+    4. Add the new lesson
+  - If `CLAUDE.md ## Learned Rules` hits 15 items, delete the most obvious/internalized rule to make room
 
 ### 5. Commit Doc Updates
 
@@ -119,7 +124,7 @@ Print the handoff prompt in a fenced code block so the user can copy it.
 Session complete.
 - STATE.md: updated
 - ROADMAP.md: [N] phases marked complete
-- lessons.md: [N] lessons added, [N] refined
+- lessons.md: [N]/10 active, [N] promoted to CLAUDE.md
 - Committed: [SHA]
 
 Handoff prompt:

package/skills/flow-go.md

@@ -10,13 +10,15 @@ You are executing the `/flow:go` skill. This reads the PRD, identifies the next
 
 **Core principle:** The PRD is the execution contract. You execute what it specifies. Do not freelance.
 
+**Plan mode warning:** Do NOT use this skill with plan mode enabled. `/flow:go` is execution — plan mode's read-only constraint prevents it from creating files, running agents, and committing work. The PRD IS your plan; run `/flow:go` in normal mode.
+
 ## Step 1 — Orient
 
 Read these files (in parallel):
 - `.planning/STATE.md` — current position
 - `.planning/ROADMAP.md` — phase progress
 - `PRD.md` — the execution spec
-- `tasks/lessons.md` — anti-patterns to avoid
+- `tasks/lessons.md` — active lessons (max 10 one-liners)
 - `CLAUDE.md` — execution rules and verification commands
 
 **Identify the next phase:** Find the first phase in ROADMAP.md with status "Pending" or the first unstarted phase in the PRD.
@@ -74,7 +76,7 @@ so agents have it in their context without needing to search.]
 - Stage only your files when committing (never `git add .` or `git add -A`)
 - If you need output from another agent that isn't available yet, create a temporary stub and continue. Delete the stub before your final commit.
 
-## Anti-Patterns to Avoid
+## Lessons (Rules to Follow)
 [Relevant lessons from tasks/lessons.md — filter to lessons that apply to this agent's work]
 ```
 

package/skills/flow-intro.md

@@ -64,7 +64,7 @@ Flow is 6 commands that turn your specs into shipped code through agent teams. E
 - Replaces STATE.md with current status
 - Updates ROADMAP.md with phase completions
 - Auto-transitions to the next planned milestone when the current one completes
-- Asks about lessons, refines existing ones
+- Captures lessons as one-liners, enforces 10-item cap (promotes to CLAUDE.md when full)
 - Commits doc updates
 - Generates a handoff prompt you copy-paste to start the next session
 

package/skills/flow-setup.md

@@ -169,18 +169,11 @@ Note: The first milestone gets status "Pending — needs `/flow:spec`". All subs
 
 **`tasks/lessons.md`:**
 ```
-# [Project Name] — Lessons Learned
+# [Project Name] — Lessons (max 10 active)
 
-Format: PATTERN → CAUSE → FIX → RULE
+One-liner format: `- **[topic]** The rule`
 
-## Execution Patterns
-<!-- Lessons about workflow, delegation, verification -->
-
-## Domain Knowledge
-<!-- Lessons about business logic, data models, user behavior -->
-
-## Technical Patterns
-<!-- Lessons about the tech stack, libraries, deployment -->
+<!-- EXAMPLE: - **[agent context]** Always tell agents exactly which functions/lines to read — never "read file.ts", say "read file.ts lines 50-120" -->
 ```
 
 **`.planning/archive/`** — Create this empty directory (use `mkdir -p` via Bash).
@@ -192,7 +185,7 @@ Project initialized:
 - CLAUDE.md — project execution rules
 - .planning/STATE.md — session GPS
 - .planning/ROADMAP.md — milestone tracker
-- tasks/lessons.md — anti-pattern catalog
+- tasks/lessons.md — active lessons (max 10)
 - .planning/archive/ — for completed milestones
 
 Run `/flow:spec` to plan your first milestone.

package/skills/flow-spec.md

@@ -10,18 +10,29 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 
 **Interview mode:** Always thorough by default. The user can say "done", "finalize", "that's enough", or "move on" at ANY time to wrap up early. Respect their signal and finalize with whatever depth has been achieved.
 
+**Plan mode warning:** Do NOT use this skill with plan mode enabled. Plan mode's read-only constraint prevents PRD.md from being written during the interview. `/flow:spec` IS the planning phase — plan mode on top of it is redundant and breaks the workflow.
+
 ## Phase 1 — Context Gathering (automatic, no user input needed)
 
 1. Read `.planning/STATE.md` and `.planning/ROADMAP.md` — understand current milestone and what's done
 2. Read `CLAUDE.md` — understand project rules and tech stack
 3. Read `PRD.md` if it exists — check for existing spec to build on
-4. **Codebase scan** (brownfield projects):
-   - **Exclusions:** NEVER scan these directories/files: `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`. Use Glob with patterns like `src/**/*`, `app/**/*`, `lib/**/*` — never use bare `**/*` which includes generated files.
-   - **Size check first:** Use Glob with `src/**/*`, `app/**/*`, `lib/**/*`, `components/**/*` (excluding the above) to estimate relevant file count. If > 500 files, switch to focused mode (see below).
-   - **Standard mode (≤ 500 files):** Use Glob to find components, pages/routes, API endpoints, types, utilities, config files, database models. Use Grep for export patterns, route definitions, key function signatures. **Cap at 50 files sampled** — prioritize entry points, config, and type definitions.
-   - **Focused mode (> 500 files):** Scan ONLY: package.json/config files, entry points (index.ts, main.ts, app.ts), route definitions, database schema/models, and type definition files. Skip component trees, test files, and generated code entirely.
-   - Build internal summary: "Here's what exists that we can reuse"
-5. Print a brief context summary to the user: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
+4. **Codebase scan** (brownfield projects) — spawn **3 parallel Explore subagents** via the Task tool to scan the codebase without consuming main context:
+
+   | Agent | Focus | Looks For |
+   |-------|-------|-----------|
+   | **Structure & Config** | Project skeleton, build tooling | `package.json`, `tsconfig`, config files, entry points, CI/CD, env setup |
+   | **UI, Pages & Routes** | Components, pages, routing | `components/`, `pages/`, `app/`, route definitions, layouts, navigation |
+   | **Data Layer & APIs** | Database, APIs, types | `api/`, `models/`, `types/`, `schemas/`, ORM definitions, query functions |
+
+   **Each subagent prompt MUST include:**
+   - **Exclusions:** NEVER scan `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`
+   - **Size-adaptive scanning:** If the agent's domain has >200 files, switch to focused mode (entry points, config, and type definitions only)
+   - **20-file sample cap per agent** (60 total across all 3)
+   - **15-line summary max** — structured as: key files found, patterns observed, reusable code/components, notes
+   - **Explicit instruction:** Do NOT return raw file contents — return only structured summaries
+
+5. **Assemble summaries:** Collect the 3 agent summaries into a brief context block (~45 lines total). Print to user: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
 
 ## Phase 2 — Adaptive Interview
 
@@ -211,7 +222,7 @@ Write `PRD.md` to the project root with this EXACT structure:
 2. Verify after every phase: [verification commands from CLAUDE.md]
 3. Atomic commits after each agent's work lands
 4. Never `git add .` — stage specific files only
-5. Read `tasks/lessons.md` before spawning agents — inject relevant anti-patterns
+5. Read `tasks/lessons.md` before spawning agents — inject relevant lessons into agent prompts
 
 ## Definition of Done
 - [ ] All user story acceptance criteria pass

package/skills/flow-status.md

@@ -64,7 +64,7 @@ Use this explicit decision tree:
 Milestone: [name] ([X/Y] phases complete)
 Last session: [date] — [what was built]
 Next: Phase [N] — [name] ([short description])
-Lessons: [N] rules
+Lessons: [N]/10 active
 
 [routing recommendations from Step 3]
 ```

package/skills/flow-task.md

@@ -104,9 +104,10 @@ RULES:
 Quick lessons prompt via AskUserQuestion:
 - "Any lessons from this task worth capturing?"
   - Option 1: "No, nothing new" — Skip lessons.
-  - Option 2: "Yes, let me describe it" — Capture to `tasks/lessons.md` in PATTERN/CAUSE/FIX/RULE format.
+  - Option 2: "Yes, let me describe it" — Capture to `tasks/lessons.md` as a one-liner: `- **[topic]** The rule`
 
 If `tasks/lessons.md` doesn't exist, skip the lessons prompt.
+If lessons.md already has 10 items, promote the most battle-tested to `CLAUDE.md ## Learned Rules` before adding the new one.
 
 ## Step 9 — Summary
 

package/templates/CLAUDE.md.template

@@ -23,9 +23,12 @@
 ## Session-End Docs (MANDATORY)
 1. `.planning/STATE.md` — replace session notes (don't append), keep <80 lines
 2. `.planning/ROADMAP.md` — update phase progress
-3. `tasks/lessons.md` — add new lessons, refine existing ones
+3. `tasks/lessons.md` — add new one-liner lessons, enforce max 10 cap (promote to Learned Rules when full)
 4. Commit doc updates to feature branch
 
+## Learned Rules
+<!-- Max 15 permanent one-liners promoted from tasks/lessons.md -->
+
 ## Critical Rules
 - No assumptions — ask if requirements unclear
 - Fight entropy — leave code better than you found it

package/templates/lessons.md.template

@@ -1,22 +1,5 @@
-# {{PROJECT_NAME}} — Lessons Learned
+# {{PROJECT_NAME}} — Lessons (max 10 active)
 
-Format: PATTERN → CAUSE → FIX → RULE
+One-liner format: `- **[topic]** The rule`
 
-## Execution Patterns
-<!-- Lessons about workflow, delegation, verification -->
-
-<!-- EXAMPLE (replace with real lessons as you work):
-
-### Agent context overflow on large files
-- **PATTERN:** Spawned agent tried to read a 2000-line file and ran out of context before finishing its task
-- **CAUSE:** Agent prompt didn't specify which lines/functions to read — it read the whole file
-- **FIX:** Added explicit line ranges and function names to the agent prompt
-- **RULE:** Always tell agents exactly which functions/sections to read. Never say "read file.ts" — say "read file.ts lines 50-120 (the handleSubmit function)"
-
-END EXAMPLE -->
-
-## Domain Knowledge
-<!-- Lessons about business logic, data models, user behavior -->
-
-## Technical Patterns
-<!-- Lessons about the tech stack, libraries, deployment -->
+<!-- EXAMPLE: - **[agent context]** Always tell agents exactly which functions/lines to read — never "read file.ts", say "read file.ts lines 50-120" -->