amicus 0.1.0__tar.gz

amicus-0.1.0/.agents/skills/agent-friendly-docs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: agent-friendly-docs
+description: Use when designing, structuring, auditing, or reviewing the documentation surface of a repository that AI coding agents read while working — instruction files, README, docs/, ADRs, per-directory context files, and code-adjacent comments. Symptoms include agents re-deriving project context every session, reading stale or wrong docs, instruction files bloated with reference material, README token bloat, ADRs mistaken for current policy, embedded commands that fail as written, duplicated content drifting apart, and repo-wide context trapped in code comments. Covers layering and placement, discoverability and read paths, one authoritative home per fact, token economy, freshness mechanisms, and runnable examples. Not for published docs sites or llms.txt, generic prose quality, GitHub repo safety configuration, or rules-vs-context audits of instruction-file content.
+---
+
+# Agent-Friendly Docs
+
+Use this skill to make a repo's documentation surface cheap for agents to navigate and trust.
+
+## Core Standard
+
+The checks that decide a pass or a finding live in [docs-checklist.md](references/docs-checklist.md), one per section.
+This list names what each section is about so you can pick one; it is a map, not a second copy of the rules.
+Read the section before you apply it, and where this list and the checklist read differently, the checklist wins.
+
+- **Layer Placement** — which layer each doc belongs to, and when a straddling section is split out.
+- **Discoverability And Read Path**, **Task-To-Doc Routing** — whether an agent reaches the right doc by following links, per task.
+- **Authority And Precedence** — one home per claim that could diverge, and what resolves a conflict.
+- **Canonical Claim Validation** — whether the authoritative doc is true, checked against the code rather than against another doc.
+- **Token Economy** — what earns a place in the always-loaded layer.
+- **Freshness Mechanisms**, **Generated-Doc Provenance**, **ADR Status And Supersession** — what keeps a doc correct, marks a generated one, and separates a live decision from a superseded one.
+- **Runnable Examples And Commands** — whether an embedded command runs as written.
+- **Comment-Vs-Doc Placement** — which constraints travel with the code and which need a doc.
+
+## When To Use
+
+- Designing or restructuring a repo's documentation surface.
+- Auditing an existing documentation surface for agent-friendliness.
+- Diagnosing a concrete agent failure: missing project conventions, reading stale docs, re-deriving context every session.
+
+## When Not To Use
+
+- Published documentation sites or llms.txt — this skill covers repo-internal docs only.
+- Generic prose quality or writing style with no agent-consumption angle.
+- Instruction-file strategy and repo safety configuration — use agent-friendly-github.
+- Rules-vs-context content audits of instruction-file prose — use separating-context-from-constraints.
+- Trivial edits to a doc surface that is already well-layered; just make the edit.
+
+## Vocabulary
+
+- **Instruction layer** — always-loaded binding norms: the canonical instruction file plus thin per-harness adapters.
+  Adapter strategy itself is owned by agent-friendly-github, not this skill.
+- **Orientation layer** — read-on-demand maps: README, architecture overviews, CONTEXT.md, per-directory context files.
+  Loaded when an agent orients itself, not on every turn.
+- **Reference layer** — detailed how-to and API material, loaded only when a task demands it.
+  Kept out of the instruction layer precisely because it is heavy.
+- **Decision history** — ADRs and postmortems that explain why a past choice was made.
+  Never binds unless promoted into a current-policy doc.
+- **Code-adjacent context** — comments and docstrings carrying constraints that must travel with the code.
+  Repo-wide context does not belong here even when it is convenient to write.
+- **Canonical instruction file** — the one instruction file a harness reads directly.
+  Other harnesses point at it through a thin adapter instead of duplicating it.
+- **Per-harness adapter** — a thin, harness-specific file that points at the canonical instruction file instead of restating it.
+- **Read path** — the sequence of docs an agent loads, in order, to complete a given task.
+- **Authoritative vs historical** — whether a doc states current policy or merely records a past decision.
+- **Generated-doc provenance** — a marker on a generated file naming its source and regeneration command.
+- These layers are a routing lens for "what does an agent read first, what is authoritative, what is historical, what is ignorable" — not a filing system every repo must adopt.
+
+## Workflow
+
+1. Identify the audience: repo owner, who can restructure, versus contributor or agent operator, who works within what exists.
+   Audience decides what to lead with.
+   Where the user does not say and the repo gives no ownership signal, assume the repo owner, state that assumption, and mark each owner-only remediation as such.
+2. Classify the task: design/restructure, audit of an existing surface, or diagnosis of a concrete failure.
+3. For design or restructure, follow [design-workflow.md](references/design-workflow.md); for audit or diagnosis, follow [review-workflow.md](references/review-workflow.md).
+4. Design tasks and audits walk [docs-checklist.md](references/docs-checklist.md) as the shared standard; a diagnosis names only the sections its failure touches and produces no coverage table.
+5. Delegate instruction-file strategy questions to agent-friendly-github.
+   Delegate rules-vs-context content audits of instruction-layer docs to separating-context-from-constraints.
+   That skill counts as available when it is loaded in the current session.
+   When it is not loaded, apply one screening question — does this sentence bind behavior or just inform it? — label the result provisional, and recommend a full audit with that skill.
+6. Use [examples.md](references/examples.md) for concrete shapes.
+
+## Done Criteria
+
+Before declaring done, read the relevant workflow, then apply the criteria for your task type below.
+Only design tasks and audits walk [docs-checklist.md](references/docs-checklist.md) section by section.
+
+- **Design tasks**: every checklist section is answered in the produced structure or explicitly marked not-applicable with a one-line justification.
+- **Review tasks**: every checklist section is covered by a finding, marked OK with brief evidence, or noted not-checked with reason.
+- **Diagnosis tasks**: the response names the most likely failure path, leads with the immediate mitigation, and separates it from owner-side restructuring.
+  No checklist walk and no coverage table — naming the one or two sections the failure falls under is the whole of the checklist's role here.

