Agent Operating Contract

Purpose

This file governs how coding agents and automation should operate in this repo.

• It does not override the product docs. It constrains how agents act within them.
• Humans own product authority. Agents execute within documented scope and the current repo architecture.
• Later unchecked phases in requiredStepsForSetup.md are not permission to start work.

Required Reading Order

Read these in order before planning or implementing changes:

1. README.md
2. docs/product.md
3. docs/features.md
4. docs/architecture.md
5. docs/DESIGN_GUIDELINES.md
6. requiredStepsForSetup.md

Authority Model

• Humans own roadmap, scope changes, releases, architecture shifts, permissions, and merge decisions.
• Agents work inside documented product scope and the current React architecture.
• If a requested change conflicts with the current architecture, propose the architecture change explicitly instead of smuggling it into an implementation task.

React Architecture Rules

• React 19 + MUI + Emotion are the canonical UI stack.
• Do not reintroduce direct DOM-rendered UI patterns into popup or dashboard surfaces.
• Keep src/domain/* React-free.
• Keep src/entrypoints/* thin. They bootstrap screens; they do not own product logic.
• UI reads and writes should flow through repositories and runtime clients, not direct chrome.storage access from UI code.
• Treat src/ui/providers.tsx and src/ui/theme.ts as shared repo contracts.
• Keep the layered boundary intact across src/ui/*, src/data/*, src/domain/*, and src/extension/*.

Agent Lanes

Humans

• Own roadmap, scope, releases, architecture, permissions, and merge decisions.

Jules

• Maintenance only.
• Allowed lanes:
  • Cartographer docs drift checks
  • Sentinel security hardening
  • Palette micro-UX and accessibility polish
  • Victor test reliability improvements
  • CI repair on Jules-created PRs
  • docs cleanup
• Jules may not self-start roadmap work.
• Jules schedules and lane prompts are configured in the Jules platform. Repo guidance for Jules platform setup lives in .jules/instructions.md.
• Jules branch names should follow jules/<workflow>/<change> for scheduled workflows or jules/<change> for manual tasks.
• Jules should not add explanatory comments for obvious code. Prefer clear implementation and explain intent, validation, and tradeoffs in the PR body.
• Dependency hygiene is currently handled by Dependabot and Renovate, not a Jules lane.
• Performance automation is deferred until explicitly approved.

Codex And Similar Interactive Agents

• Human-directed implementation only.
• Allowed lanes:
  • feature work within documented scope
  • refactors that preserve documented architecture
  • bug fixes
  • test improvements
  • documentation updates tied to requested work

Review Guidelines

Codex reviews should prioritize:

• product-scope drift, especially auth, backend, sync, or broad SaaS behavior
• Chrome extension permission changes and runtime-message validation risks
• layer-boundary violations across src/ui/*, src/data/*, src/domain/*, and src/extension/*
• direct Chrome storage or runtime access from React UI instead of repositories/runtime clients
• unnecessary code comments where clear code would be enough
• validation claims that do not match the files changed
• Jules PRs that are more than one small, high-confidence maintenance change

Blocked Work Without Human Approval

• product scope expansion
• manifest permission changes
• auth, account, or backend introduction
• major dependency shifts
• major architecture changes across ui, data, domain, and extension
• storage model redesign
• styling-system replacement

Doc Update Triggers

• Update docs/product.md or docs/features.md when behavior changes.
• Update docs/architecture.md when runtime flow, storage flow, repository contracts, providers, routes, or architectural boundaries change.
• Update ADRs under docs/decisions/ when theme, provider, styling, or other core technical decisions change.
• Update requiredStepsForSetup.md when setup or process expectations change.

Validation Requirements

• Run npm run check when a change touches:
  • src/**
  • tests/**
  • public/**
  • .github/workflows/*
  • .github/dependabot.yml
  • package.json
  • package-lock.json
  • build.cjs
  • tsconfig.json
  • eslint.config.mjs
  • vitest.config.mjs
• npm run check is the default full agent validation command because it already runs:
  • npm run lint
  • npm run typecheck
  • npm run test
  • npm run build
• For docs-only and governance-only changes touching only files such as:
  • *.md
  • CODEOWNERS
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/ISSUE_TEMPLATE/*
  • SECURITY.md
  • CONTRIBUTING.md
  • requiredStepsForSetup.md
• use npm run format:check only for that docs-only or governance-only path.
• Agents must not claim runtime, test, or build validation for docs-only work unless they also ran npm run check.
• If npm run check fails because of a pre-existing unrelated issue, the agent must say so explicitly and avoid claiming a fully green result.

Execution Defaults

• If docs conflict, follow the higher-precedence product, feature, or architecture doc and stop for human clarification on the conflicting part.
• Future ideas are not implementation approval.
• In Scope in docs/features.md means directionally allowed if explicitly requested and reviewed, not self-starting backlog permission.
• If a task would cross blocked lanes, stop and ask for explicit human approval first.

Explicitly Deferred

This file does not authorize or perform later setup phases.

• No GitHub Marketplace app installs in this phase
• No CLAUDE.md in this phase
• No branch protection or org-transfer work in this phase