agent-stack / starter-kit
AGENTS.md42 starsChanged 41 days agoApache-2.0View on GitHub
These rules are binding for every seat. The rig culture (CULTURE.md) adds team rules; where they conflict, this file wins.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- agent-stackSkill
- blast-radiusSkill
- bug-review-boardSkill
- openrig-project-setupSkill
- project-onboardingSkill
- review-lensesSkill
- technical-writingSkill
- unslopSkill
- verification-guideSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Start for tests: npm run start:test, run directly and never inside agent-heavy, because a server holds its slot forever (must serve the app …
- Distinctive: line 31
Before handing off, implementers run their feature's journeys and walk the main journey once in the browser.
- Very specific: line 35
Search with rg / rg --files / fd.
- Very specific: line 37
Commit identity: @COMMIT_IDENTITY@
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
@PROJECT@: rules for every agent
These rules are binding for every seat. The rig culture (CULTURE.md) adds team rules; where they conflict, this file wins.
What we are building
- The plan:
docs/PLAN.md(written by the owner). - The feature list:
features.json(produced by the architect, approved by the owner). A feature is done only when its locked acceptance journeys pass and the QA seat has used it by hand; then the lead setspasses: true. - A wave with user-facing changes (and so a mission) is done only when its W witness slice records
agent-witnessed (YYYY-MM-DD, by <agent>, <model>): a fresh agent used the deployed app end to end through the real UI, with evidence. Tests, merges and deploys are not witnesses. Only a docs/infra-only wave may skip it, withno-witness: <reason>on the wave in mission.yaml. - Progress log:
PROGRESS.md(one line per merged feature). Daily summaries:docs/summary/.
How to run it
- Install:
npm ci - Start for tests:
npm run start:test, run directly and never inside agent-heavy, because a server holds its slot forever (must serve the app on$PORTwith test data; Playwright sets PORT to your seat's ownE2E_PORT, so parallel seats never share a server) - Heavy runs go through the machine's shared budget (binding for every seat):
agent-heavy build -- <cmd>for tsc, eslint,npm test,next buildand full suites;agent-heavy browser -- <cmd>for Playwright. Prefer the focused run (your files, your feature's journeys) over the full suite. Servers stay outside agent-heavy (it refuses them). - Unit tests (optional, never proof of done):
agent-heavy build -- npm test - Acceptance journeys:
agent-heavy browser -- npx playwright test(desktop and phone) - Held-out journeys (merge owner only):
E2E_TEST_DIR=@HELDOUT@ agent-heavy browser -- npx playwright test
Testing from a person's perspective
- Proof of done is a person using the app: see
tests/acceptance/README.md. CI checks this (scripts/guards/check-human-perspective.sh) and blocks implementation PRs that touchtests/acceptance/(scripts/guards/check-protected-paths.sh). - Before handing off, implementers run their feature's journeys and walk the main journey once in the browser.
- The QA seat always does a hands-on pass and attaches screenshots before review.
Working rules
- Search with
rg/rg --files/fd. Put tables you pass to other seats in TOON (... | toon). - Branches: implementers
agent/<seat>, test authorstests/<feature-id>. PRs are ready, never drafts. - Commit identity: @COMMIT_IDENTITY@
- Secrets live only in local env files and the hosting provider. Never in code, tests, logs or PRs.
- Changes to
scripts/guards/,playwright.config.tsor.github/need the owner'sowner-approvedlabel.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.