feat(cli): enforce MCP tool CLI/skill parity and rich subcommand help#213
Conversation
The MCP server may become optional or expose only a subset of tools, so the CLI must stay a fully self-sufficient agent interface. - Add reverse coverage tests: every advertised MCP tool must be listed by `tracedecay tool`, invocable via `tracedecay tool <name> --help` (end-to-end through the binary), and taught by at least one bundled skill in each plugin bundle, with a documented-exceptions list for genuinely internal tools (currently empty). - Add the `inspecting-managed-skills` skill (both bundles, byte-parity) covering the four previously untaught tools: tracedecay_skill_list, tracedecay_skill_view, tracedecay_automation_run_artifact_view, and tracedecay_hermes_skill_bridge. - Give every visible top-level subcommand a when-to-use long_about and an Examples/Related after_help trailer (src/cli/help.rs), plus a top-level quick-start epilog teaching the tool discovery flow; pin the contract with parse tests so new subcommands cannot ship bare. - Teach `tracedecay tool <name> --help` to print a ready-to-copy usage line and @file guidance, and add a reserved-flags footer to the tool listing. - Update the using-the-cli skill to document the improved discovery flow (byte-identical across bundles).
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e76dc1d456
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1 participant
Summary
The MCP server may become optional (or expose only a subset of tools) in the future, so the CLI must be a fully self-sufficient agent interface. This PR closes the loop in both directions and brings CLI help up to an agent-navigable standard (modeled on the Hermes agent CLI: quick-start epilog, per-subcommand examples, related-command cross-references).
Coverage parity (tools ↔ CLI ↔ skills)
tracedecay tool <name>; 4 tools were not taught by any bundled skill:tracedecay_skill_list,tracedecay_skill_view,tracedecay_automation_run_artifact_view,tracedecay_hermes_skill_bridge.inspecting-managed-skills(both bundles, byte-identical; registered inCURSOR_PLUGIN_SKILLS,EMBEDDED_PLUGIN_FILES,CODEX_EMBEDDED_PLUGIN_FILES) covers that cluster — read-only inspection of automation-produced managed skills, run artifacts, and Hermes-owned skill state. Coverage is now 98/98 in both bundles.tests/agent_suite/tool_skill_coverage_test.rs), the complement of the skill-lint's forward skill→tool checks:tracedecay tool(discovery listing) names every tool fromget_tool_definitions();tracedecay tool <name> --helpsucceeds end-to-end through the shipped binary for every tool;SKILL_COVERAGE_EXCEPTIONSlist for genuinely internal tools (currently empty) plus a guard that exceptions reference real tools.Rich CLI help
src/cli/help.rs: every visible top-level subcommand now has a when-to-uselong_aboutand anExamples:/Related:/Notes:after_helptrailer with real flag combinations (all example flags verified against the actual tool schemas / clap args).tracedecay --helpgains a quick-start epilog that teaches the MCP tool discovery flow (list → per-tool help → invoke with--args/@file) and the--json/ project-scoping conventions.tracedecay tool <name> --helpnow prints a ready-to-copyUsage:line with the tool's required flags plus@fileguidance; thetracedecay toollisting gained a reserved-flags footer.every_visible_top_level_subcommand_ships_rich_help,every_visible_nested_subcommand_has_a_purpose_line,top_level_help_teaches_the_tool_discovery_flow.Skill update
using-the-cli(both bundles, byte-identical) documents the improved discovery flow: per-tool usage lines, and that every subcommand's--helpcarries Examples/Related sections.New-skill frontmatter follows the incoming plugin-validation lint rules (kebab-case name, trigger-first description ≥50 chars, no angle brackets, terminal punctuation, unique description, within the 6,000-char metadata budget).
Test plan
cargo check --all-targets/cargo clippy --all-targets— clean (only pre-existing vendoredlibsqlwarnings)cargo fmtcargo test --test agent_suite— 356 passed (includesplugin_skill_contract_test, codex/cursor byte-parity tests, and the 4 new coverage tests)cargo test --bin tracedecay parse_tests— 34 passed (includes 3 new help-contract tests)cargo test --lib hooks(36),--lib agents(136),--lib mcp::tools(46),--bin tracedecay tool_command(18)cargo test --test core_cli_suite cli_help— 3 passedtracedecay --help,tracedecay tool --help,tracedecay tool search --help,tracedecay memory --helprender the new trailers; all 98tracedecay tool <name> --helpinvocations succeed