Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (27 loc) · 2.6 KB

AGENTS.md

File metadata and controls

41 lines (27 loc) · 2.6 KB
Raw

AGENTS.md — Agent Onboarding

If you are an AI agent, LLM, or automated contributor working on this repository, start here.

First Step — Always

Before doing any work, you must read the following file:

→ CLAUDE.md

CLAUDE.md is the source of truth for how to work with this repository. It contains project rules, constraints, and pointers to the full build brief.

Required Reading Order

  1. CLAUDE.md — Project instructions and working rules
  2. Docs/brief.md — Full build brief (the spec for what we're building)

Do not skip these. Do not skim. Read them in full before writing any code or making any decisions.

Read Docs/deployment.md as well before touching anything that has to reach production, or before concluding that a change "did not work". UOA is one half of an estate: a capability added here only takes effect once the consuming product redeploys and serves a new config JWT, and several of those pipelines have sat broken for weeks without anyone noticing.

Rules for Agents

  • Follow the brief. All implementation must align with Docs/brief.md. It is the single source of truth for the product.
  • Follow the working rules. CLAUDE.md defines how to behave in this repo.
  • Don't assume. If something isn't specified, ask. Don't invent features or fill gaps with guesses.
  • Don't delete. Never remove content from documentation unless explicitly told to.
  • Don't over-engineer. Build exactly what's specified, nothing more.
  • Raise conflicts. If you find a contradiction between files, flag it immediately rather than silently resolving it.
  • Keep API schema in sync. When adding/removing/changing any endpoint, update both API/src/routes/root/index.ts (endpoint schema) and API/src/routes/root/llm.ts (config docs). These are the machine-readable API contract.
  • Preserve the confidential exchange boundary. The /auth/token assertion grant stays domain-hash authenticated, verifies short-lived RS256 assertions through the source config JWKS, always re-resolves the current user and source-domain role, conditionally re-resolves org/team membership when the assertion selects a team, atomically consumes each source-domain jti once through accepted expiry plus clock tolerance, and issues only resource-bound RS256 tokens through /oauth/jwks.json. Never copy the domain bearer into token claims.
  • Commit and push every turn. After each turn, commit the files you touched in that turn and push them to the current branch. Keep the scope tight because there may be multiple agents or processes working in parallel.