Skip to content

Add agent delivery guardrails (AC, scope, abstraction, human QA) #159

Description

@mattrace-gloo

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

  • AGENTS.md exists at repo root, plain markdown, no tool-specific frontmatter.
  • Cursor rule points to AGENTS.md with no duplicated prose.
  • delivery.mdc and AGENT_ONBOARDING.md link to the guardrails.
  • PR template includes acceptance-criteria, scope, and honest device-QA checkboxes.
  • All content is principle-based and blameless (no individuals or specific PRs referenced).

Verification

Docs/process only. npm run format:check and npm run lint pass. No app-code, test, or CI-workflow changes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions