# Agent Rules

These rules apply to every AI agent working in this repo.

## Read First

Before changing files, read:

- `README.md`
- `docs/product/problem.md`
- `docs/ops/build-loop-target.md`
- `docs/ops/build-loop-tests.md`
- `docs/ops/build-loop-test-areas.md`
- `docs/ops/customer-readiness-tests.md`
- `docs/ops/build-loop-done.md`
- `docs/ops/build-order.md`
- `docs/ops/overnight-agent-instructions.md`
- `docs/engineering/repo-rules.md`
- `docs/engineering/stack-decision.md`
- `docs/engineering/architecture.md`
- `docs/engineering/data-model.md`
- `docs/engineering/performance-data-model.md`
- `docs/engineering/mcp-contract.md`
- `docs/engineering/mcp-overlap-contract.md`
- `docs/engineering/session-context.md`
- `docs/engineering/overlap-precision.md`
- `docs/engineering/auth-plan.md`
- `docs/engineering/security-checks.md`

Before any frontend/UI work, also read:

- `DESIGN.md` — design directives (brand, tokens, voice, density anchor)
- `design-system/` — vendored design system (tokens, assets, UI kit)

## Hard Rules

- Frontend/UI changes must follow `DESIGN.md` and the design system in
  `design-system/`: use the design tokens, reuse the primitives in
  `src/features/console/ui/`, and never reintroduce the old light theme.

- No file may exceed 300 lines.
- Put files in the right folder. Do not dump files in the repo root.
- Keep documentation up to date with every meaningful change.
- Do not add code, snippets, or files for deferred features.
- Do not leave dead files, unused components, or fake placeholder systems.
- Do not store core app state in Markdown.
- Do not commit secrets, tokens, local databases, or generated junk.
- Run security checks before claiming work is done.
- If a trusted open-source project with at least 1,000 stars solves a problem, study it before building from scratch.
- Only reuse open-source code when the license allows it, the dependency is maintained, and the security risk is acceptable.
- MCP warnings and blocks must be returned to agents, not only shown in the UI.
- Every MCP tool call must write a usage event.
- Every work-state change must write a work event.

## Overlap Protocol (judge before you start)

When you take on work, you are the judge of whether it duplicates someone else's.

1. Call `covibe_task` with `operation: "check"`, `title`, `description`, a
   short `scope` (what the work actually is), and the REQUIRED `task_type`
   (`feature|bug|refactor|chore|docs|test|spike`). Keep the returned `check_id`.
   Optionally declare `action` (`create|modify|remove|fix|audit`) and
   `component` (a layer tag like `server`/`client`) — they sharpen precision so
   work on a different layer or with an opposed action is not flagged as a
   duplicate.
2. If it returns `ok`, start normally — an `ok` check never blocks the start.
   Weak or divergent matches may still appear in `data.matches` (with
   `warning_id`, score, and reason); they are recorded for the dashboard and are
   informational only — see `docs/engineering/overlap-precision.md`.
3. If it returns `warning` with `requires_verdict: true`, read each candidate in
   `data.candidates` (each carries its score and reason) and decide whether YOUR
   task is the SAME SCOPE as it. A candidate of `type: "intent"` is another
   agent reserving that work right now — treat it like real work. Matches
   against `done`/`cancelled` work only inform; they never escalate or block.
4. Call `covibe_task` with `operation: "start"`, the `check_id`, and a
   `scope_verdict`:
   `{ same_scope_candidate_ids: [...], reason: "..." }`. List the ids of every
   candidate that is genuinely the same scope (empty if none); always give a
   reason.
5. If you listed any id, it is a real duplicate: tell the developer, get their
   call, and pass `confirmation_reason` on the retry. Do not self-approve a true
   duplicate.
6. A match flagged `action_divergent: true` is opposed work on the same thing
   (create vs remove). It never blocks, but if your task would undo or reverse
   that owner's work, raise it with the developer before starting.
7. Before editing files, check `covibe_team` `operation: "state"` →
   `repo_snapshot_conflicts`: a teammate (or your own other agent session) may
   have uncommitted or unpushed edits on the same files. Coordinate via
   `covibe_coordination` `operation: "ask_peer"` or use a separate worktree.
   Claude Code sessions also receive these conflicts automatically as hook
   context at session start/stop.

The server records your verdict and gates the start on it. A start blocks ONLY
on the escalated (`requires_verdict`) path or on an agent-confirmed duplicate
missing its `confirmation_reason` — and the block message itself says what to
send next. Judge honestly — the verdict is audited.

## Done Means

Work is done only when:

- the app starts locally
- required tests pass
- security checks pass
- docs match the implementation
- the morning report explains what changed, what passed, what failed, and what a human should try first