diff --git a/.agents/skills/feature/SKILL.md b/.agents/skills/feature/SKILL.md index 5e13da97a5..0d269b18bb 100644 --- a/.agents/skills/feature/SKILL.md +++ b/.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 diff --git a/.agents/skills/record/SKILL.md b/.agents/skills/record/SKILL.md new file mode 100644 index 0000000000..bda78ec9ee --- /dev/null +++ b/.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. +``` diff --git a/AGENTS.md b/AGENTS.md index 637bf939bf..9f9bf8b8da 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/decisions/0001-file-based-knowledge-system.md b/docs/decisions/0001-file-based-knowledge-system.md new file mode 100644 index 0000000000..2cd974e8c3 --- /dev/null +++ b/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. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md new file mode 100644 index 0000000000..6dfe6b49e5 --- /dev/null +++ b/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 | diff --git a/docs/plans/INDEX.md b/docs/plans/INDEX.md new file mode 100644 index 0000000000..2b4aeff0f6 --- /dev/null +++ b/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 | +|------|--------|------|----|