Agent-Driven Development

Init is built to be driven end-to-end by a coding agent — from a cold clone to a verified, running feature — without a human babysitting each step. This page is that workflow; AGENTS.md at the repo root is the same guide your agent reads in-context.

One-command provisioningCopy Anchor Link

pnpm install
pnpm bootstrap --yes

pnpm bootstrap writes .env, starts local Postgres, pushes the schema, and seeds a dev user. It's interactive by default (a checklist to trim platforms you don't want), but --yes — or any piped, non-TTY invocation, which is how an agent runs it — keeps all apps and runs unattended. It's idempotent: re-run it, or pnpm db:reset, any time.

The Supabase CLI runs local Postgres as a native process, so cloud sandboxes run the whole stack. Postgres refuses root, so the repo's SessionStart hook gives Claude Code cloud sessions a system user to run it as. Every checkout and git branch gets its own database on its own port, so parallel agents and worktrees never share data — and a new branch starts empty, which one more pnpm bootstrap --yes fixes.

A seeded loginCopy Anchor Link

Every provision leaves a known account, so an agent can verify authenticated flows with no signup step:

dev@init.local / password

It comes with a personal organization and a few sample todos (see packages/service/src/seed.ts). The seed goes through better-auth's own signup API, so it exercises the same organization-provisioning path a real user hits.

Verifying a changeCopy Anchor Link

Static gate — mirrors CI, run before every commit:

pnpm verify   # typecheck · lint · format · test

It checks the desktop app's Rust as well (clippy, cargo test, cargo fmt), so a sandbox that keeps the desktop app needs rustup and, on Linux, WebKitGTK (libwebkit2gtk-4.1-dev), as CI installs them.

Smoke gate — passing types isn't proof the app boots, that auth works, or that a write reached the database. pnpm smoke drives a running server through health, the seeded sign-in, the todo lifecycle over oRPC and the authenticated dashboard, and fails naming the step that broke:

pnpm dev:web &
pnpm smoke

  ✓ server is live (/api/health) 412ms
  ✓ signed in as dev@init.local 88ms
  ✓ resolved the seeded organization 21ms
  ✓ read the seeded todos 35ms
  ✓ created a todo 40ms

  ✗ Smoke test failed: todo.update did not persist `completed`

It calls oRPC through the same RPCLink the apps use, typed against the shared contract, so a changed procedure shape breaks it at typecheck. CI runs it on every pull request against a real Postgres; SMOKE_URL=https://my-app-git-branch.vercel.app pnpm smoke points it at a preview deployment instead.

Interactive — the part most templates skip. Passing types isn't proof the feature works. Init ships agent-browser so an agent can drive the real web app:

npm i -g agent-browser && agent-browser install
agent-browser open http://localhost:3000
agent-browser snapshot           # accessibility tree with @eN refs
agent-browser fill @e1 dev@init.local
agent-browser click @e3          # sign in, then 'get text' / screenshot to assert

The web app is the one surface an agent can drive headlessly. Mobile, desktop, and extension build and typecheck, but a runtime check on those needs a human — see the matrix below.

OAuth without the internetCopy Anchor Link

Email/password needs nothing external. For the GitHub button, Init wires emulate — a local OAuth provider — so the shipped button works offline in dev. Uncomment NEXT_PUBLIC_GITHUB_EMULATOR_URL in .env, then:

pnpm emulate
pnpm dev:web

With the var set, the "Continue with GitHub" button routes through a dev-only genericOAuth provider aimed at the emulator — the same button, no diverging prod path (unset ⇒ the real provider). Click it and the emulator's user-picker completes sign-in; under pnpm dev:desktop the shell keeps that sign-in in its own window. Fixtures live in emulate.config.yaml.

One gap: avatar uploads go to Vercel Blob, which has no local emulator. Without BLOB_READ_WRITE_TOKEN that one route returns 501 with a pointer message — every other flow works offline.

What an agent can verifyCopy Anchor Link

The rest of the surfaceCopy Anchor Link

Setup and verification are the runnable half of Init's agent story. The rest is context an agent loads on its own:

• AGENTS.md + CLAUDE.md — conventions and this workflow, read automatically
• llms.txt and markdown negotiation — the docs as machine-readable text
• /.well-known/api-catalog — endpoint discovery, including the /api/health probe
• /openapi.json — the API as an OpenAPI 3.1 document, callable over REST at /api/v1
• Agent wiki — an optional OpenWiki job that keeps a generated map current

See Local Development for the human day-to-day workflow.