feat: add file-based knowledge system with decision log and plan storage (#479)

docs/decisions/0001-file-based-knowledge-system.md

@@ -0,0 +1,36 @@
+# 0001: File-based knowledge system
+
+**Status:** accepted
+**Date:** 2026-03-28
+**Area:** infra
+
+## Context
+
+Agents working on Kandev had no way to record architectural decisions or store implementation plans for future reference. This led to repeated questions about "why was X done this way?" and lost context when features were revisited. The project needed a knowledge system that works across agent providers (Claude Code, Codex, Copilot) without custom infrastructure.
+
+## Decision
+
+Use a three-tier, file-based knowledge system:
+
+- **Tier 1 (always loaded):** `CLAUDE.md` stays slim and points to Tier 2 indexes.
+- **Tier 2 (index files):** `docs/decisions/INDEX.md` and `docs/plans/INDEX.md` — one-line-per-entry tables that agents read to find relevant items.
+- **Tier 3 (individual files):** Individual ADRs (`docs/decisions/NNNN-*.md`) and plans (`docs/plans/YYYY-MM-*.md`), loaded only when needed.
+
+Architecture decisions are recorded as ADRs (this file is an example). Implementation plans are committed to `docs/plans/` as permanent records after features are implemented.
+
+A `/record` skill provides convenience for creating ADRs and plans, but the system works without it — agents can create files directly following the conventions.
+
+## Consequences
+
+- Agents can discover past decisions by reading a small index file, then drill into specific ADRs.
+- No file grows unbounded — each decision is its own file.
+- Knowledge is committed to git and survives across sessions, branches, and agent providers.
+- The `/feature` skill integrates with the decision log (reads in Phase 2, writes in Phase 6).
+- Requires discipline to record decisions — this is a convention, not an enforcement mechanism.
+
+## Alternatives Considered
+
+- **Database-backed memory (SQLite, vector search):** Too complex, requires infrastructure, doesn't work for agents that only read files.
+- **Append-only daily logs (OpenClaw pattern):** Good for persistent agents but Kandev agents are session-scoped — daily logs would accumulate noise.
+- **Auto-compaction system:** Not needed — the tiered index approach prevents unbounded growth in the first place.
+- **CLAUDE.md inline decisions:** Would make CLAUDE.md grow unbounded and overwhelm agent context.

docs/decisions/INDEX.md

@@ -0,0 +1,9 @@
+# Decision Log
+
+Architecture Decision Records (ADRs) for the Kandev project. Each decision captures the context, choice, consequences, and alternatives for significant architectural or design decisions.
+
+Read individual ADRs for full context. Create new ones via `/record decision` or manually following the template in `0001-file-based-knowledge-system.md`.
+
+| # | Title | Status | Area | Date |
+|---|-------|--------|------|------|
+| 0001 | [File-based knowledge system](0001-file-based-knowledge-system.md) | accepted | infra | 2026-03-28 |

docs/plans/INDEX.md

@@ -0,0 +1,8 @@
+# Implementation Plans
+
+Feature and architecture plans committed as permanent records. Each plan captures the problem, design, and post-implementation notes.
+
+Create new plans via `/record plan` or manually following the format below.
+
+| Plan | Status | Date | PR |
+|------|--------|------|----|