Simbai

A prompt goes in. A structured software project comes out.

New here / learning the method? Start with CREOVINE-ACADEMY-SE-LEVEL-1.md — a step-by-step guide to how this project was built with an AI coding agent, written so the method transfers to any web project.

ARCHITECTURE.md is the source of truth. Code comments reference its sections (§2, §4, §9…). Read it before changing anything structural — several rules in here look arbitrary and are not.

Built so far: Phase 0 (foundation) and Phase 1 (pipeline spine — stages 00 clarify → 01 spec → 02 architecture, which is also the free tier).

---

Run it locally

1. Environment

cp .env.example .env.local

Two values are required:

Variable	Where to get it
DATABASE_URL	Vercel Dashboard → Storage → Create → Postgres (Neon). Then vercel env pull .env.local fills both URLs automatically.
ANTHROPIC_API_KEY	console.anthropic.com → API keys. The only thing that costs money.

Leave AUTH_SECRET unset locally — the app seeds a dev user automatically (src/lib/session.ts). It is required in production.

2. Database

No Vercel account needed locally. Either works:

# Homebrew Postgres (what this machine uses)
LC_ALL=C pg_ctl -D /usr/local/var/postgresql@15 -l /tmp/pg.log start
# or Docker
docker compose up -d

Then:

npm run db:push       # apply schema to a fresh database
# or: npm run db:migrate   to run the checked-in migration
npm run db:studio     # browse it

3. Two terminals

npm run dev           # http://localhost:3000
npm run inngest       # Inngest dev server — the pipeline does not run without it

The Inngest dev server is not optional. The web app only writes a row and emits an event (§4); Inngest is what actually executes the stages.

INNGEST_DEV=1 must be in .env.local. Inngest v4 defaults to cloud mode, demands a signing key, and returns 500 from /api/inngest without it — so functions never register and runs sit in queued forever with no visible error. This is already set in .env.example.

Not sure whether your setup is complete? The home page runs /api/health on load and names anything missing, with the command to fix it.

Open http://localhost:3000, describe an idea, and answer the clarifying questions when they appear.

Demo mode — no API key required

Set SIMBAI_DEMO=1 in .env.local and the pipeline serves realistic fixtures instead of calling Anthropic. Everything else runs for real: Inngest steps, the stage-00 wait-for-answers branch, artifact persistence, cost accounting and the polling UI. Only the model call is swapped, so this is a demo of the product rather than a mock of it.

Fixtures live in src/pipeline/demo/fixtures.ts and are validated against the real Zod schemas at call time — a drifted fixture fails loudly instead of rendering as a broken artifact.

---

Commands

Command	What it does
npm run dev	Next.js dev server
npm run inngest	Inngest dev server (required for the pipeline)
npm run typecheck	tsc --noEmit
npm run build	Production build
npm run db:push / db:migrate / db:studio	Drizzle
npm run registry:check	Fails if any stack-registry entry is >90 days old. Wire into CI.

---

Where things live

src/pipeline/          the product. no HTTP, no React imports.
  call.ts              THE single Anthropic call site — see below
  schemas/             Zod, .strict(), source of truth for every stage
  prompts/system.ts    frozen system prompt — editing it invalidates all caches
  prompts/stages.ts    per-stage instructions, create + refine variants
  stages/              thin wrappers, one per pipeline stage
  registry/stacks.ts   pinned versions — the anti-hallucination mitigation
  run.ts               Inngest durable step function
src/db/                Drizzle schema + migrations
src/app/api/           thin routes: write a row, emit an event, return

Three rules that are load-bearing

1 · Never call the Anthropic SDK outside src/pipeline/call.ts. Prompt assembly order, cache breakpoints, stop_reason checking, refusal fallbacks and validate-and-retry all live there once. Adding a second call site is how the caching layout silently breaks (§9).

2 · Never put stage-specific text in prompts/system.ts. Caching is a prefix match. A per-stage system prompt diverges at byte zero and yields a 0% cache hit rate. Stage instructions go in the final user turn — that is why prompts/stages.ts exists.

3 · src/pipeline/registry/stacks.ts is a treadmill, not an asset. A stale registry is worse than model memory, because stage 02 tells the user its versions are verified. npm run registry:check fails at 90 days. It needs a named owner — see §9.

---

Not built yet

Stages 03–07 (data model, API contract, file tree, task graph, export), the constitution stage, artifact renderers, editing and regeneration, credits and billing. See §8 for the phase order.

§10.6 is open and blocks Phase 3: whether Simbai ships a CLI alongside the web app. Every comparable open-source project (§11) is a terminal tool.