Implementer overview

This section is for engineers building the Go sp CLI in sp-cli.

Read order

1. For agents — primary UX constraints
2. Output contract — JSON envelopes and exit codes
3. Architecture — recommended package layout
4. sp_api migration — parity with OpenCode plugin
5. API mapping — REST truth table
6. Non-goals

Implementation phases

Phase	Commands	Notes
v1	config, auth, app, policy, replay control, health	HTTP client + profiles
v2	record, trace, replay data, workspace, ops, …	Artifacts, pagination

Do not add sp c or embedded source to the public binary — see Non-goals.

Documentation is normative for v2 before code exists.

Definition of done (per command)

• Cobra command registered with stable argv
• --json output matches JSON types
• Integration test with httptest or recorded fixtures
• Doc page in commands/ or commands-v2/ updated if behavior differs

Testing agents

Provide golden --json files under sp-cli/testdata/ for skill regression.