Summary
Our current agent guidance covers how code is structured (architecture layers, code style) and what CI must pass (lint, format, typecheck, tests, expo-doctor). It does not yet capture the delivery judgment a senior reviewer applies. This issue adds that layer as forward-looking, general engineering norms that any coding agent or tool can read.
Motivation
Green CI and clean architecture do not by themselves mean a change is done or appropriately scoped. We want a shared, tool-agnostic contract that encodes a few healthy defaults so agents (and humans) converge on the same standard.
Proposed guardrails
- Done = acceptance criteria, not green CI. Every unmet AC is either implemented or explicitly waived in the ticket with a linked follow-up issue. A note in the PR body is not a waiver.
- One ticket = one PR. Do not implement or stub adjacent tickets unless the ticket asks for it. Prefer a thinner slice; split by layer or get approval before landing a change that spans UI + native + DB + filesystem.
- Abstraction budget. No use-case-agnostic framework/adapter/generic layer unless a second real caller exists today or the ticket asks for it.
- Human-only verification gates. Changes touching native modules or mic/camera/filesystem/permissions require Android device QA that CI cannot satisfy; the PR stays draft/changes-requested until a human records device results.
- Agent-authorship is a review heuristic. On agent-assisted feature PRs, review scope, abstraction, and AC-vs-CI first — a neutral prioritization, not a criticism.
Scope
- Add a root
AGENTS.md as the canonical, tool-agnostic home for these guardrails (readable by Cursor, Codex, Copilot, Aider, Gemini CLI, and humans).
- Add a thin always-on Cursor rule (
.cursor/rules/agent-guardrails.mdc) that points to AGENTS.md.
- Cross-link from
.cursor/rules/delivery.mdc and docs/AGENT_ONBOARDING.md.
- Surface the same gates as checkboxes in the PR template and reference them in the
/create-pr command.
Acceptance criteria
Verification
Docs/process only. npm run format:check and npm run lint pass. No app-code, test, or CI-workflow changes.
Summary
Our current agent guidance covers how code is structured (architecture layers, code style) and what CI must pass (lint, format, typecheck, tests, expo-doctor). It does not yet capture the delivery judgment a senior reviewer applies. This issue adds that layer as forward-looking, general engineering norms that any coding agent or tool can read.
Motivation
Green CI and clean architecture do not by themselves mean a change is done or appropriately scoped. We want a shared, tool-agnostic contract that encodes a few healthy defaults so agents (and humans) converge on the same standard.
Proposed guardrails
Scope
AGENTS.mdas the canonical, tool-agnostic home for these guardrails (readable by Cursor, Codex, Copilot, Aider, Gemini CLI, and humans)..cursor/rules/agent-guardrails.mdc) that points toAGENTS.md..cursor/rules/delivery.mdcanddocs/AGENT_ONBOARDING.md./create-prcommand.Acceptance criteria
AGENTS.mdexists at repo root, plain markdown, no tool-specific frontmatter.AGENTS.mdwith no duplicated prose.delivery.mdcandAGENT_ONBOARDING.mdlink to the guardrails.Verification
Docs/process only.
npm run format:checkandnpm run lintpass. No app-code, test, or CI-workflow changes.