breaking change: what a tool owes at its prompt - #4
Merged
Merged
Conversation
Seven things were missing from a shipped Codechu tool, and each was found by running it rather than by reading it: `--version` did not exist; four flags had no help; there was no way to drop the chrome for a pipe or a CI log; the banner box had been one character wider than its border in every release; the banner appeared on one long command and not the other; a second tool had no entry point at all, only module paths; and its help printed the interpreter's name because `prog` was unset. None of them are hard, and none of them would have been noticed by reading the source. They are written down so the next tool starts with them rather than discovering them one release at a time — two of the seven are testable, and the section says to bind them.
There was a problem hiding this comment.
Pull request overview
Updates the tool repository standard (project-type/TOOL.md) to explicitly codify key command-line experience requirements that were previously discovered via tool usage rather than documented expectations.
Changes:
- Replaces the former §8 README-focused section with a new §8 “The command-line experience” section containing seven concrete CLI rules (version flag behavior, flag help completeness + test enforcement, quiet-mode semantics, banner construction + consistency, single entry point, and
prog/program name setting). - Renumbers the existing README skeleton section to §9 to follow the new CLI experience section.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
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
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.
Seven CLI rules for
project-type/TOOL.md, each carrying the incident that produced it:--versionmust answer without a subcommand; every flag explains itself and a test enforces it; chrome is optional but results, warnings and errors are never suppressed; the product mark is built from its content and held square by a test; the mark is consistent across long commands; one entry point named after the tool; andprogis set so help does not print the interpreter's path.All seven were found by running two Codechu tools, not by reading them. Two are mechanically testable and the section says to bind them — the help-completeness test found two more naked flags the moment it was written.
Stacked on top of #3 in intent but not in code; if #3 merges first this needs no rebase.