srs-dd
AGENTS.md0 starsChanged 32 days agoMITView on GitHub
You are in the repository of the SRS-DD framework itself, not in a project that uses it. Nothing here describes an application: the specification in specs/ describes this framework's own tooling.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository21 other files it gives its agents.
- docs/agents.mdAGENTS.md
- skeleton/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skeleton/CLAUDE.mdCLAUDE.md
- srs-arch-auditSkill
- srs-arch-harvestSkill
- srs-archSkill
- srs-auditSkill
- srs-baselineSkill
- srs-betSkill
- srs-buildSkill
- srs-checkSkill
- srs-commitSkill
- srs-harvestSkill
- srs-initSkill
- srs-newSkill
- srs-pageSkill
- srs-releaseSkill
- srs-reviewSkill
- srsSkill
- srs-upgradeSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Before changing behavior, find the requirements that describe it: python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables in …
- Very specific: line 62
Follow .claude/skills/srs-init/SKILL.md — plain markdown, no skill system required.
- Very specific: line 69
Never run the installer against this repository.
≈ “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.
Files
SRS-DD — agent guide for the framework repository
You are in the repository of the SRS-DD framework itself, not in a project that uses it.
Nothing here describes an application: the specification in specs/ describes this framework's own tooling.
<!-- 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 --vocabularyprints 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 arespecs/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.pyruns 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 (--statementsadds what each obliges),<ID> --wherefor the lines that carry it (--sourceprints them),--areasfor what the specification is divided into,--openfor a page a non-engineer can read;.claude/skills/srs-page/SKILL.mdis the procedure around it. - Check a finished change —
.claude/skills/srs-check/SKILL.mdreads theverificationmethod and thetestsfield of every requirement the change touched, and offers exactly those; it runs nothing unasked. - Build over several passes —
.claude/skills/srs-build/SKILL.mdwrites 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.mdruns 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.mdhands 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.mdare 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.Zwrites the row intospecs/92-baselines.md; the commit that carries it is the baseline, and.claude/skills/srs-baseline/SKILL.mdis the procedure. Nothing here commits or tags for you. - Date requirements —
python3 srs-dd/tools/srs_dates.pywrites into each requirement the date its identifier first appeared in the history;--dry-runsays what it would write. Run on purpose, never by a gate. - Grounds register, where the project keeps
grounds/—python3 srs-dd/tools/srs_grounds.pychecks it and regeneratesgrounds/90-dashboard.md;--blast <path>says what the requirements behind a file stand on, and--htmlprints the dashboard as a page..claude/skills/srs-bet/SKILL.mdis the procedure. - Architecture layer, where the project keeps
arch/—python3 srs-dd/tools/srs_arch.pychecks it against the specification and regeneratesarch/90-map.md; a part stillproposedis a design, and--plansays what moving to it requires.python3 srs-dd/tools/srs_arch_doc.pyprints the layer as a document for a person, on request, and--htmlprints it as a page. A part may also say what it is made of inside, as forms inarch/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.mdis the procedure;srs-arch-harvestrecovers a cut, or the forms inside a part, from a project that has one, andsrs-arch-auditjudges either. - Publish the pages —
index.html,arch.htmlandgrounds.htmlside by side (Published pages,srs-dd/standard.md);--linksays 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.pyshows the version transition, the upgrade notes and the file list, then asks;.claude/skills/srs-upgrade/SKILL.mdis 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
- Before changing behavior, find the requirements that describe it:
python3 srs-dd/tools/srs_view.py --code <path/to/file>, or the tables inspecs/90-traceability.md. None exist — create one first, with the initial status per the Lifecycle section ofsrs-dd/standard.md. - Plans reference requirement IDs, not prose.
- Implement.
- 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.mdsays what counts — and goes intospecs/adr/; when there was none, the report says so. - Close the loop: status,
code,tests— in the same set of edits as the code. - Run the checker.
The rules most easily broken
- Changing behavior — first find or create the requirement, then write the code.
specs/90-traceability.mdis generated by a script; never edit it by hand.- Builds, tests, and every other action that SRS-DD-ART-030 of the method reserves run only with the user's explicit confirmation.
- 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>…printsFR-<AREA>-<NNN> — <its own title> (specs/<file>.md, <status>)and cites a decision by itsADR-NNNN;python3 srs-dd/tools/srs_arch.py --citeandpython3 srs-dd/tools/srs_grounds.py --citeprint the same form for an element and a register record. Afterwards the number alone is enough; insidespecs/,arch/andgrounds/the identifier is the name. A line a checker printed is run through--citebefore 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>-010throughFR-<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. - Reading the code behind a change — take the files from the
codeandtestsfields 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. - 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.
- 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.
- 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.
- 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.
- 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.
- 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
.gitignorebefore writing it. - 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 -->Installing SRS-DD into a project
Follow .claude/skills/srs-init/SKILL.md — plain markdown, no skill system required. It covers fresh initialization, adoption and upgrades, and says which decisions are the maintainer's.
python3 tools/srs_init.py path/to/project --dry-run
python3 tools/srs_init.py path/to/project [flags]Never run the installer against this repository; it refuses on its own (is_inside), but do not rely on that.
What lives where
| Path | What it is |
srs-dd/ | The framework's directory, copied whole into every project and the source here. Under tools/: srs_check.py, srs_parse.py, srs_view.py, srs_view_model.py, srs_view_page.py, srs_upgrade.py, srs_baseline.py, srs_dates.py, srs_gate.py (shipped to targets); srs_grounds.py (shipped where a project keeps a register); srs_arch.py and srs_arch_doc.py (shipped where a project keeps an architecture layer). Beside them standard.md (the specification's standard), grounds.md and arch.md (the layers' standards, shipped with their layer), method.md (SRS-DD-ART-*), guide.md (the region of every AGENTS.md), LICENSE and the README.md that carries the marker |
specs/ | This framework's own specification; specs/constitution.md holds this repository's own articles (ART-*) |
skeleton/ | Starters of a project's own files: specification files, AGENTS.md/CLAUDE.md with the region — this file and the root CLAUDE.md are this repository's instances of them |
tools/ | srs_init.py, srs_release.py, srs_cite_eval.py, srs_proc_eval.py, srs_report_eval.py, ci_selftest.sh, test_lib.sh (framework-only) |
tests/ | The suites this repository's pipeline runs; requirements cite them by path |
ci/ | Starters of a project's pipelines and hook — not this repository's own pipeline |
.claude/skills/ | Procedures; srs-init and srs-release are framework-only, the rest ship — srs-bet with the register, the three srs-arch* with the layer |
.github/workflows/srs.yml | This repository's own pipeline |
Two rules that protect other people's repositories
- Nothing framework-specific goes into
skeleton/orsrs-dd/as a path that exists only here. A requirement of this repository named in a shipped file lands in every project installed afterwards — a hard checker error on a stranger's first install. - Annotate the shipped tooling like anything else — the installer takes the annotations out on the way into a target. Every tool under
srs-dd/tools/carriesimplements:/verifies:lines — the other half of the two-way check — andtools/srs_init.pyreplaces each as it copies (FR-INIT-180), keeping the line so line numbers match. Never mark such a linesrs-ignoreto quiet something — the exemption is unconditional andsrs-ignoremarks an example, never a claim.
Working on the framework
This repository is itself an SRS-DD project: a behavior change here goes through specs/ exactly as the loop above states it.
- Generated files —
specs/90-traceability.md,arch/90-map.mdandgrounds/90-dashboard.mdare written by the checkers; never edit them by hand. - Line width — the rule and its reasons are in
CONTRIBUTING.mdunder Ground rules; read it before reformatting anything. Markdown is not wrapped to a width; where a line may break is INV-SPEC-070.tests/line-width.shrefuses a code line wider than 120 columns whose width no string literal accounts for (FR-CI-100). - Whether the guides hold for a fresh agent —
python3 tools/srs_cite_eval.pyscores how a fresh instance names records (FR-SKILL-290);python3 tools/srs_proc_eval.pyruns the scenarios intests/eval/scenarios/and reports what each added, burned and met (FR-SKILL-310);python3 tools/srs_report_eval.pyhas one instance report and a second judge it against rule 6 (FR-SKILL-580). Run by hand, never a gate. - What a procedure may cost —
tests/skill-budget.shholds every procedure and both guides to a budget of words (NFR-SKILL-020);tests/skill-instructions.shholds each procedure to the commands, articles, files and procedures its list intests/skill-instructions/says it must name (FR-SKILL-300). - Local gate —
tools/ci_selftest.shruns the same suites CI does, andpython3 srs-dd/tools/srs_gate.pythe gate a target's hook runs;git config core.hooksPath .githookswires both intopre-commit. - Cut a release — the
srs-releaseprocedure; it decides nothing about the version or the notes on its own. - Contribution and release rules —
CONTRIBUTING.md.
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
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.

