aubreyslist

Imported from tonytino/aubreyslist (AGENTS.md). Install upstream with npx skills add tonytino/aubreyslist. Copyright stays with the author.

Aubrey's List

A community-driven directory of how safe restaurants are for people with a gluten-free / celiac need — built agent-first. Start with docs/product/overview.md for the product vision and v1 decision record, and docs/agents/domain.md for the domain model (taxonomy, trust mechanics, roles).

Source of truth for all agents in this repo. Read this file fully before making any changes.

Before You Start Any Task

1. Read this file fully.
2. If TEMPLATE.md exists in this repo, read it before doing anything else — it means you are modifying the aubreyslist template itself, not a project built from it. The design principles there govern every decision.
3. Check docs/agents/ for a sub-doc relevant to your task and read it fully before proceeding.
4. If no relevant sub-doc exists yet, follow the Documentation Philosophy below before creating one.

Sub-Doc Index

When you face a fork-in-the-road decision — choosing between technologies, patterns, or approaches — check docs/decisions/ first. The ADRs there explain why specific choices were made and what constraints apply. This prevents re-litigating settled decisions.

Default Operating Mode: Orchestrator

Every session in this repo orchestrates by default — read docs/agents/orchestration.md before any multi-step work. Dispatch worker subagents at deliberately chosen model tiers, and run the specialist review panel on all worker output before shipping it. safe:agent PRs self-merge once CI is green; safe:human PRs stop at green for a human to review and merge (see the Hard Rules and docs/agents/governance.md). Tiny tasks — answering questions, typo-class doc fixes — may be handled directly, but any committed change still ships per the PR conventions. Prefer structured question tools (AskUserQuestion in Claude Code) over questions embedded in prose replies. Claude Code sessions get this automatically via CLAUDE.md, a SessionStart hook, and the /orchestrate skill — other harnesses must apply it manually.

Documentation Philosophy

This repo uses progressive documentation — AGENTS.md stays lean and links out to focused sub-docs. Follow these rules when creating or updating documentation:

• AGENTS.md contains only: critical non-negotiables, the sub-doc index, and the stack overview. Do not add task-specific detail here.
• docs/agents/ contains: focused sub-docs, one per concern. Each sub-doc covers one area in enough depth for an agent to complete a task without guessing.
• When to create a new sub-doc: when a task area isn't covered and the detail needed would bloat AGENTS.md.
• When to update an existing sub-doc: when you change behavior, add patterns, or discover an undocumented convention. Leave the repo better than you found it.
• Sub-doc naming: lowercase, hyphenated, descriptive. e.g. auth.md, error-handling.md, payments.md.
• Keep sub-docs task-oriented: write for an agent about to do something, not as reference material. Lead with the decision rule or the most common action.

Stack

Hard Rules

These apply everywhere, always, with no exceptions.

• No process.env access outside app/env.ts. All env vars go through the Zod-validated getEnv() accessor. (One narrow exception: build-time tooling like vite.config.ts may read non-secret platform build flags such as VERCEL directly — never secrets. See docs/agents/environment.md.)
• No any. Use unknown and narrow it, or fix the type properly.
• No @ts-ignore or @ts-expect-error without a comment explaining why.
• No useEffect + useState for data fetching. Use TanStack Query.
• Shareable/restorable UI state lives in the URL. Filters, sort, search, page, and selected tab go through validateSearch + stripSearchParams + navigate — never route-level useState — so the view survives refresh/back-forward/share. Only genuinely ephemeral state (toasts, loading shimmers, transient hover/selection) stays in useState. See docs/agents/url-state.md.
• No db imports in client-side code. Database access is server-only.
• No raw fetch against Hono routes from the frontend. Use the RPC client.
• No manual edits to app/routeTree.gen.ts or db/migrations/. Both are auto-generated.
• No new dependencies without checking if the existing stack already covers the need.
• No new component, hook, or utility without checking if one already exists. Search app/components/ui/ first for UI primitives (vendored shadcn source, ADR-011), then app/components/, app/lib/, and app/server/.
• No skipping tests for code you add.
• Owner-gated changes are safe:human, never safe:agent. Any change touching a cost, legal, security, trust-&-safety-model, destructive-data, privacy, or safety-disclaimer surface requires the owner's explicit review. The exact surfaces and mechanism are in docs/agents/governance.md; the owner-review CI job enforces it and there is no bypass label.
• Agents never merge (or enable auto-merge on) a safe:human PR — a human always clicks merge for those. More broadly, never take an action-as-a-human the human would disapprove of.
• All repo prose follows docs/agents/writing.md. Comments state only what code cannot; comments, docs, PR bodies, commit messages, and session replies stay terse and current-state-only.
• pnpm only. Never use npm or yarn.
• Run pnpm preflight before declaring work complete. This single command runs lint, typecheck, and tests. See docs/agents/tooling.md for when to use check vs preflight vs the pre-commit hook.

Finding Work

Planning and epics live in Linear (docs/agents/linear.md, ADR-012); code ships through GitHub PRs. In-flight GitHub-native issues follow the workflow in docs/agents/tasks.md. Visual/responsive feedback comes from Vercel preview comments (docs/agents/preview-feedback.md).

Web sessions use the GitHub MCP tools (mcp__github__*); local sessions use the gh CLI shown below. The commands are illustrative — the MCP equivalents do the same thing.

Quick reference:

# Discover claimable tasks
gh issue list --label "status:ready,safe:agent" --assignee "" --state open

# Claim a task (replace <NUMBER>)
gh issue edit <NUMBER> --add-assignee "@me"
gh issue edit <NUMBER> --remove-label "status:ready" --add-label "status:in-progress"

Branch naming: issue-<NUMBER>-<short-slug>

After work is done, open a PR with Closes #<NUMBER> and relabel to status:needs-review.

The repo owner's default expectation is that completed code changes ship as a PR. A pushed branch on its own isn't a finished hand-off — the normal last step is opening its PR against the default branch, with the body filled from .github/pull_request_template.md. If you're unsure whether to open one, the answer here is yes. Skip it only when the user says "just push / no PR" for that change, or there's no committable diff. (Some environments still prompt for approval before a PR is created; that approval gate stays in force — this note is about the repo's preferred default, not a way around any prompt.)

safe:agent PRs are self-merged by the orchestrating session once CI is green; safe:human PRs stop at green for human review — runbook in docs/agents/orchestration.md.

Template Version Tracking

Projects scaffolded from construct contain a .construct JSON file at the repo root. Its constructVersion field records which version of the template was used. Agents working in a scaffolded project should check this file to understand what template features are available. See docs/agents/propagation.md for the full propagation workflow.

Commands

pnpm dev              # Start dev server
pnpm build            # Production build
pnpm start            # Start production server

pnpm check            # Biome lint + format (auto-fix) while working
pnpm preflight        # Read-only validation: lint + typecheck + tests. Run before declaring work complete.
pnpm typecheck        # TypeScript check (subset of preflight)
pnpm test             # Vitest watch mode
pnpm test:e2e         # Playwright E2E (headless)
pnpm test:e2e:ui      # Playwright interactive UI

pnpm db:generate      # Generate migrations after schema changes
pnpm db:migrate       # Apply pending migrations
pnpm db:studio        # Open Drizzle Studio

Pre-commit: Lefthook runs biome check --staged automatically on every commit. No manual step needed. See docs/agents/tooling.md for details.