rubric-audit

# CLI Rubric Audit Audit a Go CLI repository against the 37signals CLI rubric (RUBRIC.md). ## Usage Run this skill in the root of a Go CLI repository to produce a gap report. ## Audit Process ### 1. Identify the CLI - Find the main binary (check `cmd/` directory or Makefile) - Build it: `make build` or `go build ./cmd/<name>` - Determine the profile: API CLI (wraps a web API) or TUI tool (full-screen interface) ### 2. Check Tier 1: Agent Contract #### 1A. Structured Output (API CLI only) - [ ] Run `<cli> --help` — does `--json` flag exist? - [ ] Pipe a command: `<cli> <cmd> | cat` — does it output JSON automatically? - [ ] Run with `--json`: verify `{ok: true, data: ...}` envelope - [ ] Run invalid command: verify `{ok: false, error: ..., code: ...}` envelope - [ ] Check for `--quiet`, `--agent`, `--ids-only`, `--count`, `--markdown` flags - [ ] Grep for `json.Decoder.UseNumber` or `json.Number` in output code #### 1B. Exit Codes - [ ] Run with bad args: should exit 1 - [ ] Access nonexistent resource: should exit 2 - [ ] Run without auth: should exit 3 - [ ] Check error types in code: look for typed error constructors #### 1C. Programmatic Discovery (API CLI only) - [ ] Run `--help --agent`: should emit structured JSON - [ ] Check responses for breadcrumbs - [ ] Look for `commands --json` or catalog command #### 1D. Authentication - [ ] Check for `APP_TOKEN` env var support - [ ] Check for keyring usage (go-keyring dependency) - [ ] Check for file fallback with 0600 perms - [ ] Check for token refresh logic ### 3. Check Tier 2: Reliability #### 2A. Surface Stability - [ ] `--version` flag exists and shows version/commit/date - [ ] Surface snapshot script or tool exists - [ ] CI runs surface compat check #### 2B. Resilience - [ ] Grep for retry/backoff logic - [ ] Check for 429/rate limit handling #### 2C. Configuration - [ ] Check config loading order (flag > env > file) - [ ] Check for HTTPS enforcement - [ ] Check for XDG directory usage ### 4. Check Tier 3: Agent Integration (API CLI only) - [ ] Check for SKILL.md and go:embed - [ ] Check for .claude-plugin/ directory - [ ] Check for --limit, --all flags on list commands - [ ] Check for --verbose, APP_DEBUG #### 3A.6: setup claude - [ ] Check for `internal/harness/` directory with Claude detection code - [ ] Run `<cli> setup claude --help` — subcommand exists - [ ] Grep for `ClaudeMarketplaceSource` or `basecamp/claude-plugins` in harness code #### 3A.7: Marketplace registration (manual, external) - [ ] This criterion requires checking the external `basecamp/claude-plugins` repo - [ ] If not locally available, flag as "cannot verify — check basecamp/claude-plugins manually" - [ ] If available: verify `.claude-plugin/marketplace.json` contains an entry with `"name": "<cli>"` ### 5. Check Tier 4: Distribution & Ecosystem - [ ] Check for .goreleaser.yaml - [ ] Check for Homebrew tap - [ ] Check for e2e tests - [ ] Check for golangci-lint config - [ ] Check for CONTRIBUTING.md, AGENTS.md ## Output Format Produce a scorecard: ``` ## Scorecard: <CLI Name> | Tier | Score | Max | |------|-------|-----| | T1: Agent Contract | X/26 | 26 | | T2: Reliability | X/16 | 16 | | T3: Agent Integration | X/13 | 13 | | T4: Distribution | X/29 | 29 | | **Total** | **X/84** | **84** | ### Critical Gaps 1. [Most impactful gap] 2. [Second gap] ... ### Recommended Priority 1. [First thing to fix — highest leverage] 2. [Second] ... ```