feat: Wave 2 — project knowledge system (decisions + pitfalls)

CLAUDE.md

@@ -94,7 +94,10 @@ Working memory files live in a dedicated `.memory/` directory:
 .memory/
 ├── WORKING-MEMORY.md         # Auto-maintained by Stop hook (overwritten each session)
 ├── PROJECT-PATTERNS.md       # Accumulated patterns (merged, not overwritten)
-└── backup.json               # Pre-compact git state snapshot
+├── backup.json               # Pre-compact git state snapshot
+└── knowledge/
+    ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
+    └── pitfalls.md            # Known pitfalls (PF-NNN, area-specific gotchas)
 ```
 
 **Naming conventions**: Timestamps as `YYYY-MM-DD_HHMM`, branch slugs replace `/` with `-`, topic slugs are lowercase-dashes.

docs/reference/file-organization.md

@@ -9,7 +9,7 @@ devflow/
 ├── .claude-plugin/                   # Marketplace registry (repo root)
 │   └── marketplace.json
 ├── shared/
-│   ├── skills/                       # SINGLE SOURCE OF TRUTH (24 skills)
+│   ├── skills/                       # SINGLE SOURCE OF TRUTH (31 skills)
 │   │   ├── git-workflow/
 │   │   │   ├── SKILL.md
 │   │   │   └── references/
@@ -20,7 +20,7 @@ devflow/
 │       ├── synthesizer.md
 │       ├── coder.md
 │       └── ...
-├── plugins/                          # Plugin collection (8 plugins)
+├── plugins/                          # Plugin collection (17 plugins)
 │   ├── devflow-specify/
 │   │   ├── .claude-plugin/
 │   │   │   └── plugin.json
@@ -40,10 +40,11 @@ devflow/
 ├── scripts/
 │   ├── build-plugins.ts
 │   ├── statusline.sh
-│   └── hooks/                        # Working Memory hooks
+│   └── hooks/                        # Working Memory + ambient hooks
 │       ├── stop-update-memory       # Stop hook: writes WORKING-MEMORY.md
 │       ├── session-start-memory     # SessionStart hook: injects memory + git state
-│       └── pre-compact-memory       # PreCompact hook: saves git state backup
+│       ├── pre-compact-memory       # PreCompact hook: saves git state backup
+│       └── ambient-prompt.sh        # UserPromptSubmit hook: ambient skill injection
 └── src/
     └── cli/
         ├── commands/
@@ -148,6 +149,17 @@ Three hooks in `scripts/hooks/` provide automatic session continuity. Toggleable
 
 Hooks auto-create `.memory/` on first run — no manual setup needed per project.
 
+## Project Knowledge
+
+Knowledge files in `.memory/knowledge/` capture decisions and pitfalls that agents can't rediscover at runtime:
+
+| File | Format | Source | Purpose |
+|------|--------|--------|---------|
+| `decisions.md` | ADR-NNN (sequential) | `/implement` Phase 11.5 | Architectural decisions — why choices were made |
+| `pitfalls.md` | PF-NNN (sequential) | `/code-review`, `/debug`, `/resolve` | Known gotchas, fragile areas, past bugs |
+
+Each file has a `<!-- TL;DR: ... -->` comment on line 1. SessionStart injects TL;DR headers only (~30-50 tokens). Agents read full files when relevant to their work. Cap: 50 entries per file.
+
 ## Statusline Script
 
 The statusline (`scripts/statusline.sh`) displays:

plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -28,6 +28,7 @@
     "database-patterns",
     "dependencies-patterns",
     "documentation-patterns",
+    "knowledge-persistence",
     "performance-patterns",
     "regression-patterns",
     "review-methodology",

plugins/devflow-code-review/commands/code-review-teams.md

@@ -85,39 +85,42 @@ Spawn review teammates with self-contained prompts:
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/security-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Security review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Security review done")
 
 - Name: "architecture-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/architecture-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: SOLID violations, coupling, layering issues, modularity problems
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: SOLID violations, coupling, layering issues, modularity problems
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture review done")
 
 - Name: "performance-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/performance-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Performance review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Performance review done")
 
 - Name: "quality-reviewer"
   Prompt: |
@@ -128,13 +131,14 @@ Spawn review teammates with self-contained prompts:
        - `Read ~/.claude/skills/test-patterns/SKILL.md`
        - `Read ~/.claude/skills/regression-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: complexity, test gaps, pattern violations, regressions, naming
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Quality review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: complexity, test gaps, pattern violations, regressions, naming
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Quality review done")
 
 [Add conditional perspectives based on Phase 1 — follow same pattern:
  explicit skill path, diff command, output path, SendMessage for completion]
