agentleFS
CRELLIA-S-LCRELLIA-S-L/srs-dd/.claude/skills/srs-release/SKILL.md

srs-release

Skill0 starsChanged 32 days agoMITView on GitHub

Cut a release of the SRS-DD framework — choose the version with the maintainer, draft the changelog section, then run tools/srs_release.py, which dates the section, bumps the framework's version and stops — the commit and the tag are the maintainer's, made with whatever git client they use. Invoke when the user asks to cut, publish or tag a framework release. Freezing the specification is a separate act with its own command. Available only in a clone of the framework repository; a target project releases nothing of ours.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the baseline out of the log rather than out of git describe: the log is what records a baseline, and a tag for it may never have been …

    line 22
  2. Distinctive:

    Do not settle it yourself.

    line 28
  3. Distinctive:

    Leave the heading undated — the command dates it.

    line 32
  4. Distinctive:

    Read both before writing — an entry that ignores them still passes the checker and reaches the reader in pieces, because an upgrade prints …

    line 35
  5. Distinctive:

    Put them in a trailing parenthesis, as the entries already there do.

    line 39
  6. Distinctive:

    Do not assume they share a number just because both are being cut today.

    line 58
  7. Distinctive:

    Write the notes without showing them.

    line 77

≈ “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.

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

Cutting a release

The mechanics are one command. What this procedure is for is the two things the command will not decide: which number this release carries, and what its notes say.

Procedure

  1. Read what changed since the last release.

    git log --oneline $(git describe --tags --abbrev=0 --match 'v*')..HEAD
    python3 srs-dd/tools/srs_view.py --diff <newest version in specs/92-baselines.md>

    The first says what was done since the last release, the second what it did to the specification — requirements added, removed, or reworded, each named as AGENTS.md asks at its first mention, which python3 srs-dd/tools/srs_view.py --cite <ID>… prints. The maintainer settles a version number off this list in the next step, and a bare number is a lookup per line before they can judge anything (FR-SKILL-200). Read the baseline out of the log rather than out of git describe: the log is what records a baseline, and a tag for it may never have been made (INV-SPEC-040). Where release tags exist, filter for them — v* — because an unfiltered git describe answers with whichever namespace came last.

  2. Propose the version, and let the maintainer settle it. The scheme is in the Version schemes section of CONTRIBUTING.md; read what you found in step 1 against it and say which reading you used, out loud — "MINOR, because srs_view.py gained a flag a project can call".

    Do not settle it yourself. The number is a claim about compatibility, and the person who owns the project owns that claim.

  3. Draft the ## [X.Y.Z] section in CHANGELOG.md, under ### Added, ### Changed, ### Fixed and ### Upgrade notes as they apply. Leave the heading undated — the command dates it.

    The shape of that section is a contract the installer parses: it is stated in the comment at the top of CHANGELOG.md, and the ground rules in CONTRIBUTING.md say what an upgrade note owes its reader. Read both before writing — an entry that ignores them still passes the checker and reaches the reader in pieces, because an upgrade prints the first sentence of each Added and Changed entry, cut at 76 characters, and the notes section whole.

    Name the requirement identifiers the release implements — bare, and not as the citation AGENTS.md asks for everywhere else. Two reasons, and both are about this file rather than about the rule: an upgrade prints each entry on one line, so a citation inside the first sentence breaks what the reader of an upgrade sees; and a citation carries a status, which is a value that moves, while a changelog entry is a record of what a release did and nobody will ever go back and re-date it. Put them in a trailing parenthesis, as the entries already there do. Show the draft to the maintainer before committing it.

  4. Prepare it.

    python3 tools/srs_release.py X.Y.Z --dry-run
    python3 tools/srs_release.py X.Y.Z

    The dry run prints the date and the version bump — the last chance to notice that the version is not the one you meant.

  5. Hand the commit back. The command edits CHANGELOG.md, srs-dd/tools/srs_parse.py — where the version lives, the three checkers re-exporting it — and the matrix, and stops: it commits nothing and tags nothing (CON-SPEC-030). Say which files are changed for the maintainer to commit, and that the vX.Y.Z tag is theirs to make or skip.
  6. Ask whether the specification should be frozen too, if step 1 showed it moved, and follow the srs-baseline procedure if so.

    A separate act because the two are independent: a release ships what the system does, a baseline freezes what it must do, and neither number constrains the other (INV-SPEC-030). Do not assume they share a number just because both are being cut today.

  7. Report what is in the working tree, and stop. Nothing has been committed, tagged or pushed — say so plainly, and let the maintainer take it from there with the client they use.

When it refuses

Exit code 2, before writing anything: no section for that version, a section that already carries a date, or a checker reporting an error or a warning. The one exception is the checker failing on the edited files, which the command says, naming the files to restore. The baseline command is the one place the two differ: it reads the log instead of the changelog — a version already logged is one already frozen — and it stops on an error alone, because a specification still being worked off can be frozen while it should not be shipped.

Fix the cause and run it again. There is nothing to clean up: neither command has touched the history, and running either twice is safe.

What this procedure does not do

Commit. Tag. Push. Choose the version. Write the notes without showing them. The first three belong to the maintainer's git client, which may not be a console at all; the last two are their judgement.

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.