feat: per-feature knowledge bases

CLAUDE.md

@@ -46,6 +46,8 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 **Claude Code Flags**: Typed registry (`src/cli/utils/flags.ts`) for managing Claude Code feature flags (env vars and top-level settings). Pure functions `applyFlags`/`stripFlags`/`getDefaultFlags` follow the `applyTeamsConfig`/`stripTeamsConfig` pattern. Initial flags: `tool-search`, `lsp`, `clear-context-on-plan` (default ON), `brief`, `disable-1m-context` (default OFF). Manageable via `devflow flags --enable/--disable/--status/--list`. Stored in manifest `features.flags: string[]`.
 
+**Feature Knowledge Bases**: Per-feature `.features/` directory containing KNOWLEDGE.md files that capture area-specific patterns, conventions, architecture, and gotchas. KBs are created as side-effects of planning (plan:orch Phase 12), loaded automatically across all workflows via `FEATURE_KNOWLEDGE` variable (companion to `KNOWLEDGE_CONTEXT`), and use staleness detection via git log against `referencedFiles`. Index at `.features/index.json` (object keyed by slug). Managed via `devflow kb list|create|check|refresh|remove`. Knowledge agent (sonnet) structures exploration outputs into KNOWLEDGE.md. `apply-feature-kb` skill provides consumption algorithm for agents. `.features/.kb.lock` is gitignored (transient lock directory for concurrent index writes, added automatically by `devflow init`). `devflow kb list` — List all feature KBs with staleness status. `devflow kb create <slug>` — Create a new KB via claude -p exploration. `devflow kb check` — Check all KBs for staleness. `devflow kb refresh [slug]` — Refresh stale KB(s). `devflow kb remove <slug>` — Remove a KB and its index entry. Note: debug:orch keeps FEATURE_KNOWLEDGE orchestrator-local (investigation workers examine code without pre-loaded context). Toggleable via `devflow kb --enable/--disable/--status` or `devflow init --kb/--no-kb`. SessionEnd hook auto-refreshes stale KBs (throttled to once per 2 hours, max 3 per run). `.features/.disabled` sentinel gates Phase 12 generation and refresh hook.
+
 **Two-Mode Init**: `devflow init` offers Recommended (sensible defaults, quick setup) or Advanced (full interactive flow) after plugin selection. `--recommended` / `--advanced` CLI flags for non-interactive use. Recommended applies: ambient ON, memory ON, learn ON, HUD ON, teams OFF, default-ON flags, .claudeignore ON, auto-install safe-delete if trash CLI detected, user-mode security deny list.
 
 **Migrations**: Run-once migrations execute automatically on `devflow init`, tracked at `~/.devflow/migrations.json` (scope-independent; single file regardless of user-scope vs local-scope installs). Registry: append an entry to `MIGRATIONS` in `src/cli/utils/migrations.ts`. Scopes: `global` (runs once per machine, no project context) vs `per-project` (sweeps all discovered Claude-enabled projects in parallel). Failures are non-fatal — migrations retry on next init. Currently registered per-project migrations include `purge-legacy-knowledge-v2` (removes 4 hardcoded pre-v2 ADR/PF IDs and orphan `PROJECT-PATTERNS.md`) and `purge-legacy-knowledge-v3` (v3: sweeps all remaining pre-v2 seeded entries using the `- **Source**: self-learning:` format discriminator — any ADR/PF section lacking this marker is removed; entries the user edited to include the marker survive). **D37 edge case**: a project cloned *after* migrations have run won't be swept (the marker is global, not per-project). Recovery: `rm ~/.devflow/migrations.json` forces a re-sweep on next `devflow init`.
@@ -54,15 +56,16 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 41 skills (single source of truth)
-├── shared/agents/          # 12 shared agents (single source of truth)
+├── shared/skills/          # 44 skills (single source of truth)
+├── shared/agents/          # 13 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
 ├── scripts/                # Helper scripts (statusline, docs-helpers)
-│   └── hooks/              # Working Memory + ambient + learning hooks (prompt-capture-memory, stop-update-memory, background-memory-update, session-start-memory, session-start-classification, pre-compact-memory, preamble, session-end-learning, stop-update-learning [deprecated], background-learning, get-mtime)
-├── src/cli/                # TypeScript CLI (init, list, uninstall, ambient, learn, flags)
+│   └── hooks/              # Working Memory + ambient + learning hooks (prompt-capture-memory, stop-update-memory, background-memory-update, session-start-memory, session-start-classification, pre-compact-memory, preamble, session-end-learning, stop-update-learning [deprecated], background-learning, get-mtime, session-end-kb-refresh, background-kb-refresh)
+├── src/cli/                # TypeScript CLI (init, list, uninstall, ambient, learn, flags, kb)
 ├── .claude-plugin/         # Marketplace registry
 ├── .docs/                  # Project docs (reviews, design) — per-project
