agentleFS
CRELLIA-S-LCRELLIA-S-L/srs-dd/skeleton/AGENTS.md

srs-dd / skeleton

AGENTS.md0 starsChanged 32 days agoMITView on GitHub

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:

    Before changing behavior, find the requirements that describe it: python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables in …

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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

<Your Project Name> — agent guide

<SRS-DD-WIDTH-LINE> <!-- srs-dd --> A summary for coding agents; the project follows the SRS-DD standard. On any conflict, `srs-dd/standard.md` wins — it is the single normative document on the specification. System behavior is described in `specs/` as numbered requirements with links between them and references to code.
  • Specification rules — srs-dd/standard.md, by section; python3 srs-dd/tools/srs_view.py --vocabulary prints the words a block may use.
  • The method's articles — srs-dd/method.md (SRS-DD-ART-*), the framework's and the same in every project; the project's own principles are specs/constitution.md (ART-*). Both apply to every task.
  • Markdown is not wrapped to a width — a line breaks where the meaning breaks, never inside a sentence; the renderer does the wrapping.
  • Check — python3 srs-dd/tools/srs_check.py.
  • Gate — python3 srs-dd/tools/srs_gate.py runs what the pipeline and the pre-commit hook run: the checkers, then every generated file compared with what git holds.
  • Read — python3 srs-dd/tools/srs_view.py <ID> for one requirement with its links resolved, --code <path> for the requirements describing a file (--statements adds what each obliges), <ID> --where for the lines that carry it (--source prints them), --areas for what the specification is divided into, --open for a page a non-engineer can read; .claude/skills/srs-page/SKILL.md is the procedure around it.
  • Check a finished change — .claude/skills/srs-check/SKILL.md reads the verification method and the tests field of every requirement the change touched, and offers exactly those; it runs nothing unasked.
  • Build over several passes — .claude/skills/srs-build/SKILL.md writes what has to exist before the first pass and judges the work against that list, takes one requirement's worth of change per pass with its tests, classifies every failure before touching it, and closes the loop in the same set of edits.
  • Review a finished change — .claude/skills/srs-review/SKILL.md runs the checks the requirements call for, reads the work for what no check reaches, confirms every finding in the file it names before reporting it, and calls the work reviewed only on two consecutive passes that found nothing by different means.
  • Prepare a commit — .claude/skills/srs-commit/SKILL.md hands the change to the review and check procedures, establishes which files the message covers, puts the generated files in the index and names the requirement identifiers the change implements, bare, in a trailing parenthesis; it commits nothing itself.
  • Skills — the procedures in .claude/skills/*/SKILL.md are plain markdown; an agent without a skill system reads them directly as workflow guides.
  • Freeze a baseline — python3 srs-dd/tools/srs_baseline.py X.Y.Z writes the row into specs/92-baselines.md; the commit that carries it is the baseline, and .claude/skills/srs-baseline/SKILL.md is the procedure. Nothing here commits or tags for you.
  • Date requirements — python3 srs-dd/tools/srs_dates.py writes into each requirement the date its identifier first appeared in the history; --dry-run says what it would write. Run on purpose, never by a gate.
  • Grounds register, where the project keeps grounds/ — python3 srs-dd/tools/srs_grounds.py checks it and regenerates grounds/90-dashboard.md; --blast <path> says what the requirements behind a file stand on, and --html prints the dashboard as a page. .claude/skills/srs-bet/SKILL.md is the procedure.
  • Architecture layer, where the project keeps arch/ — python3 srs-dd/tools/srs_arch.py checks it against the specification and regenerates arch/90-map.md; a part still proposed is a design, and --plan says what moving to it requires. python3 srs-dd/tools/srs_arch_doc.py prints the layer as a document for a person, on request, and --html prints it as a page. A part may also say what it is made of inside, as forms in arch/20-shapes.md, designed from the obligations the part carries and compared with what that part's own code declares. .claude/skills/srs-arch/SKILL.md is the procedure; srs-arch-harvest recovers a cut, or the forms inside a part, from a project that has one, and srs-arch-audit judges either.
  • Publish the pages — index.html, arch.html and grounds.html side by side (Published pages, srs-dd/standard.md); --link says which others are beside a page, and it links exactly those, so none promises a page nobody rendered.
  • Upgrade the framework — python3 srs-dd/tools/srs_upgrade.py shows the version transition, the upgrade notes and the file list, then asks; .claude/skills/srs-upgrade/SKILL.md is the procedure. No framework clone, no address to look up.

Two ways in

A question about how the system works starts with what this project wrote about itself — specs/00-glossary.md, specs/01-introduction.md, specs/02-overview.md: short, and in the project's own words, which a search over requirement text assumes you already know. Then --areas, then one area, then the requirement, then its code.

A change to behavior starts at the loop below.

The loop

  1. Before changing behavior, find the requirements that describe it: python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables in specs/90-traceability.md. None exist — create one first, with the initial status per the Lifecycle section of srs-dd/standard.md.
  2. Plans reference requirement IDs, not prose.
  3. Implement.
  4. Record what you chose: each way the change met a requirement that could have been met another way is a decision — Workflow in srs-dd/standard.md says what counts — and goes into specs/adr/; when there was none, the report says so.
  5. Close the loop: status, code, tests — in the same set of edits as the code.
  6. Run the checker.

The rules most easily broken

  1. Changing behavior — first find or create the requirement, then write the code.
  2. specs/90-traceability.md is generated by a script; never edit it by hand.
  3. Builds, tests, and every other action that SRS-DD-ART-030 of the method reserves run only with the user's explicit confirmation.
  4. Naming a record to a person — a requirement, a decision, and where the project keeps the layers an element or a grounds record: at its first mention in what the person reads as a whole (a message, a plan, a report), give its title, the file it is written in and its status, pasted from the tool, never typed: python3 srs-dd/tools/srs_view.py --cite <ID>… prints FR-<AREA>-<NNN> — <its own title> (specs/<file>.md, <status>) and cites a decision by its ADR-NNNN; python3 srs-dd/tools/srs_arch.py --cite and python3 srs-dd/tools/srs_grounds.py --cite print the same form for an element and a register record. Afterwards the number alone is enough; inside specs/, arch/ and grounds/ the identifier is the name. A line a checker printed is run through --cite before it is relayed. The rule holds in a table, a list, the steps of a plan and the report of any procedure — add the citation to a template that has no place for it. It is checked at sending: what was pasted is what the tool printed — no bold around it, no backticks around the file, nothing added inside the brackets. A mention in passing needs it too. A span named as a set — FR-<AREA>-010 through FR-<AREA>-090, a whole area — is one name, not a mention of each member. A commit message and the changelog are the exception and name identifiers bare, in a trailing parenthesis. A number the specification does not carry yet is a proposal, and is marked as one.
  5. Reading the code behind a change — take the files from the code and tests fields of the requirements the change belongs to (--code <path> answers from the other end), not from a search over the repository. Go wider where you must, and say where you went.
  6. Reporting to a person — write in sentences that follow one another, and keep a list or a table for what the reader has to count or compare. A label with a fragment after it is a note to yourself. A report is not sent inside a code fence, which renders none of it. Say what happened and what follows from it in plain statements: no figure of speech where a plain verb exists, nothing about the work of writing the report, no clause whose only job is to join two of your own thoughts. Read the report once before sending it, delete what the reader cannot act on, and claim no action and no number that a tool result here does not show. Answer what was asked; a subject the task did not ask about goes in one line at the end, or not at all.
  7. Saying what the project's files say — read the source in the same message and match the sentence to it before sending, not to what you remember. A count is derived over the current files, a claim that something is nowhere written names what was searched, and a paraphrase is checked against the passage it paraphrases.
  8. Putting something to a person for a decision — a sentence for a document, a requirement's text, a step of a plan: the message that asks carries the text as it would be written, quoted in a block where it is long; "as shown above" sends the reader back through the conversation to find it.
  9. A rule the conversation settles — where something agreed will bind the work after this task is over and no requirement says it, offer to author the requirement, naming what it would oblige and the area it belongs to. Offered, never written: the maintainer decides whether it is written at all.
  10. A commit that alters behavior names the requirement identifiers it implements, bare, in a trailing parenthesis — SRS-DD-ART-060 asks the commit or the pull request for them, and the identifiers are the ones the change was planned from.
  11. Nothing sensitive goes into the repository (SRS-DD-ART-100) — no credentials, personal data, documents shared in confidence or traces of your machine. Read what is untracked before staging, and name a file that stays local in .gitignore before writing it.
  12. The procedure the project names for an act is the one used — a general procedure of your own that covers the same act only where the instruction named that one. Where it did, name the project's procedure for that act before following the instruction: the choice is the maintainer's, the naming is not.
<!-- /srs-dd -->

This project

What agents working here must know beyond the method: where the code lives, how it is built and run, what is never done. Written by the project; the region above is the framework's and is refreshed by every upgrade.

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.