Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (48 loc) · 3.52 KB

AGENTS.md

File metadata and controls

65 lines (48 loc) · 3.52 KB
Raw

AGENTS.md — working in this repo

Written for AI coding agents, and equally readable by a human contributor. Short on purpose.

What this repo is

The governance skeleton: how a rule for you, your team, and your AI agents is written, routed, loaded, superseded, and argued with. There is no application here — the deliverables are a spec, templates, and sanitized real examples. Treat prose as the product and review it like code.

docs/SPEC.md is normative. If a change contradicts the spec, either the change is wrong or the spec needs the same PR.

Layout

  • docs/SPEC.md — rule anatomy, frontmatter schema, precedence, the routing tree.
  • templates/rule-template.md, decision-memo-template.md, declined-decisions-template.md.
  • examples/ — real rules from a live system, sanitized. rule-objection-sparring.md is the one born from an actual overturned verdict; it is the reference for tone.
  • FOR-ROBOTS.md — the entry point for an agent mining this repo for patterns.
  • ROADMAP.md, CHANGELOG.md — releases are cut twice a week, small commits daily.

How to verify a change

There is nothing to execute, so verification is structural. Before opening the PR:

  1. Frontmatter validates against docs/SPEC.md — every required field present, origin and date_established real, supersedes pointing at something that exists.
  2. One rule, one file. If your change adds a second rule to an existing file, split it.
  3. No duplicate homes. A rule lives in exactly one place; everything else points at it. Grep for the rule's trigger phrase before adding it — a copy that drifts is the failure mode this whole repo exists to prevent.
  4. Links resolve. Both directions, if the rule claims a relationship.

State in the PR which of those four you checked. "Prose, nothing to run" is not a verification.

Conventions

  • Trigger + essence + pointer. An always-loaded index line is short by law; the body loads on demand. A rule that needs three paragraphs in the index is two rules or a bad rule.
  • Newer beats older on the same topic, and a rule marked with an explicit owner is overturned only by that owner. Never silently edit an owner's rule — supersede it, with a dated record.
  • Declined stays declined. A rejected idea goes in the declined-decisions journal with the reason. Re-proposing it needs new information, and the PR should say what the new information is.
  • Objections are numbered and rebuttable. A "no" without a numbered list and an invitation to rebut is not a review here; it is an obstacle.
  • Examples are sanitized: no real names, no real chat identifiers, no real paths, no secrets.

Boundaries — what needs a human

  • docs/SPEC.md itself — the frontmatter schema and precedence rules are the contract every downstream copy depends on.
  • Adding a new rule type or a new home in the routing tree. Four homes exist for a reason; a fifth needs an argument in an issue.
  • Anything that weakens supersede-instead-of-edit. The audit trail is the point.

The deal

Your copyright stays yours, there is no CLA, and issues labelled accepted are free to take — comment "claiming this". Full terms: CONTRIBUTING.md.

If an AI wrote your change, say so in the PR and confirm you read it end to end. Welcome here — we do it daily. Unread generated text is the one thing that gets closed on sight, and in a repo made of prose that rule bites harder, not softer.