Groundwork AGENTS.md

Groundwork: the operating system for this project

Groundwork tells any AI agent (in any IDE, on any model) how to take this project from first idea to delivered, maintained software at enterprise quality. This file is always loaded and is the single source of rules. Everything else loads on demand via the routing table below.

New project (docs/state/STATE.md still says NOT STARTED)? Load the skill begin and follow it.

Session protocol

1. Read the handoff block at the top of docs/state/STATE.md before anything else. Do not re-derive project state from the codebase. That is what the file is for. (Maintainers of Groundwork itself: a gitignored docs/state/STATE.local.md, when present, takes STATE.md's place throughout this protocol.)
2. Work one task at a time. When you finish, propose exactly one best next step, no menus.
3. Before ending a session or after completing significant work: update docs/state/STATE.md. One fact, one place: update only the file that owns the fact.
4. End every message with ⚓ to confirm these rules are loaded.

Decision ladder: run before writing anything

Stop at the first rung that holds:

1. Does this need to exist? Not requested and not load-bearing → don't build it.
2. Does it already exist in this repo? Reuse it. Never write a second version.
3. Does the platform, stdlib, or an installed dependency do it? Use that.
4. Only then: build the minimum that works, to the standards in docs/standards/.

Understanding comes before the ladder. A small diff you don't understand is not efficiency. Read enough to know the root cause, then fix the cause once, not the symptom everywhere.

Hard rules

• Scope. All work must trace to docs/product/BRIEF.md or an explicit request. Out-of-scope findings and ideas go to docs/state/INTAKE.md: record them, don't build them.
• Done is done. Stable, tested, in scope = finished. No gold-plating, no unrequested refactors, no "while I'm here". There is always something to improve; that is not a reason to.
• Never bypass a gate. No --no-verify, no skipping hooks, no commenting out or weakening a check to make it pass. A red gate is information. If a gate is wrong, fix the gate in the open.
• Security floor (never simplify away): input validation at trust boundaries, authorization checks, error handling that prevents data loss and never swallows a failure silently, secrets out of code and logs, accessibility.
• Honesty. Report failures as failures, with output. Never claim something works that you did not verify. No reassuring the user against the evidence.
• Verify before "done". Exercise the change end-to-end, not just the type checker. What you cannot verify, you flag. Details: skill verify.
• Language. All governance text, code, comments, and commits in English. Write plainly: no em dashes, en dashes, curly quotes or ellipsis characters, and none of the AI-boilerplate phrasing banned in docs/design/VOICE.md. This holds for every file in this repo and every product built on Groundwork; checks/check.mjs (prose-style) enforces the mechanical part. Product-facing language is set per project in docs/design/VOICE.md.