Self-describing CLI: --help --agent, embedded skills, doctor integration by jeremy · Pull Request #164

Self-describing CLI: --help --agent, embedded skills, doctor integration by jeremy · Pull Request #164 · basecamp/basecamp-cli

AI review requested due to automatic review settings

February 28, 2026 02:44

The CLI now describes itself to agents at runtime instead of relying on
static reference files. Three complementary discovery mechanisms:

- `basecamp skill` prints the embedded SKILL.md from the binary
- `basecamp <cmd> --help --agent` emits structured JSON (flags, notes,
  subcommands) for any command
- `basecamp commands --json` provides the full catalog

Migrated gotchas and cross-references from 18 reference files into
Annotations["agent_notes"] on 25 cobra commands. These surface in the
notes field of --help --agent JSON output.

Added internal/harness package for Claude Code detection and plugin
health checks, wired into doctor (check 12, silent when ~/.claude/
absent). Hardened hooks: negative failure guard in post-commit-check,
jq requirement in session-start, dropped bare #12345 pattern.

SKILL.md trimmed to invariants + decision trees + discovery pointers.
Deleted references/, install-skills.sh (obsolete — embedded skills,
claude plugin install is the distribution path).

Copilot AI review requested due to automatic review settings

February 28, 2026 05:25

- Narrow hook failure regex: strip git success line before scanning so
  commit subjects like "Fix failed login" don't false-positive
- Handle fmt.Fprint error return in skill command
- Use cmd.OutOrStdout() instead of os.Stdout in emitAgentHelp

- session-start.sh: use --version flag instead of nonexistent version
  subcommand
- doctor_test.go: add TestCheckClaudeIntegration covering the harness
  integration path