Skip to content

Commit 05b991d

Browse files
jeremyjeremy
committed
Add agent skills and prompts
skills/rubric-audit/SKILL.md — agent skill for scoring any CLI prompts/close-gap.md — agent prompt for closing a specific rubric gap prompts/seed-cli.md — agent prompt for bootstrapping a new CLI
1 parent d763c19 commit 05b991d

File tree

3 files changed

+242
-0
lines changed

3 files changed

+242
-0
lines changed

‎prompts/close-gap.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Close a Rubric Gap
2+
3+
You are closing a specific gap in a Go CLI's compliance with the 37signals CLI rubric.
4+
5+
## Input
6+
7+
- **Criterion ID**: e.g., "1A.1" (--json flag on every command)
8+
- **CLI repo**: The repository you're working in
9+
- **Current state**: What exists today
10+
11+
## Process
12+
13+
1. Read RUBRIC.md to understand the criterion requirements
14+
2. Read the reference implementation in basecamp-cli
15+
3. Assess the current state of the target CLI
16+
4. Implement the minimum change to meet the criterion
17+
5. Add or update tests
18+
6. Verify the criterion is met
19+
20+
## Shared Packages
21+
22+
If the gap can be closed by adopting a shared package, prefer that over writing new code:
23+
24+
| Gap Area | Package | Import |
25+
|----------|---------|--------|
26+
| Output envelope, formats, exit codes | `output` | `github.com/basecamp/cli/output` |
27+
| Credential storage (keyring + file) | `credstore` | `github.com/basecamp/cli/credstore` |
28+
| PKCE helpers | `pkce` | `github.com/basecamp/cli/pkce` |
29+
| OAuth callback server | `oauthcallback` | `github.com/basecamp/cli/oauthcallback` |
30+
| CLI surface snapshots | `surface` | `github.com/basecamp/cli/surface` |
31+
32+
## Implementation Patterns
33+
34+
### Adding --json flag (1A.1)
35+
Add a persistent `--json` flag to the root command. In your output wrapper, check the flag and set `FormatJSON` accordingly.
36+
37+
### Adding structured output (1A.3-4)
38+
Import `github.com/basecamp/cli/output` and use `Writer.OK()` / `Writer.Err()` in every command's RunE.
39+
40+
### Adding exit codes (1B.1)
41+
Use `output.AsError(err).ExitCode()` in your root command's error handler. Map all errors through typed constructors.
42+
43+
### Adding --help --agent (1C.1)
44+
Detect `--help --agent` flag combination. When both are set, emit a JSON object with: name, description, flags (name, type, default, description), subcommands (name, description).
45+
46+
### Adding keyring (1D.3)
47+
Replace file-only credential storage with `credstore.NewStore()`. Set ServiceName to your app name, DisableEnvVar to `APP_NO_KEYRING`.
48+
49+
### Adding surface stability (2A.2-3)
50+
Use the `surface` package to generate snapshots. Commit the baseline. Add the `surface-compat` GitHub Action to CI.

‎prompts/seed-cli.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Bootstrap a New CLI from Seed
2+
3+
You are creating a new Go CLI for a 37signals product using the seed templates.
4+
5+
## Input
6+
7+
- **App name**: e.g., "fizzy", "hey"
8+
- **API base URL**: e.g., "https://fizzy.37signals.com"
9+
- **Auth model**: OAuth+PKCE, bearer token (PAT), or purchase token
10+
11+
## Process
12+
13+
1. Create the repository structure:
14+
```
15+
<app>-cli/
16+
├── cmd/<app>/main.go
17+
├── internal/
18+
│ ├── auth/
19+
│ ├── commands/
20+
│ ├── config/
21+
│ └── output/
22+
├── e2e/
23+
├── skills/
24+
├── .claude-plugin/
25+
├── go.mod
26+
├── Makefile
27+
├── .goreleaser.yaml
28+
├── .golangci.yml
29+
├── AGENTS.md
30+
├── CONTRIBUTING.md
31+
└── README.md
32+
```
33+
34+
2. Initialize go.mod with `github.com/basecamp/<app>-cli`
35+
36+
3. Add shared dependencies:
37+
```
38+
go get github.com/basecamp/cli/output
39+
go get github.com/basecamp/cli/credstore
40+
go get github.com/basecamp/cli/pkce
41+
go get github.com/spf13/cobra
42+
```
43+
44+
4. Copy and customize seed templates:
45+
- `seed/Makefile` → `Makefile` (update BINARY_NAME)
46+
- `seed/.goreleaser.yaml` → `.goreleaser.yaml` (update ProjectName)
47+
- `seed/.golangci.yml` → `.golangci.yml`
48+
- `seed/AGENTS.md.tmpl` → `AGENTS.md` (fill in app name)
49+
- `seed/CONTRIBUTING.md.tmpl` → `CONTRIBUTING.md` (fill in app name)
50+
- `seed/internal/output/output.go` → `internal/output/output.go`
51+
- `seed/internal/auth/auth.go` → `internal/auth/auth.go` (customize service name, env vars)
52+
- `seed/.claude-plugin/` → `.claude-plugin/` (customize)
53+
- `seed/skills/SKILL.md.tmpl` → `skills/SKILL.md` (customize)
54+
55+
5. Create the root command in `cmd/<app>/main.go`:
56+
- Import `github.com/spf13/cobra`
57+
- Add persistent flags: --json, --quiet, --agent, --verbose, --ids-only, --count, --markdown
58+
- Wire up output.Writer with format resolution
59+
- Add --help --agent handler
60+
61+
6. Create auth commands: `<app> auth login`, `<app> auth logout`, `<app> auth status`
62+
63+
7. Create first resource command as an example
64+
65+
8. Run `make check` to verify everything works
66+
67+
## Auth Model Configuration
68+
69+
### OAuth + PKCE
70+
```go
71+
import (
72+
"github.com/basecamp/cli/credstore"
73+
"github.com/basecamp/cli/pkce"
74+
"github.com/basecamp/cli/oauthcallback"
75+
)
76+
```
77+
78+
### Bearer Token (PAT)
79+
```go
80+
import "github.com/basecamp/cli/credstore"
81+
// No PKCE or callback needed — user provides token directly
82+
```
83+
84+
### Purchase Token (HMAC)
85+
```go
86+
import "github.com/basecamp/cli/credstore"
87+
// Custom verification logic — credstore handles storage only
88+
```