amicus-0.1.0/.agents/skills/agent-friendly-docs/references/design-workflow.md

@@ -0,0 +1,82 @@
+# Design Workflow
+
+Use this workflow when creating a new documentation surface, redesigning an existing one, or bringing an under-documented repo up to standard for agents to navigate.
+
+## 1. Inventory
+
+List the tracked docs that can change what an agent does on a task.
+
+- Instruction files, wherever the harness in use looks for them.
+- README and any docs/ directory content.
+- Contribution, testing, and release guides.
+- ADRs and other decision-history material.
+- Per-directory context files, if the repo uses that pattern.
+- Doc-comments and docstrings that carry repo-wide claims, not just code-adjacent ones.
+
+Record what you excluded and why: vendored trees, generated internals, dependency docs, and code comments that carry only file-local constraints.
+An inventory with no stated boundary reads as complete when it is not.
+Walk the repo tree rather than trusting memory or a stale index.
+A doc that isn't in the inventory can't be assigned a layer, linked from an entry point, or checked for staleness later.
+
+## 2. Assign Layers
+
+Give each inventoried doc one primary layer: instruction, orientation, reference, decision history, or code-adjacent context.
+Layer definitions live in SKILL.md Vocabulary; this stage only places docs, it doesn't redefine the layers.
+
+- A doc that reads as two layers at once — most often an instruction file carrying reference-depth material — gets its straddling section named here, and split only against the tests in docs-checklist.md Layer Placement.
+- Reference-depth material found in the instruction layer is a Token Economy problem: flag it now, move it behind a pointer when you consolidate authority.
+- A repo-wide claim sitting only in a code comment is a Comment-Vs-Doc Placement problem: give the fact a doc-level authoritative home and reduce the comment to a pointer to that doc, or to a narrowly code-local note — not a retained repo-wide copy.
+
+Record every straddling or misplaced doc as you go; later stages resolve the split, this stage only finds it.
+
+## 3. Define Read Paths
+
+For the repo's three to five most common tasks, write the ordered list of docs an agent should load to complete each one.
+
+Derive the task list from the repo rather than assuming it: CI job names, Makefile or justfile targets, the section headings in a contribution guide, and the titles of recent pull requests.
+Where none of those sources gives a task list, state the three tasks you assumed and mark them as an assumption the repo owner should confirm.
+
+- Name each read path explicitly; "the agent will find it" is not a read path.
+- Wire every entry point (README, instruction file) to link to the first doc in each read path.
+- Confirm every doc in a read path is reachable by following links, not by knowing its location in advance.
+
+This stage produces Discoverability And Read Path and Task-To-Doc Routing: an entry point that names or links to the read path for each common task, and no orphaned docs.
+
+## 4. Consolidate Authority
+
+For each in-scope claim (see docs-checklist.md Authority And Precedence) that appears in more than one doc, pick one authoritative home and replace every other copy with a link to it.
+
+Find the copies rather than recalling them: search the doc set for the distinctive strings that carry claims — command names, version numbers, thresholds, directory paths — instead of comparing docs sentence by sentence.
+State the scope you searched; mark docs you did not search `not-checked` with the reason.
+
+- Where two docs could plausibly conflict despite consolidation, record a stated precedence order that resolves which one wins.
+- Decision history is never itself the authoritative home for current policy: if an ADR's content is still binding, promote it into a current-policy doc and link the ADR forward to that doc.
+
+This stage produces Authority And Precedence.
+
+## 5. Set Maintenance Mechanisms
+
+Freshness is a mechanism, not a claim, so give each doc one.
+
+Apply the checks in docs-checklist.md Freshness Mechanisms, Generated-Doc Provenance, and ADR Status And Supersession, and record the mechanism you chose for each doc.
+This stage adds no rules of its own; read them from the checklist so that a later change to the standard reaches this stage as well.
+
+Pick mechanisms that someone or something enforces.
+A mechanism nobody runs and no gate checks is a claim wearing a mechanism's clothes.
+
+## 6. Checklist Walk
+
+Walk every section of docs-checklist.md against the structure you designed: Layer Placement, Discoverability And Read Path, Task-To-Doc Routing, Authority And Precedence, Canonical Claim Validation, Token Economy, Freshness Mechanisms, Runnable Examples And Commands, Comment-Vs-Doc Placement, Generated-Doc Provenance, and ADR Status And Supersession.
+
+Design Done Criteria: every section is answered in the produced structure, or is explicitly marked not applicable with a one-line justification.
+A section with no answer and no justification is unfinished work, not a pass.
+
+Two sections deserve a fresh look here even where earlier stages already touched them: Token Economy and Runnable Examples And Commands.
+Re-run their checks from docs-checklist.md against the finished structure rather than trusting earlier-stage answers; a design pass tends to accumulate exactly the convenience additions and unstated preconditions those two sections check for.
+
+## Delegate, Don't Restate
+
+- Instruction-file strategy — canonical instruction file choice, per-harness adapter mechanics — routes to agent-friendly-github.
+- Content audits of instruction-layer prose — whether a given sentence binds behavior or merely informs it — route to separating-context-from-constraints.
+
+Apply those skills' answers directly; this workflow does not re-derive them.

amicus-0.1.0/.agents/skills/agent-friendly-docs/references/docs-checklist.md

@@ -0,0 +1,113 @@
+# Docs Checklist
+
+Use this as the detailed standard for both design and review tasks.
+
+## Layer Placement
+
+- Every doc is assigned exactly one primary layer: instruction, orientation, reference, decision history, or code-adjacent context.
+- Every section whose loading cost, authority, or lifecycle differs from its doc's primary layer is named.
+- A named section is split out only when the audit can state the evidence for one of three tests.
+  Loading: name a task on the repo's common-task list that loads the doc and never needs that section.
+  Authority: name a second doc that states the same claim, so which one governs is open.
+  Lifecycle: name a distinct owner, generator, or change trigger for the section.
+- A section that meets none of the three tests stays where it is.
+  A short quick-start command inside an orientation README meets none of them.
+- The instruction layer carries binding norms and pointers only, not reference-depth material.
+- Decision history is labeled historical, not current policy.
+
+Layer names and definitions live in SKILL.md Vocabulary; this section only checks that every doc has been placed in one of them.
+A doc that straddles two layers is a signal to name the straddling section, then to split it only when one of the three tests above is met.
+Splitting on sight fragments a usable doc into many small ones and raises navigation cost.
+Whether a given sentence in the instruction layer is a binding norm or merely informative context is a separating-context-from-constraints question, not one this checklist re-derives; see SKILL.md Workflow for when to apply that skill and what to do when it is not loaded.
+Canonical-instruction-file and per-harness-adapter strategy is owned by agent-friendly-github; this section checks placement only, not adapter mechanics.
+
+## Discoverability And Read Path
+
+- Every instruction, orientation, reference, and decision-history doc is reachable by links from at least one entry point (README or an instruction file).
+- An agent orienting itself can reach the doc that answers a given question by following links, without reading unrelated docs first.
+- No doc in those layers is orphaned: reachable only by knowing its path in advance.
+- Code-adjacent comments and generated internals are exempt from the link requirement, and the audit states that exemption rather than reporting them as orphans.
+
+Entry points carry the map; a doc that no entry point links to is found only by search, and an agent that does not know it exists does not search for it.
+
+## Task-To-Doc Routing
+
+- Each of the repo's common tasks (add a feature, fix a bug, run tests, cut a release) has an identifiable read path: a named sequence of docs to load.
+- The entry point names that read path, or names where to find it, for each common task.
+- A read path can be completed by following links; it does not require guessing which file is relevant.
+
+This is Discoverability And Read Path applied to specific, recurring tasks rather than to an arbitrary question.
+
+## Authority And Precedence
+
+- Every normative or operational claim has exactly one authoritative home.
+  A claim is in scope when two copies of it could diverge and change what an agent does: commands, versions, thresholds, paths, ownership, conventions, policy statements, and current-state descriptions of architecture or deployment.
+  Out of scope: names, quotations, historical statements, and explanatory background that cannot change an action.
+  Prose role does not decide this — a current-state fact written as background is in scope, because an agent implements against it.
+- Every other mention of an in-scope claim is a link to the authoritative home, not a restatement.
+- Every generated mirror or quotation of an in-scope claim is marked as non-authoritative, so it is not read as a second home.
+- Where two docs stating in-scope claims can conflict, a stated precedence order resolves which one wins.
+
+Duplication is the symptom; the fix is a link, not a rewrite in both places.
+
+## Canonical Claim Validation
+
+- Every command, version, path, and current-state claim in an authoritative doc is checked against the source that implements it: the code, CI configuration, build files, manifests, or schema.
+- No claim is marked `OK` because no other doc contradicts it.
+- Every claim that cannot be checked against a source is marked `not-checked` with the reason.
+- Where the repo is too large to check every claim, the sampling boundary is stated.
+
+Authority And Precedence finds two docs that disagree; it cannot find one doc that is uniformly wrong.
+A single stale command with no competitor passes every other section in this checklist, and an agent runs it with full confidence.
+
+## Token Economy
+
+- Every procedure or reference statement in the instruction layer applies to every task in the repo's common-task list.
+  A procedure that fewer tasks need moves behind a pointer, and the pointer stays.
+- A routing pointer is exempt from the rule above: a one-line pointer that names a task and the doc it routes to belongs in the instruction layer even when only one task needs it.
+  Pointers are what make the layer small; the rule removes procedures, not routes.
+- The instruction layer carries pointers, not procedures, for anything an agent can complete a common task without.
+- No bulk content is duplicated across layers (e.g., reference material copied into the instruction file for convenience).
+- Every orientation-layer doc that carries reference or historical material — full API detail, changelogs — moves that material behind a pointer to its own layer.
+
+Every always-loaded token is a token spent on every single turn; the instruction layer's size is a standing cost, not a one-time one.
+
+## Freshness Mechanisms
+
+- Each doc (or the section of the repo it covers) has a named owner or owning team.
+- PRs that change behavior a doc describes carry a stated expectation to update that doc.
+- No doc claims freshness by timestamp or "last updated" date alone, without a mechanism that keeps it true.
+
+A timestamp records when a doc was last touched, not whether it is still correct; ownership and PR expectations are what keep it correct.
+
+## Runnable Examples And Commands
+
+- Every embedded command runs as written from the repo root, or the doc states the precondition needed to run it (working directory, environment variable, prior setup step).
+- Every path referenced in an example resolves from the stated starting point.
+- No example depends on unstated state (an unmentioned file, an unmentioned prior command) to succeed.
+
+An agent will copy-paste the example as written; if it doesn't run, the doc has failed at its one job.
+
+## Comment-Vs-Doc Placement
+
+- Constraints coupled to a specific piece of code (why this line is guarded, why this default was chosen) live in a comment or docstring next to that code.
+- Repo-wide context (architecture, conventions, cross-cutting policy) never hides in a code comment where only a reader of that one file will see it.
+- Where a comment states a repo-wide fact, that fact also has an authoritative home in a doc, per Authority And Precedence.
+
+Code-adjacent context travels with the code by design; repo-wide context needs to be found without first finding the code.
+
+## Generated-Doc Provenance
+
+- Every generated doc is marked as generated.
+- Every generated doc names its source (the file, script, or tool that produces it).
+- Every generated doc gives the regeneration command.
+
+An agent that doesn't know a doc is generated will edit it directly and lose the edit on the next regeneration.
+
+## ADR Status And Supersession
+
+- Every ADR carries a status (e.g., proposed, accepted, superseded, rejected).
+- Every superseded ADR links forward to the ADR or doc that superseded it.
+- No ADR is treated as binding current policy unless its content has been promoted into a current-policy doc; ADRs are decision history by default, per SKILL.md Vocabulary.
+
+Status and forward links are what let an agent tell a decision that is in force from a superseded decision, without reading the whole history.

amicus-0.1.0/.agents/skills/agent-friendly-docs/references/examples.md

@@ -0,0 +1,194 @@
+# Examples
+
+Worked shapes for a fictional small repo, `lighthouse` (a billing service), and a fictional monorepo, `orbit` (an API package plus a web package).
+Use these as concrete shapes to mimic; cross-reference [docs-checklist.md](docs-checklist.md) for the rules they instantiate and [SKILL.md](../SKILL.md) Vocabulary for the layer names used in the annotations below.
+
+## 1. Layered small-repo layout
+
+`lighthouse` is small enough to fit every layer in one tree.
+Each entry below is annotated with the layer it belongs to, per SKILL.md Vocabulary.
+
+```
+lighthouse/
+├── AGENTS.md                    # instruction layer — canonical, always loaded
+├── CLAUDE.md                    # instruction layer — per-harness adapter, points at AGENTS.md
+├── README.md                    # orientation layer — entry point and map
+├── docs/
+│   ├── architecture.md          # orientation layer — system map, read when orienting
+│   ├── api-reference.md         # reference layer — loaded only when a task touches the API
+│   └── testing.md               # reference layer — loaded only when running or writing tests
+├── adr/
+│   ├── 0001-use-postgres.md               # decision history — why, not current policy
+│   ├── 0002-async-job-queue.md            # decision history — superseded by 0003 (see section 4)
+│   └── 0003-replace-rabbitmq-with-kafka.md # decision history — supersedes 0002
+└── src/
+    └── billing/
+        └── invoice.py           # code-adjacent context — comments here carry constraints coupled to this file, not repo-wide claims
+```
+
+Two things this layout makes visible at a glance:
+
+- Nothing in `docs/` is always-loaded; an agent reaches `api-reference.md` or `testing.md` only by following a link from `README.md` or `AGENTS.md` when the task calls for it.
+- `adr/` sits outside both the instruction and orientation layers; an agent that finds an ADR by search rather than by link reads its status line first, and does not treat its decision as current policy (see section 4 below).
+
+## 2. Monorepo layout with nested context files
+
+`orbit` has two packages with different toolchains, so the instruction layer splits: a root file for cross-cutting norms and a nested file per package for what differs.
+
+```
+orbit/
+├── AGENTS.md                     # instruction layer — root: cross-cutting norms only (commit format, PR conventions, shared CI gate)
+├── CLAUDE.md                     # instruction layer — root adapter, points at AGENTS.md
+├── README.md                     # orientation layer — root map, links to each package's README
+├── docs/
+│   └── architecture.md           # orientation layer — cross-package system map, root only
+├── packages/
+│   ├── api/
+│   │   ├── AGENTS.md             # instruction layer — package-scoped: Go toolchain, `go test ./...`, owns packages/api/
+│   │   ├── README.md             # orientation layer — package map
+│   │   └── ...
+│   └── web/
+│       ├── AGENTS.md             # instruction layer — package-scoped: pnpm toolchain, `pnpm test`, owns packages/web/
+│       ├── README.md             # orientation layer — package map
+│       └── ...
+```
+
+What belongs at which level: cross-cutting norms (commit format, review expectations, the label taxonomy) live only in the root `AGENTS.md`; anything that differs by package — build command, test command, ownership, off-limits paths — lives in that package's nested `AGENTS.md` and overrides the root only where it differs.
+An agent working in `packages/api/` reads both files: the root file for what's always true, the nested file for what's true here.
+
+This example shows the resulting shape only.
+The strategy question — why nest per-package instruction files at all, and how the `CLAUDE.md` adapter mechanics work — is owned by the agent-friendly-github skill's Agent-Instruction-File Strategy section; this skill does not restate those rules.
+
+## 3. README de-bloat before/after
+
+`lighthouse`'s `README.md` started as the only doc anyone wrote, so it accumulated reference-layer weight: a full endpoint-by-endpoint API reference sitting inside an orientation-layer doc.
+
+**Before** (excerpt — the full file ran to roughly 2,400 words, most of it API detail):
+
+````markdown
+# lighthouse
+
+A billing service.
+
+## Setup
+
+...
+
+## API
+
+### GET /invoices
+
+Returns a paginated list of invoices. Query params: `status`, `cursor`, `limit`.
+
+Response:
+```json
+{"items": [...], "next_cursor": "...", "has_more": true}
+```
+
+### POST /invoices
+
+Creates an invoice. Body: `{"customer_id": "...", "line_items": [...]}`.
+
+Response:
+```json
+{"id": "inv_123", "status": "draft", ...}
+```
+
+### PATCH /invoices/:id
+
+... (12 more endpoints follow, each with request/response bodies)
+````
+
+**After** — the API detail moves to `docs/api-reference.md`; `README.md` keeps only what every task needs to orient, plus a pointer:
+
+```markdown
+# lighthouse
+
+A billing service.
+
+## Setup
+
+...
+
+## API
+
+Full endpoint reference: [docs/api-reference.md](docs/api-reference.md).
+Load it only when a task touches the API surface directly.
+```
+
+Token-cost rationale: before the split, `README.md` was loaded on every orientation pass at roughly 2,400 words, even for tasks — fixing a typo, updating a test — that never touch the API.
+After the split, `README.md` is roughly 400 words; the 2,000 words of endpoint detail sit behind an explicit link in `docs/api-reference.md`, loaded only when a task actually needs it.
+The fact didn't move to a worse home — it moved to the layer that matches how often an agent actually needs it.
+
+## 4. ADR header with status and supersession
+
+`lighthouse` chose RabbitMQ for its async job queue in ADR 0002, then replaced it with Kafka in ADR 0003.
+Both headers carry a `Status` line an agent can read before the surrounding prose.
+
+`adr/0002-async-job-queue.md`:
+
+```markdown
+# ADR 0002: Use RabbitMQ for the async job queue
+
+Status: Superseded by [ADR 0003](0003-replace-rabbitmq-with-kafka.md)
+
+## Context
+
+...
+```
+
+`adr/0003-replace-rabbitmq-with-kafka.md`:
+
+```markdown
+# ADR 0003: Replace RabbitMQ with Kafka for the async job queue
+
+Status: Accepted
+Supersedes: [ADR 0002](0002-async-job-queue.md)
+
+## Context
+
+...
+```
+
+How an agent should read this: on opening `0002-async-job-queue.md`, the `Status` line is the first fact after the title, before any context or rationale prose.
+`Superseded by` means the decision in this ADR is historical, not current policy.
+The agent follows the forward link to `0003-replace-rabbitmq-with-kafka.md` to find which decision replaced it.
+`Status: Accepted` on 0003 tells the agent that this ADR is the current record of the decision — it does not by itself make the ADR current policy.
+Per SKILL.md Vocabulary, an ADR binds only after its content is promoted into a current-policy doc, so the agent reads `docs/architecture.md` for the policy and uses 0003 only for the reason behind it.
+If no current-policy doc states the Kafka choice, that is a finding: the decision was never promoted, and every agent must re-derive current policy from decision history.
+If a current-policy doc still describes RabbitMQ, that is also a finding — the promotion never happened when the decision changed.
+
+## 5. PR doc-update convention
+
+Freshness in `lighthouse` uses two mechanisms: a PR template line that prompts the doc update, and a CODEOWNERS line that routes doc changes to a reviewer.
+
+`.github/pull_request_template.md` (excerpt):
+
+```markdown
+## Checklist
+
+- [ ] Updated the doc that describes this behavior (README, `docs/`, or the relevant `AGENTS.md`), or marked N/A with a one-line reason.
+- [ ] Tests pass locally (`pytest`).
+```
+
+`CODEOWNERS` (excerpt):
+
+```
+docs/       @lighthouse-org/docs-owners
+AGENTS.md   @lighthouse-org/docs-owners
+adr/        @lighthouse-org/docs-owners
+```
+
+The checklist line makes the expectation visible on every PR, but the line does not enforce the update.
+CODEOWNERS requests a review only for the paths a PR changes, so these doc-path rules do nothing on a PR that changes behavior in `src/` and touches no doc.
+The doc-path rules catch a bad edit to a doc; they do not catch a missing one.
+Adding the source paths to CODEOWNERS does not enforce the update either, because a code owner can approve a source-only PR that changes no doc.
+Source-path ownership buys routing, not enforcement: the PR reaches a reviewer who is accountable for the doc and can ask for the update.
+Only a required check that tests for the doc change can fail the PR, and that check is the difference between a prompt and a gate.
+Ownership rules and required checks are owned by agent-friendly-github; this example only states which mechanism catches which failure.
+
+## 6. Harness adapters
+
+Adapter mechanics — which file each harness reads, the include or reference syntax it supports, and what to do when it supports none — are owned by the agent-friendly-github skill's Agent-Instruction-File Strategy section.
+Apply that skill directly; this skill states no harness-specific syntax anywhere, because a copy here would age out of step with the authoritative rule and nothing would fail when it did.
+For doc-surface design, the only fact this skill needs is the shape shown in sections 1 and 2: one canonical instruction file, with per-harness files as adapters that point at it.

amicus-0.1.0/.agents/skills/agent-friendly-docs/references/review-workflow.md

@@ -0,0 +1,91 @@
+# Review Workflow
+
+Use this workflow when auditing an existing documentation surface or diagnosing a concrete agent failure.
+
+## 1. Route Audit Vs Diagnosis
+
+If the user reports a concrete failure — an agent missed a convention, read a stale doc, or re-derived context it should have found — start in diagnosis mode.
+
+Diagnosis mode is the whole workflow for that request, not its first stage.
+Produce these four things and stop:
+
+- name the most likely failure path: which doc the agent should have read, and why it didn't
+- lead with the smallest caller-side mitigation that unblocks the agent today (a pointer, a link, a reminder in the task prompt), stated before any restructuring
+- separate that from the owner-side restructuring that fixes the surface itself
+- if confirming the hypothesis needs reading a doc the caller hasn't shared, ask before assuming its contents
+
+In diagnosis mode, do not walk the checklist, do not produce a coverage table, and do not open sections the reported failure does not touch.
+Sections 2 to 6 below are for audits only.
+A diagnosis answered with a full section-by-section audit buries the one fix the user needs today, and charges them for ten sections of a surface they did not ask about.
+Use the checklist only to name which section the failure falls under, in a few words.
+
+Only when the user asks for a general audit of the documentation surface, continue with the full workflow below.
+
+## 2. Establish Evidence
+
+Prefer direct evidence over inferred behavior.
+
+Label each piece of evidence within a finding as one of:
+
+- `observed` — you read the doc, followed the link, or ran the command yourself
+- `inferred` — deduced from related material without reading the doc directly
+- `absence-of-evidence` — a required piece is missing: no read path for a core task, no owner named, no regeneration command on a generated doc
+
+Absence of a required piece is itself a finding, not a gap to note and move past.
+
+Read the repo's actual doc tree rather than trusting an index or a prior summary of it; a doc that moved or was deleted since the index was written produces a false `OK`.
+
+Two checks are never satisfied by reading alone:
+
+- **Runnable Examples And Commands.** Run each embedded command from the working directory the doc states, in a checkout you can execute.
+  Where you cannot execute, resolve every path, file, and directory the command names against the repo tree, and label the result `inferred` with the unresolved parts named.
+  Never mark this section `OK` from a command that only looks correct.
+- **Canonical Claim Validation.** Check the claim against the source that implements it, not against another doc.
+
+A command that reads as plausible and a command that runs are different findings; only one of them is evidence.
+
+## 3. Walk The Checklist
+
+Walk every section of [docs-checklist.md](docs-checklist.md) in order: Layer Placement, Discoverability And Read Path, Task-To-Doc Routing, Authority And Precedence, Canonical Claim Validation, Token Economy, Freshness Mechanisms, Runnable Examples And Commands, Comment-Vs-Doc Placement, Generated-Doc Provenance, and ADR Status And Supersession.
+
+For each section, produce at least one of:
+
+- a finding (see Finding Format below)
+- `OK` with the brief evidence that grounds it (the doc, link, or command you checked)
+- `not-checked` with the reason (out of scope, no access, not applicable to this repo)
+
+A section with no finding, no `OK`, and no `not-checked` reason is unfinished work, not a pass.
+Cite the checklist's own checks by section name rather than restating them; this workflow does not re-derive what docs-checklist.md already defines.
+
+## 4. Severity Scale
+
+Assign severity by what the finding changes, and decide it in this order:
+
+- `blocking` — the evidence shows an agent can produce a wrong result: it edits the wrong file, runs a command that fails or does the wrong thing, or follows a superseded decision as current policy.
+  Authority conflicts between two docs belong here.
+- `degrading` — the agent still reaches the correct result, but pays an avoidable cost to get there: token bloat in the instruction layer, a missing read path that forces rediscovery, context buried where the agent finds it late.
+- `polish` — neither cost is demonstrable from the evidence you hold: inconsistent terminology, a link that could be one hop shorter, formatting noise.
+
+Apply the first tier whose test the evidence satisfies.
+Where the evidence supports two tiers, assign the higher one and state the doubt in the impact line.
+Never lower a severity because the fix is large; effort belongs in remediation, not in severity.
+
+## 5. Finding Format
+
+Each finding includes:
+
+- severity: `blocking`, `degrading`, or `polish`
+- checklist section: the docs-checklist.md section it violates
+- location: file and section cited
+- evidence labels: one per evidence item — `observed`, `inferred`, or `absence-of-evidence`
+- impact: one line, stated in terms of what an agent does wrong or pays for
+- remediation: the smallest fix first, with a larger restructuring noted separately if one is warranted
+
+## 6. Report Format
+
+Order the report as:
+
+1. Findings, ordered by severity (`blocking` first, then `degrading`, then `polish`).
+2. The section-by-section coverage table produced in Walk The Checklist: every docs-checklist.md section marked with a finding reference, `OK`, or `not-checked`.
+
+When no findings surface, state that explicitly and name any section left `not-checked` and why.