ADR 0002: Three commands

Architecture decision record 0002. Status: Accepted

Date: 2026-10-10

Status

Accepted

Context

Infrastructure tools tend to grow a command per situation: import, refresh, taint, state surgery, garbage collection. Each command is another thing to document, test and decide between, and agents in particular pick the wrong one. Sponson’s operations reduce to two directions between the plan and reality, plus a read-only comparison.

The obvious fourth command was import, to bring existing resources under management. Its job overlaps with generating the first plan: both read live state and write plan lines.

Decision

The CLI has three commands, plus mcp to serve them to agents:

Command	Direction	Writes
sponson init	make the plan catch up with reality: write a starter plan, or append lines adopting unmanaged resources (--adopt <key> for one)	the plan file only
sponson plan (alias status)	compare: read live state, print the diff and drift	nothing
sponson apply	make reality catch up with the plan; --destroy removes what the scope created	providers and the receipt store

Variations are flags on these commands (--env, --approved-by, --reconcile, --wait, --destroy, --json), never new commands. Every command takes --json.

Consequences

• init is idempotent: first run writes a plan, later runs only append lines for unmanaged resources and never reformat what is there.
• apply is idempotent and resumable, so the same sponson apply serves every CI trigger (pull request opened or updated, deployment finished) and a retry is always safe.
• Some operations are deliberately missing. Garbage collection of scopes whose pull request closed without the workflow running would need a fourth command and is not implemented.
• CONTRIBUTING.md requires a design note in the pull request for any fourth command, explaining why a flag on an existing one is worse.