Building with AI agents

The shape that works

Driving the CLI from an agent is the command sequence, driving your AI with docs stops it guessing at flags, testing your backend is the gate it should run, and diagnosing a broken project is what to do when it stalls.

In Claude Code, the pithy plugin runs this shape for you: /new-app asks web, mobile or both, scaffolds with pithy init --target, and dispatches a server, client and runner agent on the models you chose. Everything below still applies to what those agents write.

Let the agent run the CLI, and let the kit’s own gates catch it.

pithy init --name acme --worker api --json
pithy add auth --worker api --with-prerequisites --json
pithy migrate --json
pithy doctor --json

Every step reports what it did and what it could not finish. An agent that reads the result rather than assuming success needs very little supervision through this part.

The instructions a project carries

pithy init tells the agent how to drive this CLI, in the project itself. It writes a marked Pithy block into AGENTS.md: pithy schema --json describes every command the installed version takes, PITHY_JSON=compact keeps every --json document on one line, PITHY_NONINTERACTIVE=1 means no prompt waits, --dry-run comes before a change, and pithy remove and every typed confirmation phrase belong to a person. It also says that an app route is an MCP tool for its users’ agents only when its describeRoute names an operation and opts in with tool, with power for the role a caller must hold, and that operation is permanent. And it says that a person administers a deployed environment through pithy mcp connect with --scope manifest:read and only the reads needed, because with no --scope it grants every read plus keys:rotate; the agent asks before each call that is not a read, and leaves pithy mcp disconnect to the person. The exit-code table sits under it.

Claude Code reads its own file, so CLAUDE.md gets one line: Agent instructions for this project, Pithy's included: @AGENTS.md. A repository that already has either file keeps every byte of it; the block or the line is appended. pithy upgrade rewrites the block as the CLI changes, and touches nothing outside it.

Three gates a scaffold ships with

pithy init writes the checks CI needs, not only the two commands a developer runs:

bun run typechecktsc -b over the solution file
bun run testVitest, split by runtime
bun run lintBiome over everything

The test split is the kit’s whole testing argument. Worker tests run inside workerd against a real D1 and a real KV through Miniflare; everything else runs in Node.

A test that mocks D1 proves the mock works — which is why the fiddly half is scaffolded rather than described.

The gap to hand the agent explicitly

Where an agent should stop

A supplied secret. Provisioning mints what is arbitrary and stops for anything that must agree with a third party.

Email Routing. Enabling it points a domain’s whole MX at Cloudflare, so no command turns it on: pithy support provision refuses a domain it is off for, and email’s bounce rule takes its zone as an explicit flag. Turning it on is a person’s decision.

Production, and anything that deletes. A type-to-confirm phrase that --yes never replaces. A line that names such a command says That is a person’s decision, not a fix, and never offers it as fix.

pithy remove. It rejects --json, --no-input and PITHY_NONINTERACTIVE=1, with exit 5 — the code that means a person has to take this step.

Reviewing what an agent wrote

Check the claims against code, not comments. Doc comments describe intentions, and an intention nobody implemented reads exactly like a feature — this repository has caught several.

Check the seams. A conditional around c.var.emit(...) means the agent thought the seam might be absent. It is present and inert.

Check the order. requireAuth() before requireEntitlement(), guards before validators. A validator ahead of a guard turns a 401 into a 400 and tells an unauthenticated caller which requests were well-formed.

Check the refs. Any ledger movement or workflow step built from a clock or a random source is a retry that pays twice.

Give it the constraints up front

Cloudflare-only. No filesystem. No code generation at runtime. No long-lived process. A bounded CPU budget per request. No interactive transactions in D1, and 100 bound parameters per query.

Most of the wrong code an agent writes for this kit comes from assuming a Node backend, and stating the constraints once is cheaper than correcting them ten times.

What the kit will tell it

pithy doctor reports what a deploy would fail on, and names the command that fixes each.

Every config block is validated at assembly, so a wrong algorithm, an immutable field changed, or a reserved plugin id fails on deploy rather than at 3am.

ESC