archvillainetteandClaude Opus 5
bc57394290
Scaffold the per-repo configuration the engineering skills expect, and put
the three-way split of work into standing law:
- Live work -> wayfinder maps + Gitea issues (closeable, assignable,
queryable).
- Settled decisions -> ADR files in docs/adr/ (immutable, findable, never
closed).
- Standing law -> DOCTRINE.md / AGENTS.md / CONTEXT.md.
Adds docs/agents/{issue-tracker,triage-labels,domain}.md and an
"Agent skills" section in AGENTS.md. The tracker doc records Gitea via the
tea CLI, the wayfinder map/ticket/blocking operations, and the rule that
issues follow ownership: file work in the repo that owns it, not the one you
happen to be standing in.
ADR-0001 (markdown is reference, law, or an ADR - nothing else) is adopted
from sow-codebase so the rule is local to every repo.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
56 lines
2.5 KiB
Markdown
56 lines
2.5 KiB
Markdown
# ADR-0001: Markdown in this repo is reference, law, or an ADR — nothing else
|
|
|
|
- **Status:** Accepted
|
|
- **Date:** 2026-07-24
|
|
- **Origin:** Adopted workspace-wide from `sow-codebase` ADR-0001, which records
|
|
the full context (a `docs/` tree that had grown to 434 files, ~27MB, most of
|
|
it dead process artifacts). This repo adopts the same law so the rule is
|
|
local, not a cross-repo reference.
|
|
|
|
## Context
|
|
|
|
Markdown that *claims to describe current state or a plan* rots, because
|
|
reality diverges and nobody edits the file. Markdown that claims neither — a
|
|
dated, immutable decision record, or a standing rule — does not rot.
|
|
|
|
Two different things get conflated:
|
|
|
|
- **Rationale** — why a system is shaped the way it is. Worth keeping.
|
|
- **Process artifacts** — plans, specs, concepts, handoffs, trackers. A record
|
|
of how work happened, not what is true now.
|
|
|
|
Left unchecked, every completed effort leaves its planning behind and the repo
|
|
accumulates a "historical" pile that agents and humans must route around to
|
|
find the few live docs.
|
|
|
|
## Decision
|
|
|
|
Markdown may exist in this repo only as one of three genres:
|
|
|
|
1. **Current-state reference** — describes what the code does now, kept honest
|
|
by code review touching it.
|
|
2. **Standing law** — `DOCTRINE.md`, root and folder-scoped `AGENTS.md`,
|
|
`CONTEXT.md`. States rules and vocabulary, not plans.
|
|
3. **Immutable decision record** — ADRs under `docs/adr/`. Append-only; never
|
|
edited, only superseded by a later ADR that points back.
|
|
|
|
Anything else — implementation plans, design specs, concepts, handoffs,
|
|
progress trackers, scratch — is **process** and does not live in the repo. It
|
|
lives in Gitea issues and wayfinder maps, where it can be assigned, closed, and
|
|
superseded. Small tasks need no written plan at all.
|
|
|
|
Deleting a process document is not destroying history: `git log -- <path>`
|
|
recovers it. The exception is *unfinished intent* (a design never built, an
|
|
open question still wanted) — that is live, not history, and must be harvested
|
|
to a Gitea ticket before its file is deleted. A citation from a living doc or
|
|
from code must be resolved before the cited file is deleted.
|
|
|
|
## Consequences
|
|
|
|
- The documentation map lists only current truth; there is no "historical" pile
|
|
to route around.
|
|
- No agent, under any plugin or skill, writes process-markdown into the repo.
|
|
The rule is plugin-agnostic on purpose — it binds the agent, not a named tool.
|
|
- History of deleted process docs is in git; unfinished intent is in the issue
|
|
tracker; rationale is in ADRs and law. Each thing has exactly one home.
|