AGENTS.md

Architecture

apps/next: Next.js 16 frontend.
apps/agent-worker: optional server-side coding-agent worker. It polls Convex for queued jobs and may control Docker/Podman to run ephemeral job containers. It also exposes a server-only HTTP API, defaulting to port 3921, that Next route handlers proxy to for active workspace files, diffs, messages, commands, and draft PR actions.
apps/expo: Expo scaffold; only work here when explicitly requested.
packages/backend/convex: self-hosted Convex functions, schema, and auth.
packages/ui: shared shadcn-based UI components.
tools: shared ESLint, Prettier, Tailwind, TypeScript, and Vitest config.
Local development uses host-run apps, local Convex on ports 3210/3211, local Postgres on port 5432 for Convex storage, and the Convex dashboard on port 6791. Agent jobs are opt-in; build docker/agent-job.Dockerfile as spoon-agent-job:latest before running Docker-backed jobs.
Gitea CI builds and pushes spoon-next, spoon-agent-worker, and spoon-agent-job images to git.gbrown.org/gib. In production, SPOON_AGENT_JOB_IMAGE should point to git.gbrown.org/gib/spoon-agent-job:latest, and the worker service requires access to the host Docker socket.

Protected and generated files

Never edit packages/backend/convex/_generated/** or packages/backend/convex/http.ts.
Do not rename apps/next/next.config.js or apps/next/src/proxy.ts.
Preserve typescript.ignoreBuildErrors in Next config.
Do not modify Sentry config or tools/tailwind/theme.css unless requested.
Generated .cache, .turbo, .local, and environment files are ignored.
scripts/convex-codegen generates Convex API files for checks and image builds when deployment env is available; do not hand-edit generated output.

Environment rules

Local dev and staging come only from Infisical via scripts/with-env; it never falls back to .env*.
Run infisical login and infisical init before local development.
scripts/export-env enforces .local/infisical.env when multiple local Infisical accounts are logged in. Put INFISICAL_EMAIL=you@example.com there for this project and do not commit it.
Machine-generated values belong in .local/<env>.generated.env; never put the generated Convex admin key in shared Infisical.
scripts/sync-convex-env <dev|staging> copies Authentik, GitHub App, UseSend, SITE_URL, SPOON_WORKER_TOKEN, encryption, and Convex Auth signing variables from Infisical into the selected Convex deployment. Backend dev/setup scripts run it before convex dev.
Agent workspace proxy env uses SPOON_AGENT_WORKER_URL, SPOON_AGENT_WORKER_HTTP_PORT, and SPOON_AGENT_WORKER_INTERNAL_TOKEN. Keep these server-only; the browser must never receive worker tokens.
CI uses Gitea-injected secrets or CI_ENV_FILE and must not call Infisical.
CI must provide Convex deployment env for codegen, either CONVEX_SELF_HOSTED_URL plus CONVEX_SELF_HOSTED_ADMIN_KEY, or CONVEX_DEPLOYMENT.
App code imports validated variables from @/env, never process.env.
Add cache-relevant variables to turbo.json globalEnv.

Code and dependency rules

Use const arrow functions instead of function declarations.
Add .js extensions to Convex generated-file imports.
Put custom frontend routes directly in apps/next/src/app or normal route groups such as apps/next/src/app/(auth).
Extend the Convex users table for application user data; do not add a profile table by default. Authenticate protected functions.
Manage shared versions in root catalogs. Never run bun update in a package.
Run root bun install and verify with bun lint:ws.
Update this guide when architecture or workflows change.

Local stack

bun db:up          # start Postgres, Convex, and dashboard
bun dev:next       # host Next + deploy/watch local Convex functions
bun dev:agent      # run the optional coding-agent worker on the host
bun sync:convex    # sync Infisical values into Convex
bun db:down        # stop and preserve local data
bun db:down:wipe   # remove local data volumes and generated admin key

Local URLs: app http://localhost:3000, Convex http://localhost:3210, dashboard http://localhost:6791, Postgres localhost:5432. Use INFISICAL_ENV=staging bun dev:next for staging services. Normal db:up never connects to staging.

Validation

Use bun typecheck, never a production build for routine validation. The full gate is SKIP_E2E=1 bun run ci:check; it runs Convex codegen before checking. Local-stack smoke e2e is bun test:e2e. Pre-commit runs lint-staged serially and pre-push runs the bounded full gate.

4.6 KiB Raw Blame History