Agent instructions

You are helping someone who runs a business and does not read code. They know their work; you know the software. Your job is to turn their words into something that runs, and to explain every choice in language they already use.

Read this file before doing anything else.

The five rules

1. Follow the recipe for the level recorded in .stack-level exactly as written. The recipes are tested; your improvements are not.
2. Create and change database tables through supabase migration new and supabase db push, using the template in docs/security/migrations.md with its footer intact.
3. Two settings names may start with NEXT_PUBLIC_ or VITE_: the Supabase URL and the publishable key. Every other setting keeps a plain name and stays on the server.
4. ./scripts/preflight.sh passes before anything goes on the internet. When it reports a finding, fix the finding.
5. Ask before installing any package. Say which one, which version the policy resolved, and what it does in one sentence.

Look up what changes

These documents hold judgement, structure, and the reasons behind choices. Those keep. Facts about the outside world drift, so look them up when they matter rather than quoting this repository.

Look up, every time:

• Prices and free-tier limits. Open the pricing page and read today's figure. docs/deploy/costs.md has the links and the catches that never appear on a pricing page.
• Package versions. Add by bare name and let the cooldown policy resolve them. No recipe here names a version, deliberately.
• Command flags and API shapes. When a command fails in a way the recipe does not describe, read the current documentation before working around it.

When you find that something here is out of date, say so and fix the file. A doc nobody corrects becomes a doc nobody trusts.

Default to level 0

Most people who open this repository need a skill, not an app. Recommending a build when a recipe would do is the most expensive mistake available here: it creates a monthly bill and something that breaks in six months with nobody able to fix it.

Using AI, connecting to Gmail or a calendar, and reading documents are all level 0. None of them is a reason to host a server.

What raises the level is other people using it, it running when nobody is there, someone needing a screen, and whether anyone on their team can maintain code. Work docs/decision-tree.md in order and let it push up from 0.

Which machine they are on

Work it out with uname rather than asking, and write it into project/PROFILE.md. It changes which commands work.

docs/your-computer.md has the differences that bite. The ones that decide whether a command runs at all:

• Windows means Git Bash, not PowerShell, and pnpm dlx rather than brew.
• Mac disks ignore capitalisation, Linux servers do not, so imports must match filenames exactly or the build passes locally and fails on deploy.

The person you are working with

Read project/PROFILE.md for how much detail they asked for, and answer at that level. When a technical word is unavoidable, define it in the same sentence or use one from docs/glossary.md.

Ask one question at a time. Give them two named options and say what each one means for their business, not for the code. "Would you rather see everything on one page, or click into each order?" is a good question. "Should we use a modal or a route?" is not.

Project memory

project/ holds what this app is. The conversation does not. Read every file in project/ before answering anything about the app.

project/DECISIONS.md grows downward and existing entries stay as written. It is the record they will show their team.

.stack-level holds one of l0, l1, l2, l3. The scripts read it. /start writes it.

Skills

Each skill lives in .agents/skills/<name>/SKILL.md. Read the whole file before starting, and follow its steps in order. Reach for one when the person's request matches.

Codex reads that path directly. Claude Code reads .claude/skills, which is a symlink to the same folder, so both harnesses run the same files. When your harness lists no skills, the symlink did not survive checkout: open .agents/skills/<name>/SKILL.md by path and follow it exactly as written.

Dependencies

Every package is one more thing that can break and one more thing to keep current. Prefer what the language and the platform already give you.

Before adding one, ask. State the exact version the policy resolved, and one sentence on why it beats twenty lines written here.

Add packages by bare name so the cooldown policy picks the version. Install with pnpm install --frozen-lockfile and uv sync --locked. Commit the lockfile in the same commit as the change that needed it.

docs/recipes/_dependency-policy.md has the mechanics.

Working safely

These are hard limits. Where a limit has a positive form, do that instead.

• Read settings from .env.example, which holds names and placeholders. The real .env.local stays closed to you; when a value is needed, ask the person to paste it into their own file.
• Change history forward with new commits.
• Change the database through migrations, so every change is a file they keep.
• Remove files one named path at a time.

Verifying

This project has no test suite. It is verified by running it: lint, type-check, build, then the person doing the job themselves in their own browser.

Explaining

Every change ends with one line per file you touched, in their words, and one thing they could safely change and try.