---

date: 2026-06-06 tags: [harness, docs, placement, agent-brief, premature-abstraction] status: active graduated_to:

Promoting a skill-local doc to shared: name the producer inline, single-source the consumer list

Symptom — Moving AGENT-BRIEF.md out of the triage skill dir to a shared docs/agents/agent-brief.md felt like "triage loses context — it's special about triage"; the first instinct was to revert to a per-skill doc or fork a triage-specific copy.

Root cause — The discomfort was a missing ownership signal, not a placement error. The doc is a generic brief-format spec with ≥2 real consumers (triage writes it; the build-* executors run from it; to-issues / find-untracked-work match its shape), so a single shared home is earned — per-skill copies would be the premature abstraction (four specs drifting apart). The move was a byte-for-byte pure rename, so no content was lost; the file just didn't say who produced it.

Fix — Keep it shared; add a one-line producer attribution under the H1 of docs/agents/agent-brief.md. Crucially, do not re-enumerate the full consumer list in the doc — the canonical producer/consumer framing already lives in CLAUDE.md's agent-briefs index, and a second list would drift; the inline note names only the producer + the build-* executor role.

Guard — Principle for shared harness docs: promote a skill-local doc to docs/agents/ only once ≥2 skills consume it (no-premature-abstraction cuts both ways); when you do, name the producer inline but keep the consumer relationship single-sourced in CLAUDE.md. Candidate to graduate into .claude/rules/skills.md (placement) if it recurs.