+├── .features/              # Per-feature knowledge bases (committed to git)
 └── .memory/                # Working memory files — per-project
 ```
 
@@ -150,7 +153,7 @@ Working memory files live in a dedicated `.memory/` directory:
 - `/self-review` — Simplifier then Scrutinizer (sequential); consumes knowledge via index + on-demand Read via `devflow:apply-knowledge`
 - `/audit-claude` — CLAUDE.md audit (optional plugin)
 
-**Shared agents** (12): git, synthesizer, skimmer, simplifier, coder, reviewer, resolver, evaluator, tester, scrutinizer, validator, designer
+**Shared agents** (13): git, synthesizer, skimmer, simplifier, coder, reviewer, resolver, evaluator, tester, scrutinizer, validator, designer, knowledge
 
 **Plugin-specific agents** (1): claude-md-auditor
 

docs/reference/file-organization.md

@@ -9,13 +9,13 @@ devflow/
 ├── .claude-plugin/                   # Marketplace registry (repo root)
 │   └── marketplace.json
 ├── shared/
-│   ├── skills/                       # SINGLE SOURCE OF TRUTH (41 skills)
+│   ├── skills/                       # SINGLE SOURCE OF TRUTH (44 skills)
 │   │   ├── git/
 │   │   │   ├── SKILL.md
 │   │   │   └── references/
 │   │   ├── software-design/
 │   │   └── ...
-│   └── agents/                       # SINGLE SOURCE OF TRUTH (12 shared agents)
+│   └── agents/                       # SINGLE SOURCE OF TRUTH (13 shared agents)
 │       ├── git.md
 │       ├── synthesizer.md
 │       ├── coder.md
@@ -42,7 +42,7 @@ devflow/
 │   ├── build-hud.js                  # Copies dist/hud/ → scripts/hud/
 │   ├── hud.sh                        # Thin wrapper: exec node hud/index.js
 │   ├── hud/                          # GENERATED — compiled HUD module (gitignored)
-│   └── hooks/                        # Working Memory + ambient + learning hooks
+│   └── hooks/                        # Working Memory + ambient + learning + KB 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
@@ -52,9 +52,16 @@ devflow/
 │       ├── session-end-learning      # SessionEnd hook: batched learning trigger
 │       ├── stop-update-learning     # Stop hook: deprecated stub (upgrade via devflow learn)
 │       ├── background-learning      # Background: pattern detection via Sonnet
+│       ├── session-end-kb-refresh   # SessionEnd hook: stale KB detection + background spawn
+│       ├── background-kb-refresh    # Background: KB refresher via Sonnet
 │       ├── get-mtime                # Shared helper: portable mtime (BSD/GNU stat)
 │       ├── json-helper.cjs           # Node.js jq-equivalent operations
-│       └── json-parse               # Shell wrapper: jq with node fallback
+│       ├── json-parse               # Shell wrapper: jq with node fallback
+│       └── lib/                      # Node.js helper modules
+│           ├── feature-kb.cjs        # Feature KB index operations (CRUD, staleness)
+│           ├── knowledge-context.cjs  # Knowledge context index builder
+│           ├── staleness.cjs          # Code reference staleness checker
+│           └── transcript-filter.cjs  # Transcript channel extractor
 └── src/
     └── cli/
         ├── commands/
@@ -138,7 +145,7 @@ Skills and agents are **not duplicated** in git. Instead:
 
 ### Shared vs Plugin-Specific Agents
 
-- **Shared** (12): `git`, `synthesizer`, `skimmer`, `simplifier`, `coder`, `reviewer`, `resolver`, `evaluator`, `tester`, `scrutinizer`, `validator`, `designer`
+- **Shared** (13): `git`, `synthesizer`, `skimmer`, `simplifier`, `coder`, `reviewer`, `resolver`, `evaluator`, `tester`, `scrutinizer`, `validator`, `designer`, `knowledge`
 - **Plugin-specific** (1): `claude-md-auditor` — committed directly in its plugin
 
 ## Settings Override
@@ -147,7 +154,7 @@ Skills and agents are **not duplicated** in git. Instead:
 
 Included settings:
 - `statusLine` - Configurable HUD with presets (replaces legacy statusline.sh)
-- `hooks` - Working Memory hooks (UserPromptSubmit, Stop, SessionStart, PreCompact) + Learning Stop hook
+- `hooks` - Working Memory hooks (UserPromptSubmit, Stop, SessionStart, PreCompact) + Learning SessionEnd hook + KB SessionEnd hook
 - `env.ENABLE_TOOL_SEARCH` - Deferred MCP tool loading (~85% token savings)
 - `env.ENABLE_LSP_TOOL` - Language Server Protocol support
 - `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` - Agent Teams for peer-to-peer collaboration
@@ -158,7 +165,9 @@ Included settings:
 
 Four hooks in `scripts/hooks/` provide automatic session continuity. Toggleable via `devflow memory --enable/--disable/--status` or `devflow init --memory/--no-memory`.
 
-A fifth hook (`session-end-learning`) provides self-learning. Toggleable via `devflow learn --enable/--disable/--status` or `devflow init --learn/--no-learn`:
+A fifth hook (`session-end-kb-refresh`) provides feature KB maintenance. Toggleable via `devflow kb --enable/--disable/--status` or `devflow init --kb/--no-kb`.
+
+A sixth hook (`session-end-learning`) provides self-learning. Toggleable via `devflow learn --enable/--disable/--status` or `devflow init --learn/--no-learn`:
 
 | Hook | Event | File | Purpose |
 |------|-------|------|---------|
@@ -167,6 +176,8 @@ A fifth hook (`session-end-learning`) provides self-learning. Toggleable via `de
 | `background-memory-update` | (background) | `.memory/WORKING-MEMORY.md` | Queue-based updater spawned by stop-update-memory. Reads queued turns + git state, writes WORKING-MEMORY.md via `claude -p --model haiku`. |
 | `session-start-memory` | SessionStart | reads WORKING-MEMORY.md | Injects previous memory + git state as `additionalContext`. Warns if >1h stale. Injects pre-compact snapshot when compaction occurred mid-session. |
 | `pre-compact-memory` | PreCompact | `.memory/backup.json` | Saves git state + WORKING-MEMORY.md snapshot. Bootstraps minimal WORKING-MEMORY.md if none exists. |
