fix: Wave 2 post-merge cleanup — knowledge persistence & command consistency

CLAUDE.md

@@ -44,7 +44,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 31 skills (single source of truth)
+├── shared/skills/          # 32 skills (single source of truth)
 ├── shared/agents/          # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (9 core + 8 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
@@ -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:

docs/reference/skills-architecture.md

@@ -21,6 +21,7 @@ Shared patterns used by multiple agents.
 | `github-patterns` | GitHub API patterns (rate limiting, PR comments, issues, releases) | Git |
 | `implementation-patterns` | CRUD, API endpoints, events, config, logging | Coder, Resolver |
 | `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /code-review, /implement, /debug |
+| `knowledge-persistence` | Record/load architectural decisions and pitfalls to `.memory/knowledge/` | /implement, /code-review, /resolve, /debug, /specify, /self-review |
 
 ### Tier 1b: Pattern Skills
 

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

@@ -23,7 +23,11 @@ Investigate bugs by spawning a team of agents, each pursuing a different hypothe
 
 ## Phases
 
-### Phase 1: Context Gathering
+### Phase 1: Load Project Knowledge
+
+Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md`. Known pitfalls from prior debugging sessions and code reviews can directly inform hypothesis generation — pass their content as context to investigators in Phase 2.
+
+### Phase 2: Context Gathering
 
 If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
 
@@ -39,7 +43,7 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible
 - **Testable**: Can be confirmed or disproved by reading code/logs
 - **Distinct**: Does not overlap significantly with other hypotheses
 
-### Phase 2: Spawn Investigation Team
+### Phase 3: Spawn Investigation Team
 
 Create an agent team with one investigator per hypothesis:
 
@@ -99,7 +103,7 @@ Spawn investigator teammates with self-contained prompts:
 (Add more investigators if bug complexity warrants 4-5 hypotheses — same pattern)
 ```
 
-### Phase 3: Investigation
+### Phase 4: Investigation
 
 Teammates investigate in parallel:
 - Read relevant source files
@@ -108,7 +112,7 @@ Teammates investigate in parallel:
 - Look for edge cases and race conditions
 - Build evidence for or against their hypothesis
 
-### Phase 4: Adversarial Debate
+### Phase 5: Adversarial Debate
 
 Lead initiates debate via broadcast:
 
@@ -135,7 +139,7 @@ Teammates challenge each other directly using SendMessage:
 - `SendMessage(type: "message", recipient: "team-lead", summary: "Updated hypothesis")`
   "I've updated my hypothesis based on investigator-b's finding at..."
 
-### Phase 5: Convergence
+### Phase 6: Convergence
 
 After debate (max 2 rounds), lead collects results:
 
@@ -147,7 +151,7 @@ Lead broadcast:
 - PARTIAL: Some aspects confirmed, others not (details)"
 ```
 
-### Phase 6: Cleanup
+### Phase 7: Cleanup
 
 Shut down all investigator teammates explicitly:
 
@@ -160,7 +164,7 @@ TeamDelete
 Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HALT.
 ```
 
-### Phase 7: Report
+### Phase 8: Report
 
 Lead produces final report:
 
@@ -189,30 +193,40 @@ Lead produces final report:
 {HIGH/MEDIUM/LOW based on consensus strength}
 ```
 
+### Phase 9: 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
 
 ```
 /debug (orchestrator)
 │
-├─ Phase 1: Context gathering
+├─ Phase 1: Load Project Knowledge
+│
+├─ Phase 2: Context gathering
 │  └─ Git agent (fetch issue, if #N provided)
 │
-├─ Phase 2: Spawn investigation team
+├─ Phase 3: Spawn investigation team
 │  └─ Create team with 3-5 hypothesis investigators
 │
-├─ Phase 3: Parallel investigation
+├─ Phase 4: Parallel investigation
 │  └─ Each teammate investigates independently
 │
-├─ Phase 4: Adversarial debate
+├─ Phase 5: Adversarial debate
 │  └─ Teammates challenge each other directly (max 2 rounds)
 │
-├─ Phase 5: Convergence
+├─ Phase 6: Convergence
 │  └─ Teammates submit final hypothesis status
 │
-├─ Phase 6: Cleanup
+├─ Phase 7: Cleanup
 │  └─ Shut down teammates, release resources
 │
-└─ Phase 7: Root cause report with confidence level
+├─ Phase 8: Root cause report with confidence level
+│
+└─ Phase 9: Record Pitfall (inline, if root cause found)
 ```
 
 ## Principles