@@ -212,7 +216,14 @@ Include confidence levels from debate consensus."
 {Key exchanges that changed findings}
 ```
 
-### Phase 5: Cleanup and Report
+### Phase 5: Record Pitfalls (if blocking issues found)
+
+If the review summary contains CRITICAL or HIGH blocking issues:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/code-review {branch}`
+3. Skip entirely if no CRITICAL/HIGH blocking issues
+
+### Phase 6: Cleanup and Report
 
 Shut down all review teammates explicitly:
 
@@ -257,7 +268,9 @@ Display results:
 │  ├─ Git agent (comment-pr with consensus findings)
 │  └─ Lead writes review-summary with confidence levels
 │
-└─ Phase 5: Cleanup and display results
+├─ Phase 5: Record Pitfalls (inline, if blocking issues)
+│
+└─ Phase 6: Cleanup and display results
 ```
 
 ## Principles

plugins/devflow-code-review/commands/code-review.md

@@ -117,6 +117,13 @@ Display results from all agents:
 - PR comments created/skipped (from Git)
 - Artifact paths
 
+### Phase 5: Record Pitfalls (if blocking issues found)
+
+If the review summary contains CRITICAL or HIGH blocking issues:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/code-review {branch}`
+3. Skip entirely if no CRITICAL/HIGH blocking issues
+
 ## Architecture
 
 ```
@@ -142,7 +149,9 @@ Display results from all agents:
 │  ├─ Git agent (comment-pr)
 │  └─ Synthesizer agent (mode: review)
 │
-└─ Phase 4: Display results
+├─ Phase 4: Display results
+│
+└─ Phase 5: Record Pitfalls (inline, if blocking issues)
 ```
 
 ## Principles

plugins/devflow-debug/.claude-plugin/plugin.json

@@ -19,6 +19,7 @@
   ],
   "skills": [
     "agent-teams",
-    "git-safety"
+    "git-safety",
+    "knowledge-persistence"
   ]
 }

plugins/devflow-debug/commands/debug-teams.md

@@ -189,6 +189,12 @@ Lead produces final report:
 {HIGH/MEDIUM/LOW based on consensus strength}
 ```
 
+### Phase 8: Record Pitfall (if root cause found)
+
+If root cause was identified with HIGH or MEDIUM confidence:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/debug {bug description}`
+
 ## Architecture
 
 ```
@@ -212,7 +218,9 @@ Lead produces final report:
 ├─ Phase 6: Cleanup
 │  └─ Shut down teammates, release resources
 │
-└─ Phase 7: Root cause report with confidence level
+├─ Phase 7: Root cause report with confidence level
+│
+└─ Phase 8: Record Pitfall (inline, if root cause found)
 ```
 
 ## Principles

plugins/devflow-debug/commands/debug.md

@@ -129,6 +129,12 @@ Produce the final report:
 {HIGH/MEDIUM/LOW based on evidence strength and investigator agreement}
 ```
 
+### Phase 5: Record Pitfall (if root cause found)
+
+If root cause was identified with HIGH or MEDIUM confidence:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/debug {bug description}`
+
 ## Architecture
 
 ```
@@ -143,7 +149,9 @@ Produce the final report:
 ├─ Phase 3: Synthesize
 │  └─ Synthesizer aggregates and compares findings
 │
-└─ Phase 4: Root cause report with confidence level
+├─ Phase 4: Root cause report with confidence level
+│
+└─ Phase 5: Record Pitfall (inline, if root cause found)
 ```
 
 ## Principles

plugins/devflow-implement/.claude-plugin/plugin.json

@@ -29,6 +29,7 @@
   "skills": [
     "agent-teams",
     "implementation-patterns",
+    "knowledge-persistence",
     "self-review"
   ]
 }