ByeBuy.ai
BUILD YOUR ESCAPE ROUTE · ✦ CURSOR · HOST IT · ◫ SUPABASE · CONNECT IT · ↯ RELAY · BUILD YOUR ESCAPE ROUTE · ✦ CURSOR · HOST IT · ◫ SUPABASE · CONNECT IT · ↯ RELAY ·
CURRICULUM
← BYEBUY NOTES

September 12, 2026

APPENDIX: AN AGENTS.MD STARTER EVERY AGENT READS FIRST

Appendix: An AGENTS.md Starter Every Agent Reads First

Part IX taught bounded tasks and contracts; Lesson 42.2 named AGENTS.md as the instructions-and-boundaries file for AI/coding agents in the repo. This is the complete starter: one page every human and agent reads before touching code, so parallel workers share the same rules instead of inventing their own.

The starter (copy, then fill)

# AGENTS.md — <project name>

## What this project is
<one sentence: user, outcome, current stage>

## Source of truth (read first)
- PRD: <path> — SPEC: <path> — ARCHITECTURE: <path>
- Interface contract: <path> — ROADMAP: <path>

## Allowed scope
- May change: <folders/files for current phase>
- Must not change without explicit approval: auth, payments, migrations, env settings, deployment, production data

## How to work here
1. Read the task card (`TASK.md`) and named sources above. Do not start from chat memory.
2. Inspect first (`git status`, relevant files, diff). Propose a plan before editing.
3. Work on the named branch/worktree only. One coherent change per commit.
4. Run the named evidence (tests, preview, checks) and report output — including what you could not verify.

## Propose, do not presume
- Smallest change that satisfies the acceptance checks; no redesign, no new dependency, no migration unless the task says so.
- Stop and escalate when: the contract must change, tests fail on main, scope expands, or a secret/credential is needed.
- Every task ends with: changed files, commands run + results, evidence attached, open questions, recommended next step.

## Approval gates
- Preview + human review required before merge. Production deploys, publishes, payments, and permission changes need explicit named approval (<owner>).

Why it works

It compresses four lessons into one page the agent cannot miss: the task card shape (44.2), the per-worker contract (36.4), the evidence loop (40.2), and the canonical docs (42.2). A new session reads this plus the task card and knows the job, the boundaries, and the proof — without inheriting a swollen conversation.

Keep it to one page. If it grows past that, the project needs clearer specs, not a longer instructions file.

Verify

Open a fresh session on a branch and ask: "Read AGENTS.md and state what you would do first and what you would refuse to touch." If it names the task card, the allowed folders, and the protected areas correctly, the file works. If it guesses, tighten the paths and gates.

Common failure mode: a generic AGENTS.md copied between projects ("follow best practices"). Recovery: replace adjectives with paths, owners, and commands specific to this repo — agents obey addresses, not aspirations.

ARTICLE DISCUSSION

JOIN THE
CONVERSATION.

0 COMMENTS

BYEBUY ACCOUNT ACCESS

Sign in

Use your account to save routes and make the catalogue yours.

Enter your email and we’ll send a secure sign-in link and code.

NEW ROUTES ADDED WEEKLY · 9,235 CATALOGUE ENTRIES · BUILD · DEPLOY · QUERY · STACK · SAY BYE TO BUY · NEW ROUTES ADDED WEEKLY · 9,235 CATALOGUE ENTRIES · BUILD · DEPLOY · QUERY · STACK · SAY BYE TO BUY ·