| name | implement-api |
| description | Implement or extend a TAPD API command in the go-tapd/cli repository. Use when adding commands like story list, bug list, task list, workspace view, or when wiring new TAPD API capabilities from the go-tapd/tapd SDK into the CLI. |
Implement API
This skill is for implementing a TAPD API command in the CLI repository:
- CLI repo:
https://github.com/go-tapd/cli
- SDK repo:
https://github.com/go-tapd/tapd
Follow this workflow.
1. Define the command contract
Before editing code, decide:
- command path
- required flags
- optional filters
- default output columns
- whether
--format json should be supported
Prefer CLI behavior that matches existing commands in the repository.
2. Inspect the SDK first
Do not write request logic from memory.
Find the matching TAPD SDK service, request, and response in go-tapd/tapd.
Check:
- which service method to call
- which request struct to use
- which fields are required
- which response fields are suitable for table output
If the SDK already supports the API, reuse it directly.
If the SDK is missing support for the API, stop and note that the SDK must be extended first.
3. Reuse existing CLI patterns
Follow the structure already used in go-tapd/cli.
Look for:
- root command registration
- shared flag helpers
- output helpers
- the closest existing command of the same shape
Use the existing style for:
- workspace flag handling
- request construction
- table output
- json output
- command help text
4. Implement with minimal abstraction
Add only what the new command needs:
- flags
- SDK request mapping
- service call
- table row mapping
- command registration
Do not introduce new abstractions unless there is already repeated logic.
5. Keep output consistent
For list commands:
- support
table and json
- choose a small default column set
- prefer stable identifiers and operator-relevant fields
For single-resource commands:
- return the raw object for
json
- use a compact table or summary view for default output
6. Validate before finishing
Run:
go build ./...go test ./...go run . <command> --help
If the repo is in an offline or sandboxed environment, adapt the validation command accordingly, but still verify compile success and command help output.
7. Update docs only when useful
If the command is user-facing and materially expands CLI capability, update the repository documentation with a short usage example.
Decision rules
- Prefer extending an existing command file over creating a new one when the resource already exists.
- Prefer adding shared helpers only after the second real reuse.
- Prefer SDK-backed typed requests over ad hoc HTTP logic.
- Prefer narrow, incremental commands over large multi-command batches in one change.
Expected implementation checklist
- command contract is clear
- SDK method is confirmed
- flags map correctly to SDK request fields
- root registration is complete
table|json output works- build passes
- tests pass
- help output is checked