+| `session-end-kb-refresh` | SessionEnd | `.features/index.json` | Checks for stale feature KBs. Throttled (<2h). Spawns background-kb-refresh. |
+| `background-kb-refresh` | (background) | `.features/{slug}/KNOWLEDGE.md` | KB refresher. Up to 3 stale KBs via `claude -p --model sonnet`. |
 
 **Flow**: User sends prompt → UserPromptSubmit hook (prompt-capture-memory) appends user turn to `.memory/.pending-turns.jsonl`. Session ends → Stop hook appends assistant turn to queue, checks throttle (skips if <2min fresh), spawns background updater → background updater reads queued turns + git state → fresh `claude -p --model haiku` writes WORKING-MEMORY.md. On `/clear` or new session → SessionStart injects memory as `additionalContext` (system context, not user-visible) with staleness warning if >1h old.
 
@@ -180,8 +191,8 @@ Knowledge files in `.memory/knowledge/` capture decisions and pitfalls that agen
 
 | 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 |
+| `decisions.md` | ADR-NNN (sequential) | `background-learning` | Architectural decisions — why choices were made |
+| `pitfalls.md` | PF-NNN (sequential) | `background-learning` | 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.
 

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

@@ -27,7 +27,8 @@
     "git",
     "synthesizer",
     "resolver",
-    "designer"
+    "designer",
+    "knowledge"
   ],
   "skills": [
     "router",
@@ -53,6 +54,8 @@
     "qa",
     "worktree-support",
     "gap-analysis",
-    "design-review"
+    "design-review",
+    "feature-kb",
+    "apply-feature-kb"
   ]
 }

plugins/devflow-ambient/agents/knowledge.md

@@ -0,0 +1,58 @@
+---
+name: Knowledge
+description: Structures codebase exploration into a feature knowledge base
+model: sonnet
+skills:
+  - devflow:feature-kb
+  - devflow:apply-feature-kb
+  - devflow:apply-knowledge
+  - devflow:worktree-support
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+# Knowledge Agent
+
+## Input Context
+
+- **FEATURE_SLUG** (required): Kebab-case identifier for the feature area (e.g., `cli-commands`)
+- **FEATURE_NAME** (required): Human-readable name (e.g., "CLI Command System")
+- **EXPLORATION_OUTPUTS** (required): Combined findings from Skimmer + Explore agents
+- **DIRECTORIES** (required): Directory prefixes defining the feature area scope
+- **KNOWLEDGE_CONTEXT** (optional): Existing ADR/PF index for cross-referencing
+- **EXISTING_KB** (optional): Current KNOWLEDGE.md content when refreshing a stale KB
+- **CHANGED_FILES** (optional): Files that changed since last KB update (for refresh)
+- **WORKTREE_PATH** (optional): Worktree root for path resolution
+
+## Responsibilities
+
+1. **Resolve worktree path**: Use `devflow:worktree-support` to determine the working directory
+2. **Orient on feature area**: Read EXPLORATION_OUTPUTS to understand the feature's architecture, patterns, and boundaries
+3. **Follow the feature-kb skill**: Execute the 4-phase process (Scan → Extract → Distill → Forge) from `devflow:feature-kb`
+4. **Cross-reference knowledge**: If KNOWLEDGE_CONTEXT is provided, reference relevant ADR/PF entries in the KB's "Related" section
+5. **Handle refresh**: If EXISTING_KB is provided, update stale sections based on CHANGED_FILES while preserving any manually added content (user edits). Don't regenerate from scratch.
+6. **Write KNOWLEDGE.md**: Write to `.features/{FEATURE_SLUG}/KNOWLEDGE.md` (create directory if needed)
+7. **Write sidecar**: Write sidecar JSON file (`.create-result.json` or `.refresh-result.json`) with `referencedFiles` and `description` so the host process can update the index
+8. **Report**: Output what was created/updated
+
+## Output
+
+```
+KB_STATUS: created | refreshed
+KB_PATH: .features/{slug}/KNOWLEDGE.md
+KB_SLUG: {slug}
+KB_NAME: {name}
+SECTIONS: [list of sections written]
+REFERENCED_FILES: [files selected for staleness tracking]
+CROSS_REFERENCES: [ADR/PF entries referenced, if any]
+```
+
+## Boundaries
+
+- **Only writes to `.features/` directory** — never modify source code
+- **Never delete existing KBs** — only create new or refresh existing
+- **500-line cap** — if KB exceeds 500 lines, split into focused sub-KBs (each gets own index entry)
+- **No push, no external API calls** — local filesystem operations only

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

@@ -33,6 +33,7 @@
     "review-methodology",
     "security",
     "testing",
-    "worktree-support"
+    "worktree-support",
+    "apply-feature-kb"
   ]
 }

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

@@ -95,7 +95,7 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 
 ### Phase 1b: Load Knowledge Index
 
-**Produces:** KNOWLEDGE_CONTEXT
+**Produces:** KNOWLEDGE_CONTEXT, FEATURE_KNOWLEDGE
 
 Load the knowledge index for the current worktree before spawning the review team:
 
@@ -105,6 +105,14 @@ KNOWLEDGE_CONTEXT=$(node scripts/hooks/lib/knowledge-context.cjs index "{worktre
 
 This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT` to each reviewer teammate prompt. Reviewers use `devflow:apply-knowledge` to Read full entry bodies on demand.
 
+**Load Feature Knowledge:**
+1. Read `.features/index.json` if it exists
+2. Based on changed files from Phase 1 analysis, identify relevant KBs (match file paths against KB `directories` and `referencedFiles`)
+3. For each match: check staleness via `node scripts/hooks/lib/feature-kb.cjs stale "{worktree}" {slug}`, read `.features/{slug}/KNOWLEDGE.md`
+4. Set `FEATURE_KNOWLEDGE` (or `(none)` if no KBs exist or none are relevant)
+
+Pass `FEATURE_KNOWLEDGE` to each reviewer teammate alongside `KNOWLEDGE_CONTEXT`.
+
 ### Phase 2: Spawn Review Team
 
 **Produces:** REVIEWER_OUTPUTS
@@ -143,16 +151,18 @@ Spawn review teammates. For each teammate, compose a self-contained prompt using
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     WORKTREE_PATH: {worktree_path}  (omit if cwd)
     KNOWLEDGE_CONTEXT: {knowledge_context}
+    FEATURE_KNOWLEDGE: {feature_knowledge}
     1. Read your skill(s): `Read {SKILL_PATHS}`
     2. Read review methodology: `Read ~/.claude/skills/devflow:review-methodology/SKILL.md`
     3. Follow devflow:apply-knowledge to scan KNOWLEDGE_CONTEXT index and Read full ADR/PF bodies on demand. Skip if (none).
-    4. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
-    5. Apply the 6-step review process from devflow:review-methodology
-    6. Focus: {FOCUS}
-    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    8. Include file:line references for every finding
-    9. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/{REPORT_NAME}.md`
-    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "{SUMMARY}")
+    4. Follow devflow:apply-feature-kb for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings. Skip if (none).
+    5. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
+    6. Apply the 6-step review process from devflow:review-methodology
+    7. Focus: {FOCUS}
+    8. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    9. Include file:line references for every finding
+    10. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/{REPORT_NAME}.md`
+    11. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "{SUMMARY}")
 
 **Core reviewers (always spawn):**