grsshppr AGENTS.md

AGENTS.md — How Humans and Agents Operate in Grasshopper

Grasshopper is a fully open product: open code, open specs, open design, open decisions, public roadmap. This file is the contract for everyone who changes the project — human or AI. It is enforceable. If a change violates it, the change is wrong, not the rule.

For engineering specifics (tech stack, data model, naming, module rules) see ENGINEERING.md. For visual direction see DESIGN.md and design/principles.md. This file governs how change happens.

---

1. Principles (non-negotiable)

1. Open by default. Publish the reasoning, not just the result. If there is no concrete reason to keep something private, it is public.
2. Document before building. Non-trivial change starts as a written proposal (RFC), not as a pull request.
3. Decisions must be traceable. Every decision links idea → discussion → decision (ADR) → implementation (PR) → release. No orphan changes.
4. Product, Design, and Engineering are equals. A design or product proposal is a first-class contribution, not a request for engineering.
5. Lazy stays lazy. This process governs change, not effort. A typo or a one-line fix needs no ceremony. The bar scales with blast radius.

---

2. Responsibilities of Agents

When acting on this repository, an agent MUST:

• Write an RFC before any major change. "Major" = new feature/module, schema or data-model change, new dependency, public API change, design-system change, governance change, or reversing a prior ADR.
• Link every change to an issue or spec. A PR with no linked issue/RFC is incomplete.
• Record decisions as ADRs. When a choice is made between alternatives, write the ADR (context, options, decision, consequences) and link it.
• Update documentation in the same change. Code that changes behavior updates the relevant doc (README, ENGINEERING, DESIGN, roadmap) in the same PR.
• Ship a test with non-trivial logic. A PR that adds or changes non-trivial logic includes a test in the same change and must not lower the coverage gate (see ADR-0011 and ENGINEERING.md). Logic that isn't unit-testable in place is extracted into a pure helper under src/lib and tested there.
• Verify green before pushing. Run pnpm verify (typecheck + lint) before pushing a branch. A branch that fails pnpm typecheck must not be pushed — typecheck is exactly what next build (Vercel) enforces. The .githooks/pre-commit hook runs it automatically as a hard gate; lint stays advisory until the current lint debt is cleared. See ADR-0012.
• Resolve merge conflicts cleanly. After resolving any conflict, re-run pnpm verify and scan the diff for accidentally duplicated blocks before committing. Never commit both sides of a hunk — a duplicated definition breaks the build.
• Record any gate bypass. git commit --no-verify is for emergencies only and must be called out in the PR description. A silent bypass is a silent change (see §4).
• Never introduce silent changes. No undocumented features, no quiet dependency additions, no schema drift, no behavior changes "while I was in there." If it wasn't asked for and isn't documented, don't ship it.
• Surface operational risk in the repo, not in private notes. Incidents, drift, and security concerns belong in /decisions or SECURITY.md, where humans can see them.