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.

## 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.