Skip to content

docs(agents): allow N-level command paths in CLI contract - #712

Merged
axisrow merged 1 commit into
mainfrom
docs/680-agents-md-three-level-commands
Aug 3, 2026
Merged

docs(agents): allow N-level command paths in CLI contract#712
axisrow merged 1 commit into
mainfrom
docs/680-agents-md-three-level-commands

Conversation

@axisrow

@axisrow axisrow commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

  • AGENTS.md described the canonical CLI shape as exactly direct <group> <command>, which is stale: PR refactor: recurse the command-tree walkers #674 made three command-tree walkers recursive specifically to support nested groups, and PR feat(masters): add direct masters adimages get #675-feat(masters): add direct masters adimages delete/set #677 shipped masters adimages get|add|delete|set as a real three-level leaf.
  • The stale wording already produced a false P1 from a review bot on PR feat(masters): add direct masters adimages get #675, citing AGENTS.md L15-19 as evidence that the new nested group broke the contract (triaged and rejected there, but the underlying wording remained misleading for future reviewers).
  • Reworded the contract to describe a path of one or more group segments plus a leaf command name, each segment validated by the same group/command rules (tests/test_cli_contract.py's GROUP_NAME_RE/COMMAND_NAME_RE only ever validated segment names, never tree depth), and added direct masters adimages get 123 as a documented example of the existing pattern.

Test plan

  • pytest tests/test_cli_contract.py tests/test_smoke_matrix.py -q — 29 passed
  • python -m direct_cli.cli masters adimages get --help — confirmed the example command's real signature (positional CAMPAIGN_ID, no --wizard-id flag)

Closes #680

🤖 Generated with Claude Code

AGENTS.md described the canonical shape as exactly `direct <group>
<command>`, which no longer matches the repo: PR #674 made three
command tree walkers recursive specifically to support nested groups,
and PR #675-#677 shipped `masters adimages get|add|delete|set` as a
real three-level leaf. The stale wording already produced a false P1
from Codex on PR #675, citing these exact lines as a contract
violation.

Reword the contract to describe a path of one or more group segments
plus a leaf command, each segment validated the same way, and add
`masters adimages` as a documented example of the existing pattern.

Closes #680
@axisrow

axisrow commented Aug 3, 2026

Copy link
Copy Markdown
Owner Author

🔍 Local review (cycle 1) — round 3321ef62-f2da-48c0-b5ed-788198aad30a

Reviewed locally (/review + Codex companion), no bots pinged.

Verdict Reviewer Finding Location
CLEAN claude No critical issues; docs wording matches the recursive _subcommands() walker and GROUP_NAME_RE/COMMAND_NAME_RE validation already in the codebase AGENTS.md
CLEAN codex No critical blocker; docs-only change matches the already-shipped nested Click command, focused contract/registration checks passed AGENTS.md

Totals: 0 FIX, 0 SKIP, 0 UNVERIFIED. Both reviewers approve.

@axisrow
axisrow merged commit bb93156 into main Aug 3, 2026
5 of 7 checks passed
@axisrow
axisrow deleted the docs/680-agents-md-three-level-commands branch August 3, 2026 20:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant