A reusable engineering playbook for building Go CLI tools on top of APIs. It provides opinionated defaults for CLI output contracts, layered testing (unit / BDD / integration), GitHub Actions CI/release workflows, and release naming consistency.

Go API-to-CLI projects tend to accumulate the same issues across repos:

• GitHub Actions workflows drift apart over time
• CLI output breaks scripts and automation silently
• Release artifact names get out of sync with docs and download commands
• Pre-commit and test strategies are set up inconsistently

This playbook captures those lessons into templates, scripts, and audit tools so they only need to be solved once.

It also includes an OpenAPI-first path so a new CLI can be planned and tested from only openapi.json.

assets/templates/       # Copy-ready templates
  prek.toml             #   Pre-commit gate config
  release-naming.env    #   Single source of truth for naming
  scripts/
    next-version.sh     #   Tag-based version calculation

references/             # Decision guides and checklists
  github-actions-comparison.md
  github-actions-adoption-checklist.md
  openapi-first-delivery.md
  release-packaging-strategies.md
  prek-precommit.md

scripts/                # Bootstrap and audit tools
  init-prek.sh          #   Set up prek in a target repo
  init-release-naming.sh#   Bootstrap release-naming.env
  openapi-bootstrap.sh  #   Build command/test plan from openapi.json
  print-release-download.sh  # Generate correct download commands
  audit-workflows.sh    #   Detect workflow config drift
  audit-release-naming.sh   # Detect naming contract drift

SKILL.md                # Claude Code skill definition

Apply the playbook to a target Go CLI repository:

# 1. Bootstrap the release naming contract
./scripts/init-release-naming.sh /path/to/your-repo

# 2. If starting from API docs only, generate plan artifacts
./scripts/openapi-bootstrap.sh /path/to/openapi.json /path/to/your-repo/docs/openapi

# 3. Initialize core project files (includes prek.toml)
./scripts/init-project-files.sh /path/to/your-repo

# 4. Set up pre-commit gate and hooks
cd /path/to/your-repo
prek validate-config
prek install --install-hooks
prek run --all-files

# 5. Copy workflow templates into your repo and replace placeholders

# 6. Audit for drift
./scripts/audit-workflows.sh /path/to/your-repo
./scripts/audit-release-naming.sh /path/to/your-repo

# 7. Validate locally
go test ./...

CLI Output — Parseable output modes (--json, --plain) are mandatory. Human hints go to stderr. Exit codes must be stable and script-safe.

Testing — Run prek run --all-files before tests. Unit tests via go test ./.... BDD paths must be explicit. Integration tests are opt-in (tagged and credential-gated).

CI/CD — CI runs formatting, vet/lint, tests, and build. Release supports PR comment (!release patch|minor|major) and manual dispatch. Tag creation dispatches release-on-tag.yml, which builds artifacts, generates changelog, and publishes GitHub Release.

Release Naming — CLI_NAME, BINARY_NAME, TAG_PREFIX, ARTIFACT_GLOB, and BUILD_TARGET live in release-naming.env as the single source of truth. No hardcoding elsewhere.

This repo doubles as a Claude Code skill. Add it to your workspace and Claude will follow the playbook when building Go CLI projects.

MIT