____ ____ ____ _  _ ___    ____ ___ ____ _  _ ___  ____ ____ ___
|__| | __ |___ |\ |  |  __ [__   |  |__| |\ | |  \ |__| |__/ |  \
|  | |__] |___ | \|  |     ___]  |  |  | | \| |__/ |  | |  \ |__/

Keep AI-agent instruction files honest and single-sourced

Standard | Start here | Quick start | Contents | Adopters | Contributing

---

About

agent-standard is a small, opinionated convention for structuring the instruction files an AI coding agent reads (AGENTS.md, CLAUDE.md) so they stay accurate as the codebase changes.

It exists because instruction files drift. The moment a repo has two of them, or a README that half-documents the same thing, they fall out of sync. An agent that reads a stale instruction file confidently follows dead rules, recreates deleted code, and relearns the same gotcha every session. agent-standard makes the files single-sourced and self-correcting instead.

agent-standard keeps instruction files honest with:

• One source of truth (§1): AGENTS.md is canonical; CLAUDE.md is a one-line @AGENTS.md include (or a symlink)
• Scoped instruction files (§1): subdirectory AGENTS.mds and path-scoped rules for context that belongs to one part of the repo, zero duplication with the root
• An in-repo fix log (§2): docs/solutions/, one past bug or gotcha per file, each opening with a small metadata header (frontmatter) so entries are searchable
• Anti-drift sync contracts (§3): a ## Keep in sync block naming the file pairs that must agree
• Self-healing SessionStart hooks (§4): a script that runs when an agent session starts and repairs silently-failing config before it bites
• A rationalization table (here): the recurring excuses used to skip the discipline ("too small to log", "I'll sync it later"), each pre-rebutted in the spec

agent-standard keeps day-to-day work safe with:

• Sanctioned commit identities (§5), so no stray author lands in history — plus continuous agent-authorship disclosure, so agent-generated commits and PR activity are never invisible
• A default-to-main commit flow (§6), with branch + PR reserved for genuinely risky changes
• Multi-account deploy hygiene (§7), so a deploy never targets the wrong account
• A pre-commit secret scan and a full-history secret audit (templates, bin/secrets-audit)
• Model-routing policy for multi-model setups (§8): route bulk work cheap, escalate on quality, dial reasoning effort over dropping to a weaker model, route against live quota, review with the strongest models
• Delegation rules for long-running work (§9): files over context, reviews that gate, continue-don't-confirm, and commit hygiene under parallel workers
• Guardrails and recovery (§10): a failure ladder instead of silence, each task gets only the tools it needs, fetched content is treated as data and never as instructions (prompt-injection discipline), and escalation criteria are written down
• Knowledge succession (§11): turning one person's tacit repo knowledge into a ground-truth-verified skill library that outlives them and runs on cheaper models

agent-standard is cross-harness — a harness is whichever tool runs your agent (Claude Code, Codex, Cursor, Gemini, …). AGENTS.md is read by Codex, Cursor, Gemini, and Agent Skills; the @AGENTS.md include points Claude Code at the same file. No lock-in.

Prefer reading on a website? The standard is rendered at anmoln7.github.io/agent-standard-oss.

Automation boundary

This project mixes two layers with different trust levels. Know which one you're opting into:

Layer	What it does	Trust level
Instruction drift control	AGENTS.md + CLAUDE.md include, docs/solutions/ fix log, ## Keep in sync blocks	Docs-only — no code runs, nothing is installed
Read-only checks	adopt --check, repo-audit, the standard-compliance CI action	Read-only — scans and reports, changes nothing
Local hooks	templates/hooks/ (SessionStart self-healing) and templates/git/hooks/pre-commit (secret scan)	Local automation — runs on your machine, you review the template before copying it in
Write-capable automation	adopt (interactive/--yes), land-safely, pr-approve, crew	Write-capable — commits, pushes, or drives multi-agent work

Start at the top of the table and move down only as far as you want. The docs-only lane below needs none of the write-capable layer.

New to this? Start here 🧙

You don't need to know what a symlink is. One line installs everything, then the adopt wizard walks you through the rest in plain English — a before/after scorecard, a question before every change, and nothing ever deleted:

curl -fsSL https://raw.githubusercontent.com/anmoln7/agent-standard-oss/main/install.sh | bash
cd /path/to/your/project
adopt

Even easier — let Claude Code do the whole thing. Install the plugin once, then one command runs the wizard and fills in your AGENTS.md from the actual codebase:

/plugin marketplace add anmoln7/agent-standard-oss
/plugin install agent-standard@agent-standard
/agent-standard:adopt

(/agent-standard:check shows the read-only scorecard anytime.)

Two minutes later your project has its welcome note (AGENTS.md), a diary of solved problems (docs/solutions/), and secret files locked out of history. Run ~/agent-standard/bin/adopt --check anytime for the scorecard — it reports a maturity level (L0–L3), where the top level requires the secret-hygiene floor, so a repo can't score "almost perfect" while leaking .env. adopt --check --json emits a machine-readable version (with stable STD-01…STD-06 check IDs) to gate CI or pipe into other tooling.

