name	go-api-cli-playbook
description	Build and standardize Go API-to-CLI projects with scaffold, CI, release workflows, Go-specific engineering defaults, and agent-friendly CLI UX contracts.

Go API CLI Playbook

Use this skill when a Go project is converting an API into a CLI and needs production-grade engineering defaults.

Start here: load references/agent-friendly-cli.md and complete the Phase 1 design contract before writing any Go code.

Outcomes

Complete project scaffold (Makefile, .gitignore, README).
OpenAPI-first delivery path from only openapi.json.
Repeatable testing: unit + BDD + opt-in integration.
Reusable GitHub Actions templates for CI and release.
Release flow: PR comment !release [patch|minor|major], manual dispatch, multi-platform artifacts, changelog notes.

Workflow

Steps 1–8 are mandatory bootstrap. Do NOT implement feature commands until scaffold files exist, prek hooks are installed, and make build passes on a skeleton binary.

Load references/agent-friendly-cli.md. Freeze command taxonomy, output samples, and behavior semantics before writing code.
(OpenAPI-driven) Run scripts/openapi-bootstrap.sh <openapi.json> <output-dir> to produce operations inventory, command plan, and test matrix.
Create release-naming.env — run scripts/init-release-naming.sh <repo-dir> or copy from assets/templates/release-naming.env. Replace all your-cli placeholders. Verify all 5 variables are set.
Initialize project files — run scripts/init-project-files.sh <repo-dir>. Replaces placeholders in Makefile, README, prek.toml to match release-naming.env.
Scaffold Go packages — cmd/<cli>/main.go, internal/cmd/root.go, internal/client/client.go, internal/model/, internal/output/output.go, tests/bdd/. Run go mod init and go mod tidy. Checkpoint: make build must pass before continuing. See references/go-code-architecture.md.
Apply GitHub Actions — copy go-ci.yml, release-command.yml, and one release-on-tag workflow from assets/templates/.github/workflows/. Customize BUILD_TARGET to match release-naming.env.
Initialize pre-commit gate — run scripts/init-prek.sh <repo-dir> if prek.toml is missing.
Run prek validate-config, prek install --install-hooks, prek run --all-files. Confirm .git/hooks/pre-commit and .git/hooks/pre-push exist.
Implement commands, client methods, and models.
Validate: go test ./..., BDD command, make ci.
Run scripts/audit-workflows.sh and scripts/audit-release-naming.sh. Fix all findings.
(Agent skill) Scaffold skills/<name>/SKILL.md with command mapping, usage examples, and error handling rules.
Run references/delivery-checklist.md — every item must pass before done.

Required CLI Contract

Output modes --json and --plain are mandatory.
--jq via itchyny/gojq only — never shell out.
--token falls back to <SERVICE>_API_TOKEN env var.
Hints and progress go to stderr, not stdout.
Connectivity check uses status command (not auth check).
list commands must have ls alias.
Command names match API terminology — no CRUD genericization.
Exit codes: 0 success, 1 error, 2 auth failure (401/403), 3 not found (404).

What To Load

references/agent-friendly-cli.md — CLI UX design contract, output format, help system, agent-friendly review checklist
references/go-code-architecture.md — Go code patterns and annotated examples
references/delivery-checklist.md — full delivery verification checklist
references/github-actions-comparison.md — side-by-side lessons and pitfalls
references/github-actions-adoption-checklist.md — rollout checklist
references/openapi-first-delivery.md — OpenAPI-only delivery flow
references/release-packaging-strategies.md — packaging strategy and naming mapping
references/prek-precommit.md — prek setup and commands
assets/templates/.github/workflows/ — copy-ready workflow files
assets/templates/Makefile, assets/templates/version.go — standardized project structure
assets/templates/scripts/next-version.sh — tag versioning script
assets/templates/release-naming.env — naming contract template
assets/templates/prek.toml — ready prek config
scripts/print-release-download.sh — download command generator
scripts/openapi-bootstrap.sh — OpenAPI bootstrap
scripts/init-project-files.sh — project files bootstrap
scripts/init-prek.sh — prek bootstrap
scripts/init-release-naming.sh — naming contract bootstrap
scripts/audit-release-naming.sh — naming drift audit

