Write down how to add a command and bump versions - #45
Merged
Merged
Conversation
In the 2026-09-29 documentation audit, fresh agents learned which files a new command or a version bump touches by failing CI. The CLI trial missed the Skills copy of the package allowlist, and it concluded that comparing a local Plan with the Service needed a new endpoint. The routes the CLI calls were documented only in the private Service repository, which public CLI docs cannot link. commands.md now owns an add-a-command checklist, checked against the source and tests, and a Service endpoints table. The table defines the Head and the "sha256:<hex>" ETag that the CLI parses. Every request now takes its method and path from one SERVICE_ROUTES entry in src/api-response.js. A test compares those entries with the table and requires each one to be used. Adding a route without a row, or keeping a row after its request is gone, therefore fails CI. `npm version <x.y.z> --no-git-tag-version --ignore-scripts=false` now updates every version field. npm writes package.json and the lockfile, and the version lifecycle runs scripts/sync-version.js to update release/compatibility.json. The last flag is needed because .npmrc sets ignore-scripts=true, which npm also applies to version scripts. The sync script is a dry run unless given --apply. Tests no longer restate the API range. Fixtures that the CLI checks against its Plan format and Rails profile read them from release/compatibility.json and src/compilation-artifact.js. A Plan contract bump then edits the declaration, the source constants, and the docs that name them, not test literals. The plan status fixture keeps its literal target because a Service-computed digest covers it. The format check still requires the declaration to equal the one format the CLI writes and accepts, because the Service's release check trusts the declaration.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Step 7 of the 2026-09-29 agent-documentation audit. In the graded trial, a fresh agent missed Skills' copy of the package allowlist. It also wrongly concluded that comparing a local Plan with the Service needed a new endpoint, because the routes the CLI calls were documented only in the private Service repo.
docs/commands.mdadditions:sha256:<hex>ETag the CLI parses.SERVICE_ROUTESentry insrc/api-response.js. A test compares those entries with the table and requires each one to be used. Adding a route without a row, or keeping a row after its request is gone, fails CI.npm version <x.y.z> --no-git-tag-version --ignore-scripts=falseupdates every version field;scripts/sync-version.jsupdatesrelease/compatibility.jsonand runs dry unless given--apply.release/compatibility.jsonandsrc/compilation-artifact.js.Docs: updated docs/commands.md, docs/README.md, RELEASING.md, README.md and AGENTS.md.
Note for Skills.
package.jsonnow has aversionscript, and it is an input to the runtime digest that firstdraft/skills pins. That digest changes the next time Skills bundles this CLI.Validation
npm run check: 219/219npm audit: 0 vulnerabilitiesnpm version 0.8.1updated every version field, andnpm run checkpassed afterwards.Review
cross-review 0.7.3, max effort, with firstdraft's
docs/review-focus.mdas the focus file. Verdict: Approve, no findings (sessione08433d7-95bb-469d-9e43-83c67eb42a7b). An adversarial verifier found 5 issues first; all were fixed, including the endpoint test missing the cancel route.