A TypeScript monorepo designed for human <> agent collaboration.

Website  ·  Notes on agentic coding  ·  MIT

bunx degit mateoroldos/effect-forge my-app

About

Agents write code faster than anyone can review it. effect-forge is a monorepo template shaped around that problem — types and traces that make behaviour inspectable, boundaries that keep changes small, and checks fast enough that an agent proves its own work before you read a line of it.

It is opinionated: Effect, Bun, PostgreSQL, and Cloudflare, wired together and deployed by Alchemy.

AGENTS.md                conventions every agent reads
skills/effect-forge/     playbooks, loaded per task

apps/
├─ web                   TanStack Start application
├─ api                   Effect HTTP API
└─ site                  the project's landing page

packages/
├─ domain                the domain model
├─ core                  application services and ports
├─ contracts             typed HTTP contracts
└─ ui                    shared visual vocabulary

adapters/
└─ database-postgres     PostgreSQL port implementations

alchemy.run.ts           infrastructure as code

Development

Bootstrap a checkout and authenticate the local Alchemy profile:

mise trust
mise run setup
bun alchemy login --configure

Start the application:

bun run dev

mise derives STAGE from the user and checkout directory. Each clone, git worktree, or jj workspace therefore gets its own Neon branch and local Alchemy stage, branched from the staging project — so staging has to exist first.

Validation

bun run test    # tests only
bun run check   # formatting, lint, types, and tests
bun run build   # production builds

CI runs check and build.

Deployment

internal PR with preview label
  → CI
  → EffectForge:pr-<number>
  → preview URL posted on the PR

label removed or PR closed
  → preview destroyed

merge to main
  → CI
  → EffectForge:prod

Pull requests without the preview label run validation only. Forks cannot access deployment credentials. Deployments to the same stage are queued because Cloudflare.state() does not lock concurrent writes.

docs/deployment.md covers the stages and the one-time maintainer setup.