breaking change: the bare command introduces the tool - #5
Merged
Merged
Conversation
Both tools met a reader who typed their name with the argument parser's error on stderr and exit 2, naming an internal dest as the missing thing. That is the first contact a stranger has, and it was a failure that pointed at a variable name.
There was a problem hiding this comment.
Pull request overview
Updates the Codechu tool conventions documentation to define how a CLI tool should behave when invoked with no arguments, treating it as an introduction/help entrypoint rather than an error—aligning stdout/stderr and exit code semantics with the broader CLI contract described in the document.
Changes:
- Adds a new rule stating that bare invocation (
toolwith no args) should print the mark + command list to stdout and exit 0. - Documents the motivating incident where the argument parser surfaced internal dest names (e.g.,
cmd) and exited with code 2 on first contact.
💡 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.
One rule for
TOOL.md§8, with its incident.Typing a tool's name with no arguments is a reader asking what it is. Both Codechu tools answered with the argument parser's two-line error on stderr, exit 2 — naming
cmd,spec,paths: internal dests, not anything a stranger could act on. For a tool whose stated manner is to refuse clearly and say what is missing, that was the one place it named an implementation detail at a person, and it was the first contact.Bare invocation now means: the mark and the command list on stdout, exit 0. A wrong command or a missing flag stays an error on stderr with a non-zero exit — the distinction §2 already asks for, applied to the entry itself.