basecamp/cli/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]
...