agentleFS
Sign inStart free
ianshankianshank/Agents/docs/AGENTS.md

Agents

AGENTS.md1 starsChanged 58 days agoApache-2.0View on GitHub

Prose the repo guards. Some of it is immutable, some is generated, none of it is a scratch pad. This directory holds the charter, the decision record, plans, runbooks and two generated artifacts. README.md is the index of what lives where; STYLE.md is the taxonomy. This file is the set of rules that turn a harmless documentation edit into a failing build. - ADRs are immutable. A decision that changed course is a new ADR that supersedes the old one,…

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    An unlisted plan is an invisible plan: Every plans/<topic>/ must appear in README.md's plans table.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — docs

Prose the repo guards. Some of it is immutable, some is generated, none of it is a scratch pad.

This directory holds the charter, the decision record, plans, runbooks and two generated artifacts. README.md is the index of what lives where; STYLE.md is the taxonomy. This file is the set of rules that turn a harmless documentation edit into a failing build.

Map

PathRole
STYLE.mdThe taxonomy: which kind of doc a change is, and where it goes
CHARTER.mdNorth-star scope and invariants. Links and claims are both gated
decisions/Immutable ADRs. Numbering is not contiguous
plans/plans/<topic>/{PLAN.md,REVIEW.md}; each must be listed in README.md
runbooks/Operational how-to prose
e2e-matrix/, matrix-coverage.mdGENERATED. Regenerate, never hand-edit
golden-corpus/Human-label contract; stays empty until a human writes rows

Diagram

flowchart TD
  accTitle: routing a documentation change to the right file
  accDescr: A decision becomes a new immutable ADR, a how-to becomes a runbook, a plan of work becomes a plan folder that must be indexed in the docs README, and an overview becomes a component README.

  Q["a change worth writing down"]

  subgraph D["docs/ (you are here)"]
    ADR["decisions/NNNN-*.md<br/>immutable"]
    RB["runbooks/"]
    PL["plans/<br/>one folder per topic"]
    IDX["README.md index"]
    GENA["matrix-coverage.md<br/>e2e-matrix/<br/>GENERATED"]
  end

  RM["a component README"]
  SUP["a NEW superseding ADR"]

  Q --> ADR
  Q --> RB
  Q --> PL
  Q --> RM
  PL --> IDX
  RB --> IDX
  ADR --> SUP
  GENA --> IDX

  classDef here fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
  class D here

Rules that bite here

  • ADRs are immutable. A decision that changed course is a new ADR that supersedes the old one, never an edit to it. Editing an accepted ADR destroys the record of why the old choice was made, which is the only thing an ADR is for.
  • ADR numbers are not contiguous, and 0007 is an intentional gap. Do not backfill it and do not renumber later ADRs to close it. Take the next free number after the highest one in decisions/README.md, and add your row to that index.
  • CHARTER.md is doubly gated. scripts/check_charter_drift.py fails when its markdown links rot; scripts/check_charter_invariants.py mechanically re-checks its claims — package roles, invariants, default-off flags — against the code. A charter edit that states something the repo does not do fails CI, not review.
  • e2e-matrix/ and matrix-coverage.md are generated and freshness-gated. Regenerate with python tests/test_matrix_coverage.py --update and make e2e-matrix-update. A hand edit is erased and fails make matrix-check / make e2e-matrix-check in the meantime.
  • An unlisted plan is an invisible plan. Every plans/<topic>/ must appear in README.md's plans table; eleven of them went unreachable before that index existed. The same applies to a new runbook.

Verify

make invariants

Subagents

Task in this directoryAgentWhy
Find every doc that cites an ADR before superseding itexplorerRead-only Grep across prose; supersession leaves stale citations behind
Run the charter and freshness gates after a docs changetest-runnerHas Bash; make invariants chains three checkers and only one will fail
Review a charter or ADR edit before pushingnarrow-criticAn overstated invariant is a correctness problem no linter reads

See also

DocRead it when
STYLE.mdYou are creating a doc and must decide whether it is an ADR, runbook, plan or README
decisions/README.mdYou need the next free ADR number or the supersession convention
README.mdYou added a plan or runbook and have to make it reachable
CHARTER.mdA change might exceed the declared scope or touch an invariant and needs escalation
plans/agents-md-directory-docs/TEMPLATE.mdYou are writing or editing an AGENTS.md anywhere in this repo

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free