‎skills/rubric-audit/SKILL.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
name: rubric-audit
3+
description: Audit a Go CLI against the 37signals CLI rubric
4+
---
5+
6+
# CLI Rubric Audit
7+
8+
Audit a Go CLI repository against the 37signals CLI rubric (RUBRIC.md).
9+
10+
## Usage
11+
12+
Run this skill in the root of a Go CLI repository to produce a gap report.
13+
14+
## Audit Process
15+
16+
### 1. Identify the CLI
17+
18+
- Find the main binary (check `cmd/` directory or Makefile)
19+
- Build it: `make build` or `go build ./cmd/<name>`
20+
- Determine the profile: API CLI (wraps a web API) or TUI tool (full-screen interface)
21+
22+
### 2. Check Tier 1: Agent Contract
23+
24+
#### 1A. Structured Output (API CLI only)
25+
- [ ] Run `<cli> --help` — does `--json` flag exist?
26+
- [ ] Pipe a command: `<cli> <cmd> | cat` — does it output JSON automatically?
27+
- [ ] Run with `--json`: verify `{ok: true, data: ...}` envelope
28+
- [ ] Run invalid command: verify `{ok: false, error: ..., code: ...}` envelope
29+
- [ ] Check for `--quiet`, `--agent`, `--ids-only`, `--count`, `--markdown` flags
30+
- [ ] Grep for `json.Decoder.UseNumber` or `json.Number` in output code
31+
32+
#### 1B. Exit Codes
33+
- [ ] Run with bad args: should exit 1
34+
- [ ] Access nonexistent resource: should exit 2
35+
- [ ] Run without auth: should exit 3
36+
- [ ] Check error types in code: look for typed error constructors
37+
38+
#### 1C. Programmatic Discovery (API CLI only)
39+
- [ ] Run `--help --agent`: should emit structured JSON
40+
- [ ] Check responses for breadcrumbs
41+
- [ ] Look for `commands --json` or catalog command
42+
43+
#### 1D. Authentication
44+
- [ ] Check for `APP_TOKEN` env var support
45+
- [ ] Check for keyring usage (go-keyring dependency)
46+
- [ ] Check for file fallback with 0600 perms
47+
- [ ] Check for token refresh logic
48+
49+
### 3. Check Tier 2: Reliability
50+
51+
#### 2A. Surface Stability
52+
- [ ] `--version` flag exists and shows version/commit/date
53+
- [ ] Surface snapshot script or tool exists
54+
- [ ] CI runs surface compat check
55+
56+
#### 2B. Resilience
57+
- [ ] Grep for retry/backoff logic
58+
- [ ] Check for 429/rate limit handling
59+
60+
#### 2C. Configuration
61+
- [ ] Check config loading order (flag > env > file)
62+
- [ ] Check for HTTPS enforcement
63+
- [ ] Check for XDG directory usage
64+
65+
### 4. Check Tier 3: Agent Integration (API CLI only)
66+
67+
- [ ] Check for SKILL.md and go:embed
68+
- [ ] Check for .claude-plugin/ directory
69+
- [ ] Check for --limit, --all flags on list commands
70+
- [ ] Check for --verbose, APP_DEBUG
71+
72+
### 5. Check Tier 4: Distribution & Ecosystem
73+
74+
- [ ] Check for .goreleaser.yaml
75+
- [ ] Check for Homebrew tap
76+
- [ ] Check for e2e tests
77+
- [ ] Check for golangci-lint config
78+
- [ ] Check for CONTRIBUTING.md, AGENTS.md
79+
80+
## Output Format
81+
82+
Produce a scorecard:
83+
84+
```
85+
## Scorecard: <CLI Name>
86+
87+
| Tier | Score | Max |
88+
|------|-------|-----|
89+
| T1: Agent Contract | X/21 | 21 |
90+
| T2: Reliability | X/14 | 14 |
91+
| T3: Agent Integration | X/9 | 9 |
92+
| T4: Distribution | X/19 | 19 |
93+
| **Total** | **X/63** | **63** |
94+
95+
### Critical Gaps
96+
1. [Most impactful gap]
97+
2. [Second gap]
98+
...
99+
100+
### Recommended Priority
101+
1. [First thing to fix — highest leverage]
102+
2. [Second]
103+
...
104+
```

0 commit comments

Comments
 (0)