## Project Knowledge Base

An incrementally growing knowledge system for each project, enabling knowledge transfer across sessions.

### Directory Structure

```
$HOME/.claude/knowledge/
  my-app/
    architecture.md     -  module map, file relationships, dependency graph
    patterns.md         -  naming, conventions, recurring structures
    gotchas.md          -  build errors, edge cases, workarounds
    decisions.md        -  architectural decisions and rationale (ADR-lite)
  another-project/
    architecture.md
    patterns.md
    gotchas.md
    decisions.md
  ...
```

### How It Works

```
Task 1 (first time): Phase 1 -> full Explore -> Phase 7 -> create knowledge
Task 2:             Phase 1 -> read knowledge -> targeted Explore -> Phase 7 -> update knowledge
Task 3:             Phase 1 -> read knowledge -> minimal Explore -> Phase 7 -> update knowledge
  ...
Task N:             Phase 1 -> knowledge sufficient -> SKIP Explore -> Phase 7 -> update knowledge
```

Each task teaches the project a bit more. Token cost decreases over time.

### Knowledge vs CLAUDE.md vs Auto Memory

| Layer                                       | Who Writes            | Scope                                      | Lifetime                 |
| ------------------------------------------- | --------------------- | ------------------------------------------ | ------------------------ |
| `$PROJECT_ROOT/CLAUDE.md`                   | User                  | Project rules, build commands              | Persistent (in git)      |
| Auto Memory (`~/.claude/projects/`)         | Claude (automatic)    | User preferences, feedback                 | Persistent (global)      |
| **Knowledge Base** (`~/.claude/knowledge/`) | Multi-agent (Phase 7) | Architecture, patterns, gotchas, decisions | Persistent (per-project) |

They all complement each other  -  no conflicts.

### Knowledge in a Short run

A Short run skips Phase 1, but knowledge **is still read**:

- Knowledge files are added to the prompt before the Opus agent starts in Phase 3
- Knowledge capture is still performed in Phase 7 (simplified report)

### Knowledge Maintenance

Knowledge files grow over time. Maintenance rules:

- Every entry has a `<!-- captured: {date}, task: {id} -->` tag
- 90-day-old entries are considered "stale"  -  not used without verification
- Stale check: orchestrator checks file mtime during Phase 1 knowledge injection
- Stale entries are added to the prompt with a "STALE  -  verify before relying" tag
- `prune-logs` does not touch knowledge  -  only deletes logs and state
- `purge` does not touch knowledge either  -  separate command: `/multi-agent clear-knowledge {project}`

---

## Skill Injection Strategy

When calling sub-agents, inject task-specific context from previous phases:

### Phase -> Agent -> Context Flow

```
Phase 1: Analysis
  -- Explore agents (parallel) -> codebase scan

Phase 2: Planning
  -- Architecture review agent
       Context: task description + Phase 1 findings + affected modules

Phase 3: Dev
  -- Sonnet agent (TDD)
       Context: Phase 2 plan + task dependencies

Phase 4: Review (CLI-aware parallel + triage)
  Claude Code (2 parallel):
    |-- Reviewer (opus)   -> security + architecture
    +-- Reviewer (sonnet) -> quality + correctness + edge cases
  Copilot CLI (3 parallel):
    |-- Reviewer (opus)    -> security + architecture
    |-- Reviewer (gpt-5.4) -> edge cases, cross-provider diversity
    +-- Reviewer (sonnet)  -> quality + correctness + naming
       Context for ALL: Phase 1 files + Phase 2 decisions + Phase 3 diff
       Then: single Fable triage pass filters false-positives
```

### Context-Aware Agent Prompting

When launching review agents in Phase 4, include:

```
"Review this diff for {task-id}. Focus areas based on analysis:
 - {files changed summary from Phase 1}
 - {architecture decisions from Phase 2}
 - {specific risk areas identified}"
```

When launching architecture agent in Phase 2, include:

```
"Evaluate architecture for {task-id}. Context:
 - {task description}
 - {affected modules from Phase 1}
 - {existing patterns found by explore agents}"
```