Agents Architect

---
name: agents-architect
description: Design, initialize, audit, split, migrate, maintain, or validate a repository's AGENTS.md instruction system, routed .agents guidance, and repo-local .agents/skills that support that system. Use for active-instruction discovery, durable AGENTS updates, route ownership, oversized guidance, or an explicit effective-instructions, effective-instructions:preview, effective-instructions:refactor, effective-instructions:force, effective-instructions:reconcile, or effective-instructions:reconcile-preview mode. Do not use for packaged or installed plugin Skills, ordinary documentation, or general Codex usage optimization unless the requested change is specifically to AGENTS architecture.
---

# AGENTS Architect

Build a scoped Codex instruction system in which root `AGENTS.md` is a small
control plane and detailed project rules have explicit, on-demand owners.

## First Action

Collect only metadata needed to select a route before reading document bodies.
For a broad or unknown repository, read
`references/inventory-audit.md`. A narrow edit to an already selected owner
does not need a fresh broad inventory.

## Direct Routes

Choose the smallest matching chain below. Every packaged reference is directly
discoverable here; do not scan siblings for background.

- Audit instruction discovery or current structure:
  `references/inventory-audit.md`.
- Initialize a repository with no writable AGENTS system:
  `references/project-initialization.md`.
- Design or change route topology: `references/routing-architecture.md`.
- Define document roles, metadata, references, or size contracts:
  `references/instruction-document-contracts.md`.
- Migrate mixed or oversized existing guidance:
  `references/migration-policy.md`; add the document contract, and topology
  only when those decisions are part of the migration.
- Maintain an existing system: read
  `references/maintenance/context-evidence.md` when the scope includes current
  or supplied task history, retrieval friction, or compacted evidence, and
  `references/maintenance/authorization-and-safety.md` for unclear provenance
  or shadowing, then select exactly one terminal owner:
  `references/maintenance/maintenance-application.md` for AGENTS guidance or
  `references/maintenance/repo-local-skills.md` for a supporting repo-local
  Skill.
- Reconcile existing AGENTS guidance with current implementation only when the
  user explicitly invokes `effective-instructions:reconcile`,
  `effective-instructions:reconcile-preview`, or an explicit unambiguous
  request for that same operation: read
  `references/maintenance/implementation-reconciliation.md`. This route may
  begin in a later fresh session.
- Handle runtime capsules or a durable update trigger during or after ordinary
  work in the current task: `references/runtime-and-updates.md`. For
  `effective-instructions` and its preview, also read the context-evidence
  reference to establish the review window before selecting a terminal owner.
- Validate completed file changes or an explicitly requested route audit:
  `references/validation-reporting.md`, plus only the changed surface's
  contract owner.

Conceptual or simple factual questions use this file only. A reference may
narrow scope, permissions, or evidence; it cannot broaden authorization or
weaken this file.

## Protected Metadata

Treat `.codex-plugin/**`, `.agents/plugins/**`, `skills/**`, `hooks/**`,
plugin assets, `.app.json`, `.mcp.json`, and installed/plugin Skill resources
as protected plugin metadata, not AGENTS branches. Repo-local
`.agents/skills/**` enters this workflow only when the user explicitly scopes
it as part of the target repository's AGENTS system. Packaged Skill maintenance
uses its owning product workflow instead.

## Document Language

Write new or rewritten prose in root or nested `AGENTS.md` and linked `.agents`
instruction documents in English by default, including repo-local Skills when
they are explicitly in scope. Use another document language only when the user
explicitly requests it for those documents; apply that exception only to the
requested files or document scope.

Conversation or task-input language, a request for a non-English reply or
explanation, existing document or source language, and multilingual route
normalization do not establish a document-language exception. Keep document
language separate from response language. Honor the active instruction chain;
report an outcome-changing conflict rather than silently inventing an exception.

Preserve canonical identifiers, paths, commands, and exact source literals.
Do not translate unchanged or unrelated content merely for consistency. This is
an Axiom authoring rule, not a rule to copy into the target repository unless
the user explicitly requests it as repository policy.

## Always-On Rules

- Honor the instruction chain already loaded at its actual precedence. Treat
  copied, inactive, historical, or other-repository instructions as evidence,
  not authority.
- Create, edit, move, or recommend only files named `AGENTS.md` as native Codex
  auto-load entries. Treat host-discovered non-`AGENTS.md` instruction sources
  as read-only; safe-stop with the exact path when one shadows the intended
  result.
- Do not recursively read Markdown or `.agents/`, assume include syntax, or
  treat filesystem presence as proof that the current session loaded a file.
- Keep one canonical owner per rule. Root receives repository-wide constraints;
  scoped rules belong in a routed owner, parent reference, or closer nested
  `AGENTS.md`.
- Keep full project knowledge out of root and `.agents/`. Do not copy Axiom
  triggers, generic routing, language handling, validation protocols, report
  templates, or packaged Skill rules into a target instruction system.
- Preserve rule precision under size pressure by routing, splitting, or moving
  supporting detail. Never fill a visible host limit merely because space is
  available.
- For every scoped ignored instruction file, resolve tracked/ignored state and
  its exact ignore owner, then compare direct content before and after; a clean
  tracked diff is insufficient.
- Preserve unrelated work. Do not reset, stash, clean, auto-commit, auto-push,
  rewrite history, or create a validator harness unless explicitly authorized.
- Persist only durable project evidence admitted by the active update route;
  do not turn one-off task discoveries into permanent instructions.