dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

docs: decentralize ADR identifiers (#1746)

Browse Source
This commit is contained in:
Carlos Florêncio
2026-07-16 23:13:27 +01:00
committed by GitHub
parent 323d65db95
commit dddb5496b0
4 changed files with 52 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/record/SKILL.md
+30 -15
View File
@@ -1,6 +1,6 @@
---
name: record
description: 'Keep docs/decisions/ ADRs and docs/specs/ specs in sync with the work happening in the conversation. AUTO-INVOKE proactively the moment the user asks for any change that will alter architecture or observable product behavior — new feature, cross-cutting refactor, dependency swap, data-model or public-API change, new pattern, or a bug fix that changes documented behavior or reveals a spec gap. Also invoke on explicit triggers: "record this", "create an ADR", "document this decision", "update the spec", "ADR for X". Run BEFORE coding when the decision is upfront, or AFTER landing when the right call only became clear during implementation. SKIP for typo/lint fixes, refactors that preserve behavior within an existing pattern, and obvious uncontested choices.'
description: 'Keep durable architecture decisions and product specs in sync with the work happening in the conversation. AUTO-INVOKE when a request establishes or changes a long-lived architectural boundary, public contract, data ownership rule, operational invariant, or repo-wide convention with meaningful alternatives. Also invoke on explicit triggers: "record this", "create an ADR", "document this decision", "update the spec", "ADR for X". Run BEFORE coding when the decision is upfront, or AFTER landing when the right call only became clear during implementation. Do not create ADRs for simple features, local implementation choices, routine dependency changes, or bug fixes that do not establish a durable rule.'
---
# Record Knowledge
@@ -11,17 +11,22 @@ Record architectural decisions for future reference, and keep related feature sp
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
4. **Reconcile specs** — see "Update or create a spec" below
1. Choose a decentralized ID in the form `YYYY-MM-DD-short-title`. The short title must be
specific enough to remain unique among decisions created on the same date.
2. Confirm that `docs/decisions/<id>.md` does not already exist.
3. Create `docs/decisions/<id>.md` using the template below.
4. Update `docs/decisions/INDEX.md` with the new entry.
5. **Reconcile specs** — see "Update or create a spec" below.
Existing numeric ADR IDs remain valid and must not be renamed. References use the complete stable
ID, for example `ADR-2026-07-16-project-shell-output`.
### ADR template
```markdown
# NNNN: Short Title
# ADR-YYYY-MM-DD-short-title: Short Title
**Status:** accepted | superseded by NNNN | deprecated
**Status:** accepted | superseded by <adr-id> | deprecated
**Date:** YYYY-MM-DD
**Area:** backend | frontend | infra | protocol | workflow
@@ -40,16 +45,26 @@ 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
Create an ADR only when all of these are true:
- The choice establishes a durable constraint, boundary, contract, ownership rule, operational
invariant, or repo-wide convention.
- There were meaningful alternatives with materially different trade-offs.
- Future work will need to follow or deliberately supersede the choice.
- A spec, plan, code comment, or regression test alone would not preserve enough of the reasoning.
Typical examples include selecting a system-wide communication model, defining ownership across
subsystems, changing a public API or persisted-data contract, and adopting a cross-cutting security
or reliability invariant.
### What does NOT need an ADR
- Bug fixes, refactors within the same pattern, simple features
- Anything where the choice is obvious and uncontested
- Simple features whose behavior belongs in a product spec
- Local implementation tactics and refactors within an existing pattern
- Routine dependency additions or upgrades
- Bug fixes unless they establish a new rule that future implementations must follow
- Plan sequencing, task breakdown, and temporary migration mechanics
- Anything obvious, uncontested, or easily reversible without cross-system consequences
## Update or create a spec
@@ -57,7 +72,7 @@ ADRs capture *why* a decision was made. Specs capture *what* a feature does and
1. Read `docs/specs/INDEX.md` and identify any spec whose scope the decision touches (e.g., a routing decision affects `office-provider-routing/spec.md`).
2. For each affected spec:
- **If the decision changes observable behavior, scope, or scenarios:** update `docs/specs/<slug>/spec.md` so the "What" and "Why" sections reflect the new direction. Add a `Decision: ADR-NNNN` reference where relevant.
- **If the decision changes observable behavior, scope, or scenarios:** update `docs/specs/<slug>/spec.md` so the "What" and "Why" sections reflect the new direction. Add a `Decision: ADR-<id>` reference where relevant.
- **If the decision is purely internal (implementation choice with no spec-visible change):** no spec edit needed — the ADR alone is sufficient.
3. If the decision introduces a new product feature that has no spec yet, invoke `/spec` to create one rather than writing it ad-hoc here.
4. If no spec applies (pure infra/process decision, like this knowledge system itself), skip — note in the ADR that no spec is needed.
.agents/skills/spec/SKILL.md
+1 -1
View File
@@ -209,7 +209,7 @@ A padded spec is worse than a short one — it hides the requirements behind cer
## Style notes
- **Symbols in code font.** File paths, packages, types, table names: `internal/agent/lifecycle`, `TaskSession`, `task_session_worktrees`.
- **Cross-link, don't duplicate.** Reference ADRs (`../../decisions/NNNN-...md`) and other specs rather than restating their content.
- **Cross-link, don't duplicate.** Reference ADRs (`../../decisions/<adr-id>.md`) and other specs rather than restating their content.
- **Specs rarely need diagrams.** A user-flow mermaid is acceptable when it clarifies a multi-step interaction. Architectural diagrams do not belong here — those go in ADRs.
- **Present tense, active voice.** "The agent resumes the turn" — not "the turn will be resumed by the agent".
- **Concrete over abstract.** "Wakeups fire at most once per 60s per agent" is testable; "wakeups are rate-limited appropriately" is not.
docs/decisions/0001-file-based-knowledge-system.md
+19 -2
View File
@@ -1,7 +1,7 @@
# 0001: File-based knowledge system
**Status:** accepted
**Date:** 2026-03-28 (updated 2026-05-15)
**Date:** 2026-03-28 (updated 2026-07-16)
**Area:** infra
## Context
@@ -14,12 +14,23 @@ 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/specs/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 feature specs (`docs/specs/<slug>/spec.md`), loaded only when needed.
- **Tier 3 (individual files):** Individual ADRs (`docs/decisions/<adr-id>.md`) and feature specs (`docs/specs/<slug>/spec.md`), loaded only when needed.
ADRs `0001` through `0042` retain their numeric IDs. New ADRs use decentralized,
date-prefixed IDs in the form `YYYY-MM-DD-short-title`, with a sufficiently specific slug to avoid
same-day collisions. The complete filename stem is the stable ADR ID. This removes the need for
parallel branches to reserve a shared next number.
Architecture decisions are recorded as ADRs (this file is an example). Product features are captured as specs under `docs/specs/<slug>/` — the "what & why", committed to git. Implementation plans (`docs/specs/<slug>/plan.md`) and post-ship notes (`docs/specs/<slug>/notes.md`) live alongside specs but are **gitignored** — they are ephemeral working files regenerated from the spec as needed, not permanent records.
A `/record` skill creates ADRs and a `/spec` skill creates specs, but the system works without them — agents can create files directly following the conventions.
ADRs are reserved for durable architectural constraints, boundaries, contracts, ownership rules,
operational invariants, and repo-wide conventions for which meaningful alternatives existed.
Simple features belong in specs, implementation sequencing belongs in plans, and local tactics or
ordinary bug fixes remain in code, tests, and commit history unless they establish a rule that
future work must follow.
## Consequences
- Agents can discover past decisions by reading a small index file, then drill into specific ADRs.
@@ -27,9 +38,15 @@ A `/record` skill creates ADRs and a `/spec` skill creates specs, but the system
- 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.
- Date-prefixed IDs are longer than sequence numbers, but branches can create them independently
without filename collisions over the next shared integer.
## Alternatives Considered
- **Continue allocating sequential ADR numbers:** Rejected for new ADRs because parallel branches
must read and update the same allocation point, producing duplicate IDs and avoidable conflicts.
- **Use random UUIDs:** Rejected because they avoid coordination but make filenames and references
difficult to scan. A date plus specific slug is decentralized while remaining recognizable.
- **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.
docs/decisions/INDEX.md
+2 -2
View File
@@ -4,9 +4,9 @@ Architecture Decision Records (ADRs) for the Kandev project. Each decision captu
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 |
| ID | Title | Status | Area | Date |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------- | ---------- |
| 0001 | [File-based knowledge system](0001-file-based-knowledge-system.md) | accepted | infra | 2026-03-28 |
| 0001 | [File-based knowledge system](0001-file-based-knowledge-system.md) | accepted (amended 2026-07-16) | infra | 2026-03-28 |
| 0002 | [Host utility agentctl for sessionless ACP flows](0002-host-utility-agentctl-for-sessionless-flows.md) | accepted | backend | 2026-04-08 |
| 0003 | [executors_running as the single source of truth for agent_execution_id](0003-executors-running-as-execution-id-source-of-truth.md) | accepted | backend | 2026-05-03 |
| 0004 | [Task model unification — shared base, per-strategy meta, shared kernel](0004-task-model-unification.md) | proposed | backend, frontend | 2026-05-05 |