AGENTS.md · BuilderIO/agent-native

Sections

1. Skills
2. Always-On Rules
3. Final Status Block
4. Checks
5. Architecture Contract
6. Data And Security
7. Frontend And UX
8. Packages And Releases
9. Extensions

First lines (shown under the repo's MIT license)

# Agent-Native Framework

This repository builds apps where the AI agent and UI are equal partners:
everything the UI can do, the agent can do through the same SQL data and action
surface. Keep this file small: the rules below are the invariants, and
`.agents/skills/*` carries the workflow. Read the relevant skill before changing
that area.

## Skills

`.agents/skills/` holds detailed area guidance; each `description` says when to
read it. Read the matching skill before changing that area. Skill rules govern;
this file records only invariants.

A few entry points:

- `adding-a-feature` — four-area feature checklist.
- `decisions` — when using capability-aware classification and scoring.
- `content-product-development` — Content's product contract and shared changes.
- `writing-agent-instructions` — before editing instructions, skills, or tool/action descriptions.
- `verifying-changes` — exercise the broken path before calling a fix done.
- `adding-tests-and-ci` — before adding tests, CI jobs, or workflow triggers.
- `test-audit` — test changes.
- `reporting-progress` — during long runs and before asking for status.
- `concurrent-agents` — before shared-checkout work.
- `ship` — guarded shipping; beta/docs deploy automatically, other production promotion is manual.
- `ship-and-monitor` — requested post-merge checks or beta risks local proof cannot cover.
- `ship-now` — fast admin merge with post-merge monitoring.

Use `/sidecar <task>` for read-only investigations.

## Always-On Rules

- Scale effort: for small changes, read briefly, edit, and run existing checks;
  skip surveys, unrequested tests, and browser automation. Explore deeply only
  for ambiguous or cross-cutting work.
- Keep routine replies concise: lead with the answer in 1–2 short sentences.
  Include only the requested detail and any essential result, blocker, or next
  step; omit recaps, process narration, and filler unless more detail is needed.
- Before finishing or handoff, close opened browser tabs/app sessions and stop
  started processes. Honor keep-open requests; stop only owned resources; report
  failures.
- A user's task-scoped authorization persists across replies, heartbeats, and
  compaction until complete or revoked. An affirmative answer resolves the
  pending action; do not ask again. Revalidate live ownership and state before
  writing; verification is not renewed approval. Ask only for scope beyond the
  authorization, a user-reserved boundary such as production promotion or
  contacting another person, a missing credential, a user-only decision, or a
  destructive data change. See `ship` and `new-branch` for covered git/PR work.
- Never add `Co-Authored-By` or other agent attribution to commits.
- Use the current suitable branch. PRs are ready for review unless drafts are
  requested.
- Deployment split: `.github/workflows/deploy-beta-sites-prebuilt.yml` is the
  sole beta publisher; Actions uploads prebuilt artifacts to independent
  `beta.*.agent-native.com` sites. Netlify Git builds are disabled; do not wait
  on their queues or previews. If beta deployment status is in scope, check the
  Actions run and built-in site smoke. Normal `/ship` does not monitor beta or
  claim beta health. Add an independent beta behavior check only when requested
  or a concrete beta risk needs proof local checks cannot cover; use
  `/ship-and-monitor`. The docs exception is `.github/workflows/deploy-docs-production.yml`:
  it publishes `fw` / `www.agent-native.com` from matching `main` changes and
  disables Git builds; there is no beta docs site. Other production promotion
  is manual through `.github/workflows/deploy-production-sites-prebuilt.yml` or
  `promote-netlify-deploy.yml`. Let workflows manage Netlify locks; clearing
  one does not promote production.
- When shipping from a worktree, commit, push, and open or update the PR there;
  leave the shared checkout untouched.
- Never push to another's PR without exact-PR authorization; merge authorization
  is separate unless the user explicitly authorized that exact merge. See
  `ship`/`babysit-pr` for author/head checks.
- On your own PRs, replies to every review thread you fix or disposition are
  always authorized and expected; add a concise top-level recap for review-body-only
  feedback. On others' PRs, comment only with explicit authorization for that
  exact PR; avoid unrelated comments, tags, and assignments.
- Use root `.tmp/` for repo-local temp files; it is gitignored.
- Never use `[codex]`, `codex`, or similar agent labels in user-visible GitHub
  metadata unless explicitly requested.
- Keep the chat title accurate.
- Follow `reporting-progress` for updates and mid-task stops.
- When adding package dependencies or framework integrations, verify the current
  latest version first with `npm view`/`pnpm view` or current docs. Do not rely
  on remembered versions.
- Never use `pnpm patch` or `pnpm patch-commit`, add
  `pnpm.patchedDependencies`, or commit dependency patch artifacts under
  `patches/`. Upgrade the dependency or fix app-owned code instead.
- A `catch`, default, or coercion that returns a value callers cannot
  distinguish from success is a bug, not a guard. "Absent" and "unreadable" must
  be different values; a truncated run is not a completed one; a dropped payload
  is not an empty one. This is the single habit behind the longest-running class
  of repeat user reports here: each layer coerces a failure into a clean value,
  so every layer above it reports something confidently wrong and nobody can see
  it. Prefer a loud, typed failure over a plausible-looking normal state.
- Before adding a condition to a function that already stacks several special
  cases, stop: that shape is how the same bug ships twice. Fix the boundary that
  made the special case necessary, and delete the ones it subsumes.
- Write code that reads like the surrounding code: match its comment density,
  naming, and idiom. When you do comment, comment a constraint the code cannot
  show — a non-obvious trap a future change would otherwise reintroduce — not
  what the next line does, why your change is correct, or where it came from.
- When changing docs under `packages/core/docs/content`, update the matching
  localized docs under `packages/core/docs/content/locales/*` when the source
  meaning changes. If translations cannot be updated in the same change, call
  out the specific locales that need follow-up; reviewers should flag docs
  changes that only update one language.
- During review, treat any user-facing copy change as a localization change:
  UI labels, buttons, tooltips, placeholders, errors, empty states,
  accessibility text, prompts, and documentation prose all need their English
  source and configured locale translations updated together. Run
  `pnpm guard:i18n-catalogs` and `pnpm guard:i18n-changed-copy`; do not approve
  an unexplained `i18n-copy-ignore` marker or localization baseline update.
- Docs-only commits start with `docs: ` in the present tense, e.g.
  `docs: fix broken link in provider API guide`, not `docs: fixed broken link`.

## Final Status Block

Every final response must end with a three-line status block:

```md
---

⠀
🟢 Actual concise status sentence
```

The words after the icon are a short, task-specific status written for this
response; never use the placeholder text `Brief status` literally. Use `🟢`
when the requested coding/work unit is finished on the current branch, even if
routine commit/PR/deploy/CI remains. Use `🟡` when non-routine work or a manual
step is still pending. Use `🔴` only when blocked on user input. When you use
`🟡`, the pending item must be legible from that one line alone — the user
should never have to reply asking what is not done.

## Checks

Rules here are carried by skills, not by blocking your tools. Two exceptions
exist, and both are narrow on purpose.

**Guards** (`pnpm guards`, and CI on every PR — these apply to Codex, Claude
Code, and a human equally). `pnpm guards --list` prints the current set;
`no-silent-coercion`, `no-raw-colors`, `no-boot-data-work`,
`no-heavy-dashboard-list-reads`, `no-unbounded-table-reads`,
`no-bare-error-in-actions`, `external-result-contract`,
`no-source-reading-tests`, `no-oracle-loosening`,
`no-raw-sql-interpolation`, `action-output-schema`,
`strict-lint`, and `compiler-strictness` check only lines this branch added,
so the
pre-existing backlog stays a separate cleanup. Each guard has a documented
opt-out pragma, and every opt-out is a decision a reviewer should see.
`no-new-legacy-mcp-hints`, `no-new-escape-hatches`, and `compiler-strictness`
have none: the MCP `destructiveHint` baseline, each file's count of `any`,
`!`, and suppression comments, and the list of tsconfig strictness opt-outs
only shrink.

A guard reports three outcomes, not two: exit 0 passed, exit 1 failed, exit 2
could not run. A diff-scoped guard that cannot resolve a base ref exits 2 via
`requireAddedLines`, and `pnpm guards` renders it SKIPPED and refuses to print
"All checks passed" — in CI it fails the run. Never reintroduce an `exit(0)`
for a check that inspected nothing; that is the flagship rule above, violated
inside the thing that enforces it.