@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-ui-ops/references/standards/agents-md-spec.md

@@ -1,138 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - claude-md-convention.md
-  - cross-tool-matrix.md
-primary_sources:
-  - https://agents.md — canonical home of the spec
-  - https://openai.com/index/agentic-ai-foundation/ — Agentic AI Foundation announcement (Dec 2025)
-  - https://techcrunch.com/2025/12/09/openai-anthropic-and-block-join-new-linux-foundation-effort-to-standardize-the-ai-agent-era/
-  - https://developers.openai.com/codex/guides/agents-md
-  - https://docs.devin.ai/onboard-devin/agents-md
-  - https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
-  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
-status: research-verified
----
-
-# AGENTS.md — the canonical entry-file standard
-
-## What AGENTS.md is
-
-`AGENTS.md` is a Markdown file at the repo root that instructs an LLM coding agent on how to work in the repo. The format **emerged August 2025** out of a working group of OpenAI Codex, Amp (Sourcegraph), Jules (Google), Cursor, and Factory. As of **December 2025 it is stewarded by the Agentic AI Foundation (AAIF) under the Linux Foundation**, alongside Anthropic, OpenAI, Block, Google, Microsoft, AWS, Bloomberg, and Cloudflare. Adoption (as of April 2026) is **60,000+ open-source projects**.
-
-Canonical home: [agents.md](https://agents.md).
-
-## What the spec actually requires
-
-**Almost nothing.** The spec is deliberately format-light — *"just standard Markdown, no required fields."* Authority is governance (AAIF/Linux Foundation steward), not schema. Any sectioning convention (e.g., "Where to find things") is **opinionated overlay**, not spec compliance.
-
-This skill recommends the structure below — but it is *our* recommendation, layered on top of a deliberately permissive spec.
-
-## Recommended structure (this skill's overlay)
-
-```markdown
-# AGENTS.md
-
-This file gives instructions to LLM coding agents (Codex, Devin, Cursor,
-Windsurf, Copilot, Aider, Continue, Jules, Junie — and Claude Code via
-symlink/pointer) working in this repo.
-
-_Last reviewed: 2026-04-27_
-
-## Project overview
-
-One paragraph: what this repo does, who uses it.
-
-## Build / test / run
-
-```bash
-pnpm install
-pnpm test
-pnpm build
-```
-
-## Conventions
-
-- TypeScript strict mode; ESM only
-- Vitest for tests; Playwright for E2E
-- Conventional Commits
-
-## Trust boundaries
-
-- DO NOT modify: `db/migrations/`, `legal/`, `LICENSE`
-- DO modify: `src/`, `tests/`, `.brain/` (with care for ADRs)
-
-## Where to find things
-
-- **Architecture:** `ARCHITECTURE.md`
-- **Active plan:** `.brain/PLAN.md`
-- **Roadmap:** `.brain/ROADMAP.md`
-- **Architecture Decision Records:** `.brain/adrs/` (see also `.brain/adrs/README.md` for the index)
-- **Post-mortems:** `.brain/postmortems/`
-- **Runbooks:** `.brain/runbooks/`
-- **Released changes:** `CHANGELOG.md`
-- **Contributor guide:** `CONTRIBUTING.md`
-
-## Memory primitives
-
-- **Before making architectural decisions**, read `.brain/adrs/` newest-first.
-- **When debugging a production issue**, search `.brain/postmortems/`.
-```
-
-The "Where to find things" section is **load-bearing for navigation** even if not strictly required by the spec. Without it, the agent sees only `AGENTS.md` and has to guess where everything else lives.
-
-## Adoption matrix (April 2026)
-
-| Tool | Reads AGENTS.md natively? | Notes |
-|---|---|---|
-| **OpenAI Codex** | **Yes** — primary | Plus `~/.codex/AGENTS.md`, `AGENTS.override.md` |
-| **Cognition Devin** | **Yes** — primary | docs.devin.ai/onboard-devin/agents-md |
-| **Cursor** | **Yes** | Plus `.cursor/rules/*.mdc` (newer) and `.cursorrules` (deprecated, still works) |
-| **Windsurf** (Cognition-owned since Dec 2025) | **Yes** | Plus `.windsurfrules`, `.windsurf/rules/` |
-| **GitHub Copilot** (coding agent + CLI) | **Yes** (added 2025-08-28) | Also reads `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md` |
-| **VS Code agent mode** | **Yes** | |
-| **Google Jules / Gemini CLI** | **Yes** | |
-| **JetBrains Junie** | **Yes** | |
-| **Sourcegraph Amp** | **Yes** | Founding member of the agents.md working group |
-| **goose, Factory, Kilo, Antigravity, OpenClaw** | **Yes** | All listed on agents.md adopters page |
-| **Aider** | Configurable via `--read CONVENTIONS.md` | Default is `CONVENTIONS.md`, AGENTS.md only via config |
-| **Continue.dev** | **Not yet** | Issue #6716 open |
-| **Claude Code** (Anthropic) | **NOT natively as of April 2026** | Issue [#31005](https://github.com/anthropics/claude-code/issues/31005) — workaround: symlink `ln -s AGENTS.md CLAUDE.md` or thin pointer file |
-
-## Why AGENTS.md vs CLAUDE.md / .cursorrules / .windsurfrules
-
-| Approach | Problem |
-|---|---|
-| `CLAUDE.md` only | Codex / Devin / Cursor / Windsurf / Copilot don't read it natively. Drift between tools. |
-| `.cursorrules` only | Other tools don't read it. Same problem inverted. |
-| One file per tool | N copies of the same content, guaranteed to drift over time. |
-| **`AGENTS.md` + thin pointers/symlinks** | One source of truth; tool-specific files are 3-line redirects (or symlinks). |
-
-## Audit checks for AGENTS.md
-
-When auditing a repo:
-
-1. **Existence** — does `AGENTS.md` exist at the repo root?
-2. **Recommended sections present** — project overview, build/test/run, conventions, trust boundaries, where-to-find-things, memory primitives. (None are spec-mandated; all are recommended for navigability.)
-3. **Pointer integrity** — does each `.brain/...` reference point to a real path?
-4. **Freshness** — `_Last reviewed:_` line or YAML frontmatter `date:` present?
-5. **Other entry files are thin pointers or symlinks** — if `CLAUDE.md` / `.cursorrules` / `.windsurfrules` exist, they should redirect to (or symlink to) `AGENTS.md`, not duplicate content. See `claude-md-convention.md`.
-6. **Length** — under ~200 lines is the ergonomic target (per Anthropic's own CLAUDE.md guidance, which ports cleanly to AGENTS.md). Long instructions degrade adherence; push detail into `.brain/` subfolders.
-
-## Common anti-patterns
-
-- **Naked AGENTS.md** — just a project overview, no `Where to find things` section. Agent has nothing to navigate to.
-- **Duplicate content** — AGENTS.md and CLAUDE.md both contain full instructions, drifted apart. Pick one canonical, make the others pointers/symlinks.
-- **Stale build commands** — `npm install` listed but project moved to pnpm a year ago. Audit catches this by comparing to `package.json` / lockfiles.
-- **No trust boundaries** — agent edits files it shouldn't (migrations, legal, generated code). Trust-boundary section prevents this.
-- **No memory primitives section** — agent doesn't know to read ADRs before architectural decisions.
-- **Bloated AGENTS.md** — 800-line instruction dump that nobody (human or agent) reads. Compress, link out.
-
-## Cross-references
-
-- CLAUDE.md as thin pointer / symlink: `claude-md-convention.md`
-- Cross-tool compatibility matrix (full): `cross-tool-matrix.md`
-- Audit checks: `../audit-patterns/entry-file-coverage.md`
-- Greenfield setup recipe: `../recipes/greenfield-setup.md`
-- LLM-doc-writing guidance: `../guidance/llm-doc-writing.md`

package/skills/adia-ui-ops/references/standards/claude-md-convention.md

@@ -1,123 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - agents-md-spec.md
-  - cross-tool-matrix.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices — Anthropic Claude Code best practices
-  - https://github.com/anthropics/claude-code/issues/31005 — request to support AGENTS.md (Apr 2026: still open, no Anthropic response)
-  - https://github.com/anthropics/claude-code/issues/6235 — parent issue (3,020 upvotes, 224 comments, 7 months open)
-  - https://www.humanlayer.dev/blog/writing-a-good-claude-md
-status: research-verified
----
-
-# CLAUDE.md — thin pointer or symlink to AGENTS.md
-
-> **The canonical pattern.** When `AGENTS.md` is present, `CLAUDE.md` should be either (a) a 3-5 line redirect, or (b) a symlink: `ln -s AGENTS.md CLAUDE.md`. The same pattern applies to `.cursor/rules/*.mdc`, `.windsurfrules`, `.github/copilot-instructions.md`.
-
-## How Claude Code actually reads CLAUDE.md
-
-Claude Code loads CLAUDE.md with this **precedence** (highest → lowest):
-
-1. **Managed enterprise policy** (org-level)
-2. **`~/.claude/CLAUDE.md`** (user global)
-3. **`./CLAUDE.md`** (project root)
-4. **`./CLAUDE.local.md`** (personal overrides, gitignored)
-
-It also walks parent directories, supports `@import` syntax, and reads `.claude/rules/` for path-scoped rules.
-
-## The load-bearing caveat — Claude Code does NOT read AGENTS.md natively
-
-As of April 2026, **Claude Code does not natively read `AGENTS.md`**. The community has been requesting this since at least September 2025; [issue #31005](https://github.com/anthropics/claude-code/issues/31005) and the parent issue #6235 (3,020 upvotes, 224 comments, 7 months open) both have **zero Anthropic response**.
-
-Two clean workarounds:
-
-**Workaround A — Symlink** (minimal repo footprint):
-
-```bash
-ln -s AGENTS.md CLAUDE.md
-git add CLAUDE.md
-```
-
-**Caveat:** symlinks across `.claude/skills/` ↔ `.agents/skills/` and similar directory pairs have known compatibility quirks; verify on the platforms you target. Windows + WSL contributors may also have issues with symlinks committed to git.
-
-**Workaround B — Thin pointer file** (the safe default):
-
-```markdown
-# CLAUDE.md
-
-This repo's instructions for LLM coding agents live in [`AGENTS.md`](./AGENTS.md).
-Please read that file. The contents apply identically to Claude Code.
-
-_Last reviewed: 2026-04-27_
-```
-
-Three to five lines. Same shape works for:
-
-```
-# .cursor/rules/instructions.mdc
-This repo's instructions live in AGENTS.md at the root. Please read it.
-```
-
-```
-# .windsurfrules
-This repo's instructions live in AGENTS.md at the root. Please read it.
-```
-
-```
-# .github/copilot-instructions.md
-This repo's instructions live in AGENTS.md at the root. Please read it.
-```
-
-(Note: GitHub Copilot already reads AGENTS.md natively, but a thin pointer here is harmless and helps consistency.)
-
-## Anthropic's own guidance for CLAUDE.md
-
-Per [Anthropic's Claude Code best practices](https://code.claude.com/docs/en/best-practices) and the widely-cited [HumanLayer post](https://www.humanlayer.dev/blog/writing-a-good-claude-md):
-
-- **Keep CLAUDE.md under ~200 lines.** Instruction quality decreases as count increases.
-- **Only universally-applicable instructions.** Path-specific rules belong in `.claude/rules/<path>/CLAUDE.md`.
-- **Prefer hooks over advisory text** for deterministic behavior — hooks always execute; CLAUDE.md text is advisory.
-- **Iterate by telling Claude to add corrections to CLAUDE.md itself.** Treat it as live, not frozen.
-
-These guidelines port cleanly to AGENTS.md — same ergonomics regardless of filename.
-
-## Anti-pattern: divergent CLAUDE.md and AGENTS.md
-
-The most common stale-docs failure: CLAUDE.md was written first, then AGENTS.md added later, and now they have drifted. Different build commands. Different conventions. Different trust boundaries.
-
-Audit signal:
-- Both files exist
-- Both are non-trivial in size (>15 lines each)
-- A diff shows substantive content differences
-
-Fix: pick one canonical (AGENTS.md), demote the other to a pointer or symlink.
-
-## Migration recipe — turning a fat CLAUDE.md into a thin pointer
-
-If you have a fat `CLAUDE.md` and no `AGENTS.md`:
-
-1. **Copy** `CLAUDE.md` → `AGENTS.md` (`cp CLAUDE.md AGENTS.md`).
-2. **Generalize the wording.** Replace "Claude Code" / "Claude" with "LLM coding agents (Claude Code, Codex, Devin, Cursor, Windsurf, etc.)".
-3. **Add a `Where to find things` section** if missing.
-4. **Trim AGENTS.md to under ~200 lines.** Push detail into `.brain/`.
-5. **Replace `CLAUDE.md`** with either a symlink (`rm CLAUDE.md && ln -s AGENTS.md CLAUDE.md`) or a thin pointer file.
-6. **Add `.cursor/rules/instructions.mdc`, `.windsurfrules`, `.github/copilot-instructions.md`** as thin pointers if those tools are used.
-7. **Commit clearly:** `docs: split CLAUDE.md → AGENTS.md (canonical) + CLAUDE.md (pointer)`.
-
-## Audit checks for CLAUDE.md
-
-1. **If `AGENTS.md` exists**, `CLAUDE.md` should be either a symlink to it OR a thin pointer (≤15 lines). Anything else is drift.
-2. **If `AGENTS.md` does not exist**, recommend creating one and demoting `CLAUDE.md` to a pointer.
-3. **If both exist as fat files**, flag as drift risk — diff them and recommend consolidation.
-4. **If `CLAUDE.md` references files that don't exist**, flag broken pointers.
-5. **CLAUDE.md > 200 lines** — flag as a length smell. Anthropic's own guidance recommends shorter.
-
-## Cross-references
-
-- AGENTS.md spec: `agents-md-spec.md`
-- Full cross-tool compatibility matrix: `cross-tool-matrix.md`
-- LLM-doc-writing guidance (length, content quality): `../guidance/llm-doc-writing.md`
-- Audit checks: `../audit-patterns/entry-file-coverage.md`
-- Migration recipe in detail: `../recipes/audit-existing-repo.md`

package/skills/adia-ui-ops/references/standards/cross-tool-matrix.md

@@ -1,85 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - agents-md-spec.md
-  - claude-md-convention.md
-primary_sources:
-  - https://agents.md — canonical adopters list
-  - https://github.com/anthropics/claude-code/issues/31005 — Claude Code AGENTS.md request
-  - https://docs.devin.ai/onboard-devin/agents-md
-  - https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
-  - https://cursor.com/docs/rules
-  - https://aider.chat/docs/usage/conventions.html
-  - https://docs.continue.dev/customize/deep-dives/rules
-  - https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
-  - https://cognition.ai/blog/windsurf — Windsurf acquisition
-status: research-verified
----
-
-# Cross-tool compatibility matrix
-
-> **The single load-bearing fact:** AGENTS.md is read natively by almost every major LLM coding agent **except Claude Code**. The skill's recommendation — AGENTS.md canonical, all others as thin pointers/symlinks — minimizes drift across this surface.
-
-## The matrix (April 2026)
-
-| Tool | Native instruction file(s) | Reads AGENTS.md natively? | Notes |
-|---|---|---|---|
-| **Claude Code** (Anthropic) | `CLAUDE.md` (+ `~/.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/`, `@import`) | **No** | Issue [#31005](https://github.com/anthropics/claude-code/issues/31005) open with no Anthropic response. Workaround: `ln -s AGENTS.md CLAUDE.md`. |
-| **OpenAI Codex** | `AGENTS.md` (+ `~/.codex/AGENTS.md`, `AGENTS.override.md`) | **Yes** — primary | Founding member of the agents.md working group. |
-| **Cognition Devin** | `AGENTS.md` | **Yes** — primary | [docs.devin.ai/onboard-devin/agents-md](https://docs.devin.ai/onboard-devin/agents-md). |
-| **Cognition Windsurf** | `.windsurfrules`, `.windsurf/rules/` | **Yes** | Cognition acquired Windsurf Dec 2025 (~$250M). |
-| **Cursor** | `.cursor/rules/*.mdc` (newer); `.cursorrules` (deprecated, still works) | **Yes** | Founding member of the agents.md working group. |
-| **GitHub Copilot** (coding agent + CLI) | `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md` | **Yes** (added 2025-08-28) | Also reads `CLAUDE.md` and `GEMINI.md`. |
-| **VS Code agent mode** | `AGENTS.md` (+ Copilot's instructions) | **Yes** | |
-| **Google Jules / Gemini CLI** | `AGENTS.md` | **Yes** | Founding member of the working group. |
-| **JetBrains Junie** | `AGENTS.md` | **Yes** | |
-| **Sourcegraph Amp** | `AGENTS.md` | **Yes** | Founding member. (Sourcegraph Cody, distinct, has no documented file convention; relies on indexed context.) |
-| **Aider** | `CONVENTIONS.md` (loaded via `--read`), `.aider.conf.yml` | **Configurable** — not auto by default | Set `read: ["AGENTS.md"]` in config to opt-in. |
-| **Continue.dev** | `config.yaml` rules; Markdown rule files in `.continue/rules/` | **Not yet native** | Issue #6716 open. |
-| **goose, Factory, Kilo, Antigravity, OpenClaw** | `AGENTS.md` | **Yes** | All listed on agents.md adopters page. |
-
-## What this means for the audit
-
-When auditing a repo:
-
-1. **AGENTS.md** is the canonical entry — it should exist and be the fat one.
-2. **For each *other* file the listed tools read natively**, check whether it exists. If it does, it should be a thin pointer or symlink to AGENTS.md, not a fat duplicate.
-3. **Claude Code is the special case.** Either symlink (`ln -s AGENTS.md CLAUDE.md`) or maintain a thin pointer CLAUDE.md.
-4. **Continue.dev is the other holdout.** If the project uses Continue, maintain `.continue/rules/main.md` as a pointer. Watch the issue tracker for native AGENTS.md support.
-5. **Copilot triple-reads** — it reads its own instructions file PLUS CLAUDE.md PLUS AGENTS.md. Drift between any of those will be visible to Copilot users; the audit should flag any inconsistency.
-
-## "Gas Town" — what it is, why it's not on this matrix
-
-Gas Town ([gastownhall.ai](https://gastownhall.ai)) is **Steve Yegge's open-source multi-agent orchestrator** (released Jan 1, 2026), described as "Kubernetes for AI coding agents." It coordinates Claude Code, Codex, Gemini, etc., persisting work state in git-backed hooks.
-
-It does **not** define a repo-doc format of its own — it dispatches to the underlying agents, each reading whatever file convention they support. Any AGENTS.md / CLAUDE.md set up correctly per this matrix will already work under Gas Town orchestration.
-
-## "Hermes" — what it is, why it's not on this matrix
-
-[NousResearch's Hermes Agent](https://hermes-agent.nousresearch.com) is a self-improving agent that uses **Skills stored in `~/.hermes/skills/`** with a `SKILL.md` + YAML frontmatter pattern (essentially the same shape as Anthropic's Agent Skills). It does **not** define a project-instruction file convention. There is no `HERMES.md`.
-
-Note: "Hermes" is not Cognition Labs' product. Cognition's coding agent is **Devin** — see the row above. Confusion is common.
-
-## Recipe: the minimal pointer set for full compatibility
-
-If you want to support every major agent without drift, the minimum file set is:
-
-```
-/repo
-├── AGENTS.md                            # ← the fat one (canonical)
-├── CLAUDE.md                            # ← symlink → AGENTS.md  OR  3-line pointer
-├── .cursor/rules/main.mdc               # ← 3-line pointer (optional; AGENTS.md works native)
-├── .windsurfrules                       # ← 3-line pointer (optional; AGENTS.md works native)
-├── .github/copilot-instructions.md      # ← 3-line pointer (optional; AGENTS.md works native)
-├── .continue/rules/main.md              # ← 3-line pointer (Continue doesn't read AGENTS.md natively)
-└── CONVENTIONS.md                       # ← only if Aider is in use
-```
-
-If you do not use Cursor/Windsurf/Copilot/Continue, drop those files. The two that always matter: AGENTS.md (everyone) and CLAUDE.md (Claude Code).
-
-## Cross-references
-
-- AGENTS.md spec: `agents-md-spec.md`
-- CLAUDE.md thin-pointer/symlink: `claude-md-convention.md`
-- Audit checks: `../audit-patterns/entry-file-coverage.md`

package/skills/adia-ui-ops/references/standards/readme-conventions.md

@@ -1,232 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - agents-md-spec.md
-  - claude-md-convention.md
-  - cross-tool-matrix.md
-  - ../audit-patterns/redundancy-detection.md
-primary_sources:
-  - https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-health-files
-  - https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository
-  - https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
-  - https://opensource.guide/code-of-conduct/
-  - https://www.contributor-covenant.org/
-  - https://keepachangelog.com/
-status: research-verified
----
-
-# README, CONTRIBUTING, SECURITY — the human-and-LLM landing files
-
-> **The premise.** AGENTS.md is for agents only. README.md is the *front door* — where humans land first, where GitHub auto-renders, where the LLM lands when the user pastes a repo URL into a chat. The two files have different jobs and shouldn't duplicate each other.
-
-## The role split
-
-| File | Audience | Role | Loaded by agent? |
-|---|---|---|---|
-| `README.md` | Humans + LLMs in cold-start | What this project is, install + run, how to find more | Often (when user references the repo at large) |
-| `AGENTS.md` | Coding agents in a session | How to *work in* this repo: commands, conventions, trust boundaries, memory homes | Always (every session) |
-| `CONTRIBUTING.md` | Humans contributing | How to participate: PR process, code review norms, contributor onboarding | Sometimes |
-| `SECURITY.md` | Humans + automated scanners | How to report vulnerabilities; supported versions; disclosure policy | Rarely |
-| `CODE_OF_CONDUCT.md` | Contributors + maintainers | Behavior expectations | Almost never |
-
-README.md and AGENTS.md are **complementary, not redundant**. The redundancy-detection pattern (`../audit-patterns/redundancy-detection.md`) catches when build commands or facts appear in both — that's where drift starts.
-
-## README.md — the human + LLM front door
-
-| Section | Required? | Notes |
-|---|---|---|
-| Project name + tagline | Yes | One sentence |
-| What it does | Yes | One paragraph |
-| Why use it (over alternatives) | Recommended | If applicable |
-| Quickstart / install | Yes | Minimal commands; link to AGENTS.md for full setup |
-| Usage example | Recommended | Smallest meaningful example |
-| Documentation pointer | Yes | Link to `docs/`, AGENTS.md, or external docs site |
-| License | Yes | Or link to `LICENSE` |
-| Contributing pointer | Recommended | One line linking to `CONTRIBUTING.md` |
-| Security pointer | Recommended | One line linking to `SECURITY.md` |
-| Status badges | Optional | Don't bloat — pick load-bearing 2-3 |
-
-### What does NOT go in
-
-- **Full build/test/run commands** — that's AGENTS.md's job. README has a *quickstart*; AGENTS.md has the canonical commands. Both = drift waiting to happen.
-- **Conventions / coding standards** — AGENTS.md or CONTRIBUTING.md.
-- **Architecture details** — `ARCHITECTURE.md`.
-- **Trust boundaries / agent-specific instructions** — AGENTS.md.
-- **Long FAQ** — `docs/faq.md`.
-
-### Length target
-
-200-300 lines for open-source. Internal/private repos: 50-150. A 1000-line README is almost always content that belongs in `docs/`.
-
-### Pointer-discipline pattern
-
-The README's job is to *route* — not *contain*.
-
-```markdown
-# Acme Service
-
-A high-throughput message router for federated agent systems.
-
-## Quickstart
-
-```bash
-pnpm install
-pnpm dev
-```
-
-For canonical build / test / run commands and contributor conventions,
-see [AGENTS.md](./AGENTS.md). For full architecture, see
-[`ARCHITECTURE.md`](ARCHITECTURE.md).
-
-## Documentation
-
-- **For agents (Claude, Codex, Cursor, ...):** [`AGENTS.md`](./AGENTS.md)
-- **Contributing:** [`CONTRIBUTING.md`](./CONTRIBUTING.md)
-- **Security policy:** [`SECURITY.md`](./SECURITY.md)
-- **Architecture:** [`ARCHITECTURE.md`](ARCHITECTURE.md)
-- **Decisions (ADRs):** [`.brain/adrs/`](.brain/adrs/)
-
-## License
-
-[Apache 2.0](LICENSE).
-
-_Last reviewed: 2026-04-27_
-```
-
-The `pnpm dev` command in the quickstart is duplicated minimally on purpose — humans skim README and want "can I run this in 30 seconds?". The agent reaches for AGENTS.md anyway.
-
-## CONTRIBUTING.md — how humans participate
-
-GitHub auto-renders `CONTRIBUTING.md` and surfaces it in the contributor flow (per [GitHub's community-health docs](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions)).
-
-| Section | Required? | Notes |
-|---|---|---|
-| Local setup | Yes | Or link to AGENTS.md / `docs/setup.md` |
-| Running tests | Yes | Or link to AGENTS.md |
-| Branching / commit conventions | Yes | E.g., Conventional Commits |
-| PR process | Yes | Where to open PRs, who reviews, expected turnaround |
-| Code-review norms | Recommended | E.g., "approve on intent, not nitpicks" |
-| Issue templates / labels | Recommended | If you use them |
-| Code of conduct + Security pointers | Recommended | One-line links |
-
-### CONTRIBUTING vs AGENTS — the key split
-
-CONTRIBUTING is for **humans contributing** (norms, review process, branching). AGENTS is for **agents working in the repo** (commands, conventions, trust boundaries). They overlap on `Build / test / run`, and that's where drift happens. Cleanest pattern:
-
-```markdown
-## Local setup
-For build / test / run commands, see [`AGENTS.md`](./AGENTS.md). For
-contribution conventions specific to humans (branching, PR flow,
-code-review norms), continue below.
-```
-
-Same redundancy-elimination pattern as `../audit-patterns/redundancy-detection.md`.
-
-## SECURITY.md — disclosure policy
-
-GitHub auto-renders `SECURITY.md` at `<repo>/security/policy` and links to it from the **Report a vulnerability** flow (per [GitHub's adding-a-security-policy docs](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)).
-
-```markdown
-# Security Policy
-
-## Supported versions
-
-| Version | Supported          |
-|---------|--------------------|
-| 2.x     | :white_check_mark: |
-| 1.x     | :x:                |
-
-## Reporting a vulnerability
-
-Please report vulnerabilities to security@acme.example. We respond
-within 48 hours. Do **not** file public issues for security reports.
-
-We follow [coordinated vulnerability disclosure](https://www.cisa.gov/coordinated-vulnerability-disclosure-process):
-acknowledge within 48h, investigate within 7d, public disclosure
-within 90 days of report (or upon fix release, whichever sooner).
-
-_Last reviewed: 2026-04-27_
-```
-
-### `SECURITY.md` placement
-
-Three locations are equally valid (per GitHub docs):
-
-| Location | When |
-|---|---|
-| `SECURITY.md` (repo root) | Most repos |
-| `.github/SECURITY.md` | If you keep policy files in `.github/` |
-| `docs/SECURITY.md` | If you want it docs-aligned (renders in GitHub UI either way) |
-
-GitHub auto-renders all three. **Pick one — having two is confusing.**
-
-What does NOT go in: implementation details of past vulnerabilities (those go in `.brain/postmortems/` with sensitive details redacted), threat-model docs (`docs/threat-model.md`), compliance attestations (`docs/compliance/`).
-
-## CODE_OF_CONDUCT.md — behavior expectations
-
-Most projects use the [Contributor Covenant](https://www.contributor-covenant.org/) verbatim — the de facto industry default. Placement: repo root or `.github/`. Same auto-render rules as SECURITY.md. The audit flags absence on public/community repos as **recommended-low**; for internal-only repos, not required.
-
-## How AGENTS.md should reference these files
-
-In `Where to find things`:
-
-```markdown
-- **README:** `README.md` — the human-and-LLM front door
-- **Contributor guide:** `CONTRIBUTING.md`
-- **Security policy:** `SECURITY.md`
-- **Code of conduct:** `CODE_OF_CONDUCT.md`
-```
-
-These are *navigation* references. The agent already loads AGENTS.md every session; it pulls in README/CONTRIBUTING/SECURITY only when the user's question implies it.
-
-## Avoiding redundancy with AGENTS.md
-
-| Topic | AGENTS.md | README.md | CONTRIBUTING.md | SECURITY.md |
-|---|---|---|---|---|
-| What this project is | brief tagline (header) | full one-paragraph | (no) | (no) |
-| Build / test / run | **canonical** | quickstart only, link to AGENTS | "see AGENTS.md" | (no) |
-| Conventions | **canonical** | (no) | branching/commits only | (no) |
-| Trust boundaries | **canonical** | (no) | (no) | (no) |
-| Where to find things | **canonical** | brief pointer to AGENTS | (no) | (no) |
-| Memory primitives | **canonical** | (no) | (no) | (no) |
-| PR process | (no) | (no) | **canonical** | (no) |
-| Vulnerability reporting | (no) | (no) | (no) | **canonical** |
-| Architecture | "see ARCHITECTURE.md" | "see ARCHITECTURE.md" | (no) | (no) |
-
-Every cell with **canonical** is the *only* place that information lives. Other cells link to it. Detected/enforced by `../audit-patterns/redundancy-detection.md`.
-
-## GitHub UI behaviors
-
-- README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT all get **auto-rendered** at well-known URLs.
-- The **community profile** view (`<repo>/community`) shows which recommended files are present.
-- The "first-time contributor" prompt surfaces CONTRIBUTING and CODE_OF_CONDUCT.
-- The **Report a vulnerability** flow surfaces SECURITY.md.
-- GitHub does **not** auto-render AGENTS.md as anything special — it's just Markdown. The `agents.md` standard exists to be agent-readable, not GitHub-UI-special.
-
-## Audit checks
-
-1. `README.md` exists, ≤300 lines (warn at 200; error at 500).
-2. `CONTRIBUTING.md` exists for public/community repos.
-3. `SECURITY.md` exists for public/community repos with users.
-4. `CODE_OF_CONDUCT.md` exists for public/community repos with contributors.
-5. None duplicate AGENTS.md's canonical content (build commands, conventions, trust boundaries) — flag as drift risk per `../audit-patterns/redundancy-detection.md`.
-6. README references AGENTS.md (so agents and humans converge on the same canonical instructions).
-7. SECURITY.md is in *one* location (root, `.github/`, or `docs/`) — flag if multiple.
-
-## Common anti-patterns
-
-- **README.md duplicates the entire AGENTS.md.** Drift waiting to happen. Compress to a routing layer.
-- **CONTRIBUTING.md re-lists build commands.** Same drift problem. Link to AGENTS.md.
-- **SECURITY.md says "report vulnerabilities" without saying *how*.** Useless. Include contact + SLA.
-- **CODE_OF_CONDUCT.md modified beyond the Contributor Covenant baseline.** Usually unproductive scope creep.
-- **Status badges everywhere, no real content.** Fails the "what does this do?" test in 5 seconds.
-- **README.md without `_Last reviewed:_` or frontmatter date.** Fails the staleness gate.
-
-## Cross-references
-
-- AGENTS.md spec: `agents-md-spec.md`
-- CLAUDE.md as thin pointer: `claude-md-convention.md`
-- Cross-tool compatibility matrix: `cross-tool-matrix.md`
-- Redundancy detection: `../audit-patterns/redundancy-detection.md`
-- Greenfield setup: `../recipes/greenfield-setup.md`