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

.agents/skills/feature/SKILL.md

@@ -23,7 +23,8 @@ Systematic feature development: understand the problem, explore the codebase, de
    - Architecture and abstractions in the relevant area
    - Integration points, data flow, and extension points
 2. Read all key files the agents identify
-3. Present a summary of existing patterns and conventions to reuse
+3. Check `docs/decisions/INDEX.md` for relevant architectural decisions in this area
+4. Present a summary of existing patterns and conventions to reuse
 
 ## Phase 3: Design
 
@@ -73,3 +74,5 @@ Run `/qa` as a subagent (keeps the main context clean) to verify the feature wor
 3. Run `/code-review` as a subagent on the changes
 4. Fix any blockers, present suggestions to the user
 5. Summarize: what was built, key decisions, files modified, suggested next steps
+6. If significant architectural decisions were made, record them via `/record decision`
+7. Save the feature design to `docs/plans/` via `/record plan` for permanent reference

.agents/skills/record/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: record
+description: Record an architectural decision (ADR) or save an implementation plan. Use after making significant design choices or completing features.
+---
+
+# Record Knowledge
+
+Record architectural decisions and implementation plans for future reference.
+
+## Record a decision
+
+When a significant architectural or design choice is made, create an ADR:
+
+1. Read `docs/decisions/INDEX.md` to find the next number
+2. Create `docs/decisions/NNNN-short-title.md` using the template below
+3. Update `docs/decisions/INDEX.md` with the new entry
+
+### ADR template
+
+```markdown
+# NNNN: Short Title
+
+**Status:** accepted | superseded by NNNN | deprecated
+**Date:** YYYY-MM-DD
+**Area:** backend | frontend | infra | protocol | workflow
+
+## Context
+What situation prompted this decision. 2-5 sentences.
+
+## Decision
+What was decided. Reference file paths, packages, interfaces.
+
+## Consequences
+Trade-offs. What becomes easier or harder.
+
+## Alternatives Considered
+What else was considered and why it was rejected.
+```
+
+### What warrants an ADR
+
+- Choosing one approach over another (e.g., event bus vs direct calls)
+- Adding a new dependency or library
+- Changing a data model or API contract
+- Selecting a pattern that affects multiple files (e.g., provider pattern for DI)
+- Decisions that future developers will ask "why?" about
+
+### What does NOT need an ADR
+
+- Bug fixes, refactors within the same pattern, simple features
+- Anything where the choice is obvious and uncontested
+
+## Save a plan
+
+After implementing a feature, save the design as a permanent record:
+
+1. Read `docs/plans/INDEX.md` to check for existing plan
+2. Create `docs/plans/YYYY-MM-feature-name.md` using the template below
+3. Update `docs/plans/INDEX.md` with the new entry
+
+### Plan template
+
+```markdown
+# Feature/Plan Title
+
+**Date:** YYYY-MM-DD
+**Status:** proposed | approved | implemented | abandoned
+**PR:** #NNN
+**Decision:** ADR-NNNN (if applicable)
+
+## Problem
+What problem this solves.
+
+## Design
+File paths, interfaces, data flow. Mermaid diagrams where useful.
+
+## Implementation Notes
+Post-implementation: what changed from the plan, gotchas, things the next person should know.
+```

AGENTS.md

@@ -287,6 +287,10 @@ Static analysis runs in CI and pre-commit. New code **must** stay within these l
 
 **When you hit a limit:** extract a helper function, custom hook, or sub-component. Prefer composition over growing a single function.
 
+### Knowledge
+- **Decisions:** Architecture decisions are recorded in `docs/decisions/`. Read `docs/decisions/INDEX.md` for an overview. When making significant architectural choices, create a new ADR via `/record decision`.
+- **Plans:** Implementation plans are stored in `docs/plans/`. Save completed feature designs via `/record plan`.
+
 ### Backend
 - Provider pattern for DI; stderr for logs, stdout for ACP only
 - Pass context through chains; event bus for cross-component comm

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 |
+|------|--------|------|----|