flow-cc 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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

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.2
+0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.4.2",
+  "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

@@ -18,7 +18,7 @@ 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.
@@ -76,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

@@ -222,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" -->