docs: adopt workspace-wide agent standards and retire sow-docs
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.
sow-docs is retired: its 35 decisions become ADRs in the repos that own them,
its living docs move to sow-platform and sow-assets-manifest, and its
unfinished intent becomes Gitea issues.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user