Skip to content

docs: add AGENTS.md describing how we build - #8

Merged
sam-goodwin merged 3 commits into
mainfrom
docs/agents-md
Oct 7, 2026
Merged

sam-goodwin merged 3 commits into
mainfrom
docs/agents-md

Conversation

@sam-goodwin

Copy link
Copy Markdown
Collaborator

Adds a root AGENTS.md: what the repo is, and how we build in it.

## How we build

Tests drive the work, and real infrastructure runs from the first test. Each change goes through the same loop:

1. Write a failing test at the layer the change affects (see Testing).
2. Make it pass against local workerd with `ALCHEMY_DEV=1`, which is fast.
3. Run the same suites against real Cloudflare without `ALCHEMY_DEV`.
4. Open a PR. CI deploys a preview, runs every suite and records a demo video.
5. Merge, then pick up the next change.

Testing layers, each with a snippet from the real suites:

Layer File Command
Story packages/frontend/src/story.test.ts pnpm --filter @cafe/frontend test
Scene packages/frontend/src/scene.test.ts pnpm --filter @cafe/frontend test
API packages/backend/test/api.test.ts pnpm --filter @cafe/backend test
e2e packages/frontend/test/chat.test.ts pnpm --filter @cafe/frontend test:e2e

Parallel worktrees, each with its own stages so they don't deploy over each other:

git worktree add ../cafe-<topic> -b feat/<topic> origin/main
export ALCHEMY_STAGE=dev_<topic>          # alchemy dev / deploy
export ALCHEMY_TEST_STAGE=test_<topic>    # Test.make

Also covers demos (pnpm demo, or let the PR record one) and conventions: one file per responsibility in domain folders, named Effect.fn, effect/Config instead of process.env, a browser-safe @cafe/api, Conventional Commit PR titles.

🤖 Generated with Claude Code

sam-goodwin and others added 3 commits October 7, 2026 01:54
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 317eaa4 into main Oct 7, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant