Structured positional-arg metadata in help system

[jeremy]

Summary

• Parses Use: strings into structured ArgInfo metadata (name, required, variadic, description, kind) with mechanical humanization and no hand-maintained lookup table
• Agent help (--help --agent) now includes an args JSON field; human help renders an ARGUMENTS section
• Doc contract tests validate positional args across key commands and verify SKILL.md Quick Reference against the live command tree
• Surface snapshot script emits ARG lines with zero-padded positional index

Test plan

• make test — all Go tests pass (0 failures)
• make test-e2e — all e2e tests pass (0 failures)
• ./bin/basecamp todo --help --agent | jq '.args' — shows structured content arg
• ./bin/basecamp projects --help --agent | jq 'has("args")' — false (no args)
• ./bin/basecamp show --help — ARGUMENTS section with [type] and <id|url>
• ./bin/basecamp people --help — no ARGUMENTS (not runnable)
• ./bin/basecamp webhooks create --help --agent | jq '.args[].name' — "url" only ([flags] stripped)
• ./bin/basecamp schedule --help --agent | jq '.args // empty' — absent ([action] stripped)

---

Summary by cubic

Add structured parsing of positional args and surface them in both agent (--help --agent) and human help. Also add clear missing-arg behavior: friendly help in TTY, structured JSON errors in agent/machine mode.

• New Features

  • Parse positional args into ArgInfo (name, required, variadic, description, kind) with humanization and kind inference; supports Annotations["arg_schema"]; skips non-runnable commands; strips [flags] and [action].
  • Agent help now includes an args JSON field; omitted when empty.
  • Human help renders an ARGUMENTS section with aligned bracket notation and optional/variadic hints.
  • Missing-arg UX: missingArg, noChanges, and isMachineOutput helpers show cmd.Help() (exit 0) in TTY, or return structured JSON errors naming the specific arg in agent/machine mode.
  • Doc contract tests validate positional args for key commands and verify SKILL.md Quick Reference against the live command tree.
  • scripts/check-cli-surface.sh now emits zero-padded ARG lines to preserve positional order in the CLI surface snapshot.

• Bug Fixes

  • Remove a stray merge conflict marker in helpers.

^{Written for commit 0f52333. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/cli/args.go">

<violation number="1" location="internal/cli/args.go:120">
P2: `strings.Contains(lower, "id")` matches substrings within larger words (e.g., "video" → "identifier", "update" → "date"). Split the name into tokens on `|`/`-`/`_` delimiters and match whole tokens instead.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Copilot]

Pull request overview

Adds structured positional-argument metadata to the CLI help system by parsing Cobra Use: strings into ArgInfo, exposing that structure in both human help output and --help --agent JSON, and introducing doc/contract tests to keep help/docs aligned with the live command tree.

Changes:

• Parse positional args from Use: into structured ArgInfo (with optional annotation override) and render an ARGUMENTS section in styled help.
• Extend --help --agent JSON output with an args field and update the CLI surface snapshot script to emit ARG records.
• Add contract tests for key positional-arg declarations and for SKILL.md Quick Reference command paths.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/check-cli-surface.sh	Emits ARG lines (with padded positional index) from agent-help JSON.
internal/commands/doc_contract_test.go	Adds doc/CLI contract tests for positional args and SKILL.md command references.
internal/cli/root.go	Extends agent-help JSON schema with args.
internal/cli/help_test.go	Adds coverage for agent args JSON + human ARGUMENTS section rendering behavior.
internal/cli/help.go	Renders an ARGUMENTS section for runnable commands with parsed positional args.
internal/cli/args_test.go	Adds unit tests for parsing, display, humanization, and kind inference.
internal/cli/args.go	Implements ArgInfo, ParseArgs, ArgDisplay, and arg humanization/kind inference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.