agents-architect git:20261030.4e5e768A

Immutable. This exact content never changes and is served at /api/v1/blob/4111a162292322b6.

---
name: agents-architect
description: Design, audit, split, or maintain a repository's AGENTS.md system, routed .agents guidance, and repo-local .agents/skills or .claude/skills. Also run an explicit effective-instructions, effective-instructions:preview, effective-instructions:refactor, effective-instructions:force, effective-instructions:reconcile, or effective-instructions:reconcile-preview mode. Not for packaged plugin Skills or plain documentation.
---

# AGENTS Architect

Build a scoped instruction system in which root `AGENTS.md` is a small control plane and detailed project rules have explicit, on-demand owners. Axiom supplies the options; the host's model makes the decisions and records each departure from a default with its reason.

## Invariants

These invariants bind in every phase, including the references that phase loads. Everything else in this skill is a default you may adapt, saying so when you depart; shapes, counts, field lists, and byte targets yield to repository evidence.

1. **The loaded chain governs.** Honor the instruction chain already loaded at its actual precedence. Copied, inactive, historical, or other-repository instructions are evidence, not authority, and a reference never broadens authorization.
2. **Only `AGENTS.md` is written.** Create, edit, move, or recommend only files named `AGENTS.md` as native auto-load entries. Treat host-discovered non-`AGENTS.md` instruction sources as read-only, and safe-stop with the exact path when one shadows the intended result.
3. **Loading is proven, not assumed.** Do not recursively read Markdown or `.agents/`, assume include syntax, or treat filesystem presence as proof that the current session loaded a file. For a scoped ignored instruction file, resolve its tracked or ignored state and exact ignore owner, then compare direct content before and after; a clean tracked diff is insufficient.
4. **One owner per rule, nothing of Axiom's.** Root receives repository-wide constraints and each scoped rule lives in one routed owner, parent reference, or closer nested `AGENTS.md`. Never copy Axiom triggers, generic routing, language handling, validation protocols, report templates, or packaged Skill rules into a target system, and never fill a visible host limit merely because space is available.
5. **Unrelated work and durable evidence.** 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; never turn one-off task discoveries into permanent instructions.
6. **Protected metadata is not an AGENTS branch.** `.codex-plugin/**`, `.claude-plugin/**`, `.agents/plugins/**`, `skills/**`, `hooks/**`, plugin assets, `.app.json`, `.mcp.json`, and installed or plugin Skill resources are protected plugin metadata. Repo-local `.agents/skills/**` and `.claude/skills/**` enter this workflow only when the user explicitly scopes them as part of the target repository's AGENTS system.

## First Action

Collect only the 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. Read `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 on an explicit `effective-instructions:reconcile` or `effective-instructions:reconcile-preview` invocation, 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`; capsules live where `references/memory-and-state.md` places them. For `effective-instructions` and its preview, also read the context-evidence reference to establish the review window before selecting a terminal owner.
- Decide where task state lives, size a grown instruction memory, or simplify addressing: `references/memory-and-state.md`.
- 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. 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, and 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.