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>
2.5 KiB
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-codebaseADR-0001, which records the full context (adocs/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:
- Current-state reference — describes what the code does now, kept honest by code review touching it.
- Standing law —
DOCTRINE.md, root and folder-scopedAGENTS.md,CONTEXT.md. States rules and vocabulary, not plans. - 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.