srs-build
Skill0 starsChanged 33 days agoMITView on GitHub
Build over as many passes as it takes — the list of what has to exist written before the first pass, one requirement's worth of change per pass with its tests, the whole set of checks read rather than glanced at, every failure classified before it is touched, and the loop closed in the same set of edits. Invoke when a change will not be finished in one pass, or when a build has begun to go round in circles. One pass through the loop is the `srs` procedure.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- 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-checkSkill
- srs-commitSkill
- srs-harvestSkill
- srs-initSkill
- srs-newSkill
- srs-pageSkill
- srs-releaseSkill
- srs-reviewSkill
- srsSkill
- srs-upgradeSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Distinctive: line 21
Say what the work is worth in passes: before the first one, so that running out is a decision and not a surprise.
- Distinctive: line 34
Never weaken a check to get past it: No deleted or skipped test, no broadened exception, no loosened assertion, no rule priced down to …
- Very specific: line 52
Commit — that is .claude/skills/srs-commit/SKILL.md.
- Distinctive: line 54
Run anything the maintainer did not approve.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
<!-- Copyright (c) 2026 CRELLIA S.L. — part of SRS-DD, distributed under the MIT License -->Building over several passes
One pass is .claude/skills/srs/SKILL.md: the requirements the change belongs to, the code, the decisions it settled, the loop closed, the checker.
This procedure is what repeating that pass needs, and it begins with the thing a repeated pass loses first — what the work was for.
Before the first pass
Write the list of what has to exist when this is over.
One line per behaviour, each naming a requirement and what it obliges, taken from the requirements in scope and not from the files you expect to touch: a list of files is a plan, and a plan cannot be finished.
A behaviour the task implies and no requirement states is authored first (.claude/skills/srs-new/SKILL.md) or declared out of scope on the list itself; building it unwritten is the one thing this procedure will not do.
This list is half the stop condition. The checks are the other half, and a green set certifies what it covers, which may be a third of the work.
Say what the work is worth in passes before the first one, so that running out is a decision and not a surprise.
Each pass
One requirement's worth of change, with its tests in the same pass: bundled changes hide which one worked.
- Build it —
.claude/skills/srs/SKILL.md, whole, including the step that closes the loop: the status, thecodeandtestsfields and the annotations in the same set of edits as the code. A pass that leaves the loop open is a pass somebody does twice. - Run the whole set, not what you touched —
.claude/skills/srs-check/SKILL.mdderives it from the requirements the change touched and offers exactly that; nothing runs unasked, which is SRS-DD-ART-030 ofsrs-dd/method.md. Fixes break neighbours, which is the reason this repeats at all. - Classify every failure before touching it: caused by this pass, standing before it, could not run at all — a missing dependency, no network, a tool that is not there — or unsteady, which means it passed and failed against files nobody changed, confirmed by running it alone two or three times. A check that never ran is never reported as passing, and an unsteady one is never quieted by loosening it.
- Read the green as a claim too. A suite that collected nothing, a filter that matched nothing, an assertion in a branch nothing reaches, a test that still passes when the behaviour it covers is deleted. That last one is the check on the test itself, and
.claude/skills/srs-audit/SKILL.mdsays what makes it worth running. - Read the documentation on a failure and on a success alike. On a failure the error says what broke and the document says what was supposed to happen; editing until the message disappears produces something wrong more quietly. On a success read the contract anyway, at the version installed rather than the newest one. Where the change touched the specification, that document is
srs-dd/standard.mdand the standard of whichever layer it touched. - One line of log per pass: what changed, what the run said, what the document settled, what is still open. At the twelfth pass that line is what stands between you and doing the fourth again.
Never weaken a check to get past it. No deleted or skipped test, no broadened exception, no loosened assertion, no rule priced down to quiet it. A check that is genuinely wrong stays red and the report says why.
When to stop
Stable is stricter than green: every line of the list is there and reached by a check, the whole set passes twice running against files nobody touched between the runs — the second time from a clean state, with whatever the checks cached or built thrown away first — and every status, code and tests field says what is true now.
Stable is the condition for review and not a finished build: every line of it was judged by whoever wrote the code.
Stop early and report where the same check fails three times after genuinely different attempts, where a fix brings back something already fixed, where two passes running do not reduce what is open, or where what is left is the maintainer's decision. No further pass clears any of those.
Then hand the work on rather than calling it done: .claude/skills/srs-check/SKILL.md for what the requirements themselves ask, and the inspections it names are not finished by a green suite.
What makes it done is the pass somebody else's means reaches — .claude/skills/srs-review/SKILL.md, which closes on two consecutive passes that found nothing by different means.
Report
Against the list, not against the checks: what is there and what is not; what was built, naming each requirement as AGENTS.md asks at its first mention; what the checks said, with anything skipped and why; what the documentation settled; what is open, each with where it was seen; and how many passes it took of how many the work was worth.
What this procedure does not do
Commit — that is .claude/skills/srs-commit/SKILL.md.
Author a requirement — that is srs-new, and a build that needs one has stopped being a build.
Run anything the maintainer did not approve.
Decide that a red check is acceptable.
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.