Go API CLI Playbook

Use this skill when a Go project is converting an API into a CLI and needs production-grade engineering defaults.

Start here: load references/agent-friendly-cli.md and complete the Phase 1 design contract before writing any Go code.

Outcomes

Complete project scaffold (Makefile, .gitignore, README).

OpenAPI-first delivery path from only openapi.json.

Repeatable testing: unit + BDD + opt-in integration.

Reusable GitHub Actions templates for CI and release.

Release flow: PR comment !release [patch|minor|major], manual dispatch, multi-platform artifacts, changelog notes.

Workflow

Steps 1–8 are mandatory bootstrap. Do NOT implement feature commands until scaffold files exist, prek hooks are installed, and make build passes on a skeleton binary.

Load references/agent-friendly-cli.md. Freeze command taxonomy, output samples, and behavior semantics before writing code.

(OpenAPI-driven) Run scripts/openapi-bootstrap.sh <openapi.json> <output-dir> to produce operations inventory, command plan, and test matrix.

Create release-naming.env — run scripts/init-release-naming.sh <repo-dir> or copy from assets/templates/release-naming.env. Replace all your-cli placeholders. Verify all 5 variables are set.

Initialize project files — run scripts/init-project-files.sh <repo-dir>. Replaces placeholders in Makefile, README, prek.toml to match release-naming.env.

Scaffold Go packages — cmd/<cli>/main.go, internal/cmd/root.go, internal/client/client.go, internal/model/, internal/output/output.go, tests/bdd/. Run go mod init and go mod tidy. Checkpoint: make build must pass before continuing. See references/go-code-architecture.md.

Apply GitHub Actions — copy go-ci.yml, release-command.yml, and one release-on-tag workflow from assets/templates/.github/workflows/. Customize BUILD_TARGET to match release-naming.env.

Initialize pre-commit gate — run scripts/init-prek.sh <repo-dir> if prek.toml is missing.

Run prek validate-config, prek install --install-hooks, prek run --all-files. Confirm .git/hooks/pre-commit and .git/hooks/pre-push exist.

Implement commands, client methods, and models.

Validate: go test ./..., BDD command, make ci.

Run scripts/audit-workflows.sh and scripts/audit-release-naming.sh. Fix all findings.

(Agent skill) Scaffold skills/<name>/SKILL.md with command mapping, usage examples, and error handling rules.

Run references/delivery-checklist.md — every item must pass before done.

Required CLI Contract

Output modes --json and --plain are mandatory.

--jq via itchyny/gojq only — never shell out.

--token falls back to <SERVICE>_API_TOKEN env var.

Hints and progress go to stderr, not stdout.

Connectivity check uses status command (not auth check).

list commands must have ls alias.

Command names match API terminology — no CRUD genericization.

Exit codes: 0 success, 1 error, 2 auth failure (401/403), 3 not found (404).

What To Load

references/agent-friendly-cli.md — CLI UX design contract, output format, help system, agent-friendly review checklist

references/go-code-architecture.md — Go code patterns and annotated examples

references/delivery-checklist.md — full delivery verification checklist

references/github-actions-comparison.md — side-by-side lessons and pitfalls

references/github-actions-adoption-checklist.md — rollout checklist

references/openapi-first-delivery.md — OpenAPI-only delivery flow

references/release-packaging-strategies.md — packaging strategy and naming mapping

references/prek-precommit.md — prek setup and commands

assets/templates/.github/workflows/ — copy-ready workflow files

assets/templates/Makefile, assets/templates/version.go — standardized project structure

assets/templates/scripts/next-version.sh — tag versioning script

assets/templates/release-naming.env — naming contract template

assets/templates/prek.toml — ready prek config

scripts/print-release-download.sh — download command generator

scripts/openapi-bootstrap.sh — OpenAPI bootstrap

scripts/init-project-files.sh — project files bootstrap

scripts/init-prek.sh — prek bootstrap

scripts/init-release-naming.sh — naming contract bootstrap

scripts/audit-release-naming.sh — naming drift audit

go-api-cli-playbook