Co-VibeDocs

Overview

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
View as .md