AGENTS.md — Agent Router

This file is the entry point for any AI agent interacting with this design system. Read this file first. Always. Type: instruction Logical path: AGENTS.md Author: Guilherme Negreiros Read before: DESIGN.md Relations: DESIGN.md, governance/rules/project-overview.md, governance/instructions/codebase-context.md, How-to-without-agents.md (fallback if agents are unavailable)

Core principle

The human always has the final word. Agents execute, propose, and detect drift. Strategic decisions, exceptions, and values belong to the teams.

Available agents

Designer Agent

Role: Monitor drift in Figma Can: Detect detached instances, components without a description, inconsistent spacing Cannot: Automatically modify Figma files Produces: Drift reports — human approval required before action

Developer Agent

Role: Detect token misuse in code Can: Detect hardcoded colors, deprecated tokens, duplicated components, open suggestion PRs Cannot: Merge without human approval Produces: Correction PRs — review required

Documentation Agent

Role: Keep docs in sync with components Can: Generate changelogs, migration guides, accessibility notes Cannot: Publish without validation Produces: Documentation drafts — human validation required

QA Agent

Role: Systematic checks before merge Can: Run accessibility tests, visual regressions, token conformance Cannot: Approve a merge Produces: Conformance reports — blocking on critical violations

Orchestrator

The orchestrator coordinates the agents. It decides:

• Which changes are safe to automate
• Which require human approval
• When to escalate to the team

Escalation rule: Any change touching a semantic token or a component contract is automatically escalated.

Files to read before any action

DESIGN.md                                    ← portable contract — always read first
governance/rules/project-overview.md         ← project context
governance/rules/tokens-system.md            ← token rules
governance/rules/ux-patterns-sources.md      ← sources + UX pattern review (before any component)
governance/rules/figma-components.md         ← Figma rules (properties, auto-layout, naming, API)
governance/instructions/codebase-context.md  ← technical context
governance/instructions/verification-standards.md ← how to verify and report your own work
governance/instructions/session-spec.md      ← condensed spec for this session
governance/ai-skills-reference.md            ← for non-Claude tools: what .claude/skills/ automates and how to reproduce it
tokens/semantic.json                         ← source of truth for UX intentions
decisions/                                   ← why decisions were made (ADRs)

What agents must never do

• ❌ Use a hardcoded color or spacing value
• ❌ Reference a primitive token directly in a component
• ❌ Modify a semantic token without an approved TCR
• ❌ Deploy to production without human validation
• ❌ Ignore an accessibility violation report
• ❌ Bypass lint rules
• ❌ Add a token field outside the annotation schema of ADR-102 — descriptions go in $description; team data goes in $extensions["com.agentica.usage"] (how to use a token) or $extensions["com.agentica.governance"] (contract of a file or component); never a new $-prefixed key

Project tracking and decision documentation

Project management

Task tracking (statuses, backlog, priorities, dependencies) lives exclusively in GitHub Projects — never in a versioned file in the repo. See governance/rules/project-overview.md (ADR-069).

Architectural decisions (ADR)

Decisions are documented in decisions/ (not docs/adr/) — one file per ADR, format ADR-XXX-title.md. Read the ADRs that touch the area you're about to work on before taking any action. See .claude/skills/pipelines/adr-triggers.md to know when to create a new one.

Domain context

No CONTEXT.md at the root — domain context lives in DESIGN.md (portable brand contract), guidelines/ (foundations and components), and the governance/rules/ rules.

Using a non-Claude AI tool

If you're Codex CLI or GitHub Copilot: .agents/skills/ already has working ports of Agentica's 7 core skills (open Agent Skills format — load them the way you normally load project skills, no setup needed). If you're Gemini CLI: .gemini/settings.json + .gemini/hooks/*.js already reproduce the ADR-trigger and UX-pattern-review reminder hooks natively.

Read governance/ai-skills-reference.md for what all of .claude/skills/ automates — including the pipeline checklists that aren't ported anywhere yet — and how to reproduce a control your tool doesn't have a working port for. If you're the first to wire this repo up for a tool that doesn't already have a governance/tool-parity/*.md file (check that directory first), you must add one (copy governance/tool-parity/ TEMPLATE.md) recording, for every mandatory control, either how it's replaced or why its absence is accepted. scripts/check-tool-parity.js (CI: .github/workflows/ tool-parity.yml) fails until that file exists and every row is signed off — it will not tell you the tool works correctly, only that a human made the call instead of the gap going unnoticed.