cli-build

Build a CLI whose primary user is an agent and whose supervisor is a human. That inverts the usual defaults: machine-readable output is not a flag you add later, prompts are a failure mode in non-interactive contexts, and every write leaves a receipt.

Phase 0: where does the contract come from

Every command you write reads or mutates something with a shape. This phase names that shape's owner, because it decides whether you go find the contract or write it.

Discovered. The CLI wraps a system you do not control: a third-party API, a login-walled portal, a device, an undocumented file format. The contract exists and is unverified, so guessing at it wastes more time than mapping it. Run surface-recon first and start from its report.

Defined. You own the model: CRUD over your own database, a scaffolder, a local transform, a wrapper around a library whose types you already have. There is nothing to reverse-engineer, so surface-recon has no input and skipping it costs nothing. Write the contract instead, in one pass before Phase 1: the entities, their fields and types, the operations allowed on each, and what makes a write irreversible. That artifact is what a recon report would have given you.

Mixed. A CLI over your own database that also calls a payment provider is discovered at the boundary and defined in the middle. Recon only the discovered part; do not let one external call turn the whole build into a recon job.

Say which one this is out loud before Phase 1, and write it into friction.md. An unstated classification defaults to discovered, which is how a defined build ends up blocked waiting for a report nobody can produce.

Done when: the origin is named, and either a recon report exists or the entities and operations are written down.

Open friction.md next to the code now and append as you go.