Quick start

Prefer to do it by hand? Adopt the standard in an existing repo in four steps. The full recipe is in STANDARD.md.

# Get the templates and scripts
git clone https://github.com/anmoln7/agent-standard-oss ~/agent-standard

# In your repo:
# 1. Make AGENTS.md canonical, CLAUDE.md a one-line include
#    (if AGENTS.md already exists, merge CLAUDE.md into it by hand instead)
[ -f AGENTS.md ] && echo "AGENTS.md exists — merge by hand" || git mv CLAUDE.md AGENTS.md
printf '@AGENTS.md\n' > CLAUDE.md

# 2. Start a fix log
mkdir -p docs/solutions
cp ~/agent-standard/templates/docs/solutions/EXAMPLE-*.md docs/solutions/

# 3. Add a "## Keep in sync" block to AGENTS.md for your drift-prone file pairs

# 4. (optional) add the self-healing hook for repos with silent-failure config
cp -r ~/agent-standard/templates/hooks .

Then put the bin/ scripts on your PATH for the automated safe path:

export PATH="$HOME/agent-standard/bin:$PATH"   # add to your shell profile

Docs-only / read-only adoption

Some teams want the instruction standard without any hooks, commit helpers, or PATH automation. This lane is entirely docs-only plus one read-only check — nothing here runs code beyond adopt --check scanning your files:

git clone https://github.com/anmoln7/agent-standard-oss ~/agent-standard

# 1. Make AGENTS.md canonical, CLAUDE.md a one-line include
[ -f AGENTS.md ] && echo "AGENTS.md exists — merge by hand" || git mv CLAUDE.md AGENTS.md
printf '@AGENTS.md\n' > CLAUDE.md

# 2. Start a fix log
mkdir -p docs/solutions
cp ~/agent-standard/templates/docs/solutions/EXAMPLE-*.md docs/solutions/

# 3. Check compliance — read-only, changes nothing
~/agent-standard/bin/adopt --check

No hooks are installed, no bin/ scripts touch your PATH, and nothing commits on your behalf. Layer in local hooks or write-capable automation later, if ever — see the automation boundary table above.

What's in the box

STANDARD.md                        the spec
install.sh                         one-line installer (curl | bash, no sudo)
.gitattributes                     forces LF on all files (Windows/CRLF checkouts)
VERSION                            single source of truth for the release version
.claude-plugin/ + commands/        Claude Code plugin: /agent-standard:adopt, :check
AGENTS.md                          this repo's own instruction file (dogfooding the standard)
docs/solutions/                    this repo's own fix log — real past bugs, one per file
bin/                               reusable agent-workflow scripts (bash, no deps)
  adopt                            friendly onboarding wizard (plain English, asks first)
  repo-audit                       read-only health report across your repos
  secrets-audit                    full-history secret scan of a repo, not just staged
  pr-risk / pr-approve             classify a change routine vs novel; gate merges
  land-safely                      first-pass agent code to a clean reviewed PR
  crew / wt                        run parallel agent tasks; manage git worktrees
                                   (worktree = a parallel checkout of the same repo)
  sync-version                     derive VERSION into the plugin manifests + README pin (maintainer)
  doc-gate-check                   pin AGENTS.md's documented commands to the CI gates (maintainer)
tests/
  run-tests.sh                     plain-bash tests for the scripts (run in CI)
templates/
  docs/solutions/EXAMPLE-*.md      two worked fix-log entries with the required frontmatter
  hooks/                           SessionStart self-healing hook; review-gate + ratchet gates (§2)
  git/                             a pre-commit secret-scan hook and a gitignore starter
examples/
  AGENTS.md                        a worked AGENTS.md that follows the standard
  orchestration-workflow.md        a worked orchestrator + workers model setup (§8)

Scripts are config-first. repo-audit and secrets-audit scan AGENT_STD_ROOTS (colon-separated, default ~/Documents/GitHub:~/Code:~/src). repo-audit can also watch "Keep in sync" twins — set AGENT_STD_TWIN_DIRS="dirA:dirB" and it flags same-named files that differ between the two dirs. crew launches at most CREW_MAX_PARALLEL agents at once (default 4, 0 = unlimited).

Enforce it in CI

This repo doubles as a GitHub Action that runs the adopt --check scorecard and fails the build if your repo drifts from the standard:

jobs:
  agent-standard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anmoln7/agent-standard-oss@v0.10.0

Once it's green, grab the badge and add yourself to ADOPTERS.md:

Design principles

• Single-source or bust. The only thing this fights is duplication. Two complementary files are fine; two files with the same content are not.
• Config stays private. The standard is public policy. Your concrete account maps, emails, and secrets belong in a private file or a secrets manager, never here.
• Small and enforceable. Every rule reduces drift or it does not belong in the spec.

Contributing

PRs welcome. See CONTRIBUTING.md. Good first contributions: a new templates/docs/solutions/ example, a harness this standard has not been tested against, or a bin/ script that automates another safe path.

License

MIT.