feat(cli): group the top-level help and lead with gateway/service/doctor (#5159) - #5353
Conversation
…tor (#5159) `kirocrew --help` listed ~40 subcommands as one flat argparse block in registration order, headed by a `{chat,doctor,gateway,...}` choice blob that filled the usage line, with 17 `mcp-*` internals rendered as literal `==SUPPRESS==` rows. The three commands a new install actually needs sat in the middle of it, and nothing said how `gateway` differs from `service install` or what port either one opens. The taxonomy now lives in `cli_help.py`: ordered sections, `Start here` first with exactly gateway, service and doctor, followed by notes on the two lifetimes (foreground vs. systemd/launchd, one at a time) and on the single loopback dashboard port. argparse's own listing is suppressed and the grouped listing is rendered into the epilog. Every user-facing command registers through `cli_help.add_command`, which refuses a name that is in no section, so a new command cannot be added without appearing in the help; the section summary becomes the subparser `description`, which is what `kirocrew <cmd> --help` prints. The `mcp-*` MCP servers the agent backend spawns are dropped from the listing and from the `invalid choice: 'x' (choose from ...)` message, which otherwise answered a typo with all 17 of them. Their `choices` view filters iteration only: membership and `_name_parser_map` are untouched, so `kirocrew mcp-core` still dispatches. (cherry picked from commit 55814a8)
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Real discoverability problem, solved at the right layer: one owned taxonomy with a fail-loud registration guard and drift tests, fully reversible. The one clever piece — [DESIGN-REVIEWED] ba22bc2 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of Reading complete. I checked the contract, the intent, the full patch, and grepped the repo for consumers of every new First-Principles-Verdict: PASS A byte-identical release-branch replay of merged #5159; every item traces to the named argparse limit (flat, registration-ordered listing) and none duplicates an existing mechanism. What this change shipsIntent: let a fresh install find
Checks run: [FIRST-PRINCIPLES-REVIEWED] ba22bc2 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Cherry-picks #5159 onto
release/0.4.0for the next insider cut.git cherry-pick -x 55814a8b8— pure replay of main's squash commit, no edits. Auto-merged indocs/system-specs/modules/cli.mdandsrc/kiro_crew/cli.pywith zero conflicts; the resulting diff is byte-identical to the source commit (only blob hashes and hunk line offsets differ, because this branch'scli.pyis 13 lines shorter than main's).Groups the
kirocrew --helptop-level listing behind a single-source-of-truth taxonomy insrc/kiro_crew/cli_help.py, leading withgateway/service install/doctor, and hides themcp-*internal servers from the invalid-choice error without breaking their dispatch.Tests
test/test_cli_help.py— 11 passed on this base.test_offered_and_grouped_sets_matchis the one that matters here: it provesrelease/0.4.0's command set is fully covered byCOMMAND_GROUPS, so no command on this branch can KeyError at import.pytest test/ -k cli→ 3367 passed, 7 skipped.