Imported from avmnu-sng/sutra (plugins/sutra/skills/agent-docs-architecture/SKILL.md). Install upstream with npx skills add avmnu-sng/sutra --skill agent-docs-architecture. Copyright stays with the author.

Agent docs architecture

Agent-facing docs fail in one of two ways: everything is crammed into a single entry file that no one can navigate, or the guidance is scattered with no declared order, no source of truth, and no way for an agent to tell which doc answers its question. Both leave an agent guessing, and a guessing agent hallucinates.

This skill lays out the structure that prevents that. The goal is a layered tree where a thin entry doc routes to deeper guides, one rulebook is shared verbatim across tools, every doc's job is declared, and one doc is named as ground truth. The machine-readable manifest that binds these pieces together -- entry-doc path, rulebook path, source-path-to-domain routing, skill order -- lives in examples/setup.yaml. Treat that file as the contract and this skill as the rationale.

When to use

• Setting up agent docs (AGENTS.md, CLAUDE.md, a docs/ tree) in a repo that has none, or has an overgrown single file.
• Auditing an existing tree for the failure modes below: inlined entry doc, drifted cross-tool rules, no routing table, no declared source of truth.
• Adding a new domain guide and wanting it to match the house shape rather than being one more ad-hoc file.

When not to use

• The repo has no agents and no intent to add them; a plain README is enough.
• You are writing product or API docs for end users. This skill is about docs an agent reads to do work in the repo, not docs a customer reads.

1. Layer the tree; keep the entry doc thin

The entry doc (AGENTS.md or CLAUDE.md) is a switchboard, not an encyclopedia. It states the project in two sentences, names the hard rules, and links out to deeper docs. It does not inline setup steps, domain walkthroughs, or troubleshooting -- those live in leaf docs and go stale the moment they are duplicated at the top.

Target shape:

AGENTS.md                 <- thin entry: what this is, STOP-gate, routing table
CLAUDE.md                 <- byte-identical AI footer (see section 2)
docs/
  rules.md                <- the one shared rulebook
  setup.md                <- environment, toolchain, dev loop
  domains/
    <domain>.md           <- one guide per feature area (routing in setup.yaml)
  guides/
    <topic>.md            <- safety / domain guides (authored per section 8)
  ground-truth.md         <- the source of truth (see section 6)
examples/
  setup.yaml              <- machine-readable manifest binding all of the above

Rules of thumb:

• If the entry doc is longer than one screen, content has leaked in that belongs in a leaf. Move it and leave a link.
• Every leaf doc opens with one line stating its job ("This doc covers X; for Y see Z"). An agent should be able to reject a doc in one line.
• Depth over breadth. A three-level tree an agent can walk beats a flat pile of twenty sibling files with no ordering.

2. One rulebook, shared verbatim across tools

Humans and agents follow the same rules. Maintain a single docs/rules.md. Different agent tools look for their guidance in different filenames (AGENTS.md, CLAUDE.md, and others), so the AI-instructions footer must be byte-identical across every one of those files -- not paraphrased, not "kept roughly in sync." Divergence is how one tool ends up operating under stale rules.

Mechanics:

1. Author the footer once in a canonical block.
2. Copy it verbatim into each tool's entry file.
3. Add a CI check that fails on any byte difference between the copies.

A minimal divergence gate (adapt paths to setup.yaml):

# fail if the shared AI footer drifts between entry files
diff <(sed -n '/BEGIN-AI-FOOTER/,/END-AI-FOOTER/p' AGENTS.md) \
     <(sed -n '/BEGIN-AI-FOOTER/,/END-AI-FOOTER/p' CLAUDE.md) \
  || { echo "AI footer drifted between AGENTS.md and CLAUDE.md"; exit 1; }

Wrap the shared region in stable BEGIN-AI-FOOTER / END-AI-FOOTER markers so the check compares the intended span and nothing else. When you edit the footer, edit the canonical copy and re-propagate; never hand-patch one file.

3. Compliance STOP-gate plus a routing table

The first thing an agent reads in the entry doc is a STOP-gate: a short, unmissable block that says "before you touch anything, confirm you have read X and understood Y." It exists to stop an agent from acting before it knows the rules.

Immediately after the STOP-gate, put a "what you need -> which doc" routing table so the agent lands on the right doc instead of scanning the tree:

STOP. Before making any change:
  1. Read docs/rules.md (the shared rulebook).
  2. Confirm the source of truth for your task (section: Source of truth).
  3. If anything is unclear, ask or read -- do not guess.

What you need                     -> Read this
--------------------------------------------------------------
Set up the environment / dev loop -> docs/setup.md
Rules that gate every change      -> docs/rules.md
Work inside a feature area        -> docs/domains/<area>.md  (map: setup.yaml)
Write a new safety/domain guide   -> this skill, section 8
Resolve a conflict between docs   -> docs/ground-truth.md

Keep the table short and outcome-phrased ("Set up the environment", not "setup.md"). The left column is the question the agent is actually asking.

4. Handoff table for multi-step / multi-skill work

When work flows across steps or skills, values get produced in one place and consumed in another. Undeclared, those handoffs are where an agent invents a variable name or reads a stale value. Declare them in a Variable | Set-by | Consumed-by table in the relevant doc:

Variable            | Set-by                     | Consumed-by
------------------------------------------------------------------------
BUILD_ID            | step 1 (scaffold)          | step 3 (deploy), step 5
ARTIFACT_PATH       | step 2 (build)             | step 3 (deploy)
REVIEW_VERDICT      | review skill               | merge skill

• One row per value that crosses a boundary. If a value never leaves the step that made it, it does not belong here.
• Name the producer and every consumer. A value with a producer and no consumer is dead; a value consumed with no declared producer is a guess waiting to happen.

5. Skill invocation order, mode guards, and troubleshooting

Skills that run in the wrong order or the wrong state cause the most confusing failures. Make the intended order explicit and linear:

scaffold -> build -> review -> integrate -> verify -> ship
   |          |         |          |           |        |
   plan     source    findings   merged      driven   tagged

Then give each skill a mode guard: a one-line precondition it checks before doing anything, so it refuses to run in a state it cannot handle.

Skill        | Runs only when                    | Refuses / warns when
----------------------------------------------------------------------------
build        | a plan exists                      | no plan on disk
review       | a diff exists                      | working tree clean
integrate    | review verdict == pass             | verdict missing/failed
verify       | change touches runtime surface     | docs/tests-only diff

Pair the order diagram with a symptom-driven troubleshooting table so an agent can self-diagnose instead of thrashing:

Symptom                          | Likely cause                 | Remedy
----------------------------------------------------------------------------
Skill exits "nothing to do"      | ran before its input existed | run prior step
Agent edits the wrong area       | skipped the routing table    | re-read section 3
Value read is stale/empty        | undeclared handoff           | add to section 4
Two docs disagree                | no source of truth honored   | see section 6

6. Designate one source of truth; wire in anti-hallucination

Every tree needs exactly one doc named as ground truth -- the doc that wins when two docs disagree. Declare it explicitly (in the entry doc and in setup.yaml), because an undeclared conflict is resolved by whichever doc the agent happened to read last.

Source of truth: docs/ground-truth.md
On any conflict between docs, docs/ground-truth.md wins. Fix the other doc;
do not silently follow the loser.

Wire an anti-hallucination directive into the agent preflight (it belongs in the shared footer from section 2, so every tool inherits it):

When you are uncertain about a name, path, value, or behavior: ask, read, or reference the source -- do not guess. A guessed field name or file path is the dominant failure mode; one verified read costs less than one wrong change.

Uncertain means: you cannot point at the doc, schema, or code line that backs the claim. That is a stop-and-read signal, not a proceed-and-hope one.

7. Golden path: "add a feature"

Give newcomers (human or agent) one ordered recipe that names real exemplar files, so the first change follows the grain of the repo instead of reinventing it. Point at named files, not abstractions:

1. Read docs/setup.md; get the dev loop green before changing anything.
2. Find the feature area in examples/setup.yaml (source-path -> domain map) and open its docs/domains/<area>.md.
3. Copy the nearest exemplar -- e.g. src/features/<exemplar>.* and its test test/features/<exemplar>_test.* -- and adapt it.
4. Run the mode-guarded skills in order (section 5): build -> review -> verify.
5. Update the handoff table (section 4) if your change introduces a cross-step value.
6. If your change encodes a new rule or hazard, write it up as a guide using the template in section 8.

Keep the exemplar filenames current. A golden path that points at a deleted file is worse than none.

8. Authoring template for a new safety or domain guide

New guides drift into ad-hoc shapes unless they share one. This shape is the transferable value: it turns a one-off incident into reusable, checkable guidance. Use it verbatim for any docs/guides/<topic>.md.

# <Guide title>

## Incident
The real event that motivates this guide. Concrete: what happened, what
broke, what it cost. No hypotheticals -- a guide with no incident is an
opinion.

## Principle
The one general rule extracted from the incident. One or two sentences an
agent can hold in its head.

## Detection
How to recognize you are in the hazard zone -- the signal, grep, symptom,
or state that says "this rule applies right now."

## Protocol
The step-by-step safe procedure. Numbered, ordered, each step checkable.
This is what the agent actually does.

## Agent anti-patterns
The specific wrong moves an agent makes here -- guessing a name, skipping a
read, running a skill out of order. Name them so they can be avoided.

## Worked example
One end-to-end pass through the protocol on a real case, showing the inputs
and the correct outputs.

## Checklist
- [ ] Mechanically checkable item
- [ ] ...
Every item is verifiable. If you cannot check it, rewrite it until you can.

Section order matters: incident earns the principle, principle drives detection, detection triggers the protocol, and the checklist makes the whole thing enforceable. Drop a section and the guide loses the link that makes it trustworthy.

Checklist

• Entry doc is one screen and links out; no inlined setup or walkthroughs.
• One rules.md; the AI footer is byte-identical across entry files.
• CI fails on any divergence between the footer copies.
• Entry doc opens with a STOP-gate and a "what you need -> which doc" routing table.
• Multi-step work has a Variable | Set-by | Consumed-by handoff table.
• Skill order is drawn linearly; each skill has a mode guard.
• A symptom -> cause -> remedy troubleshooting table exists.
• Exactly one doc is named as source of truth, in the doc and in setup.yaml.
• The anti-hallucination directive ("ask/read/reference -- do not guess") is in the shared footer.
• A golden-path "add a feature" recipe points at named exemplar files.
• New guides follow the section-8 template.
• examples/setup.yaml reflects the current entry-doc path, rulebook path, source-path-to-domain routing, and skill order.