This pack provides eight narrow, platform-native roles for Claude Code and Codex. It optimizes for result quality, explicit routing boundaries, current evidence, single-writer implementation, and real runtime verification.

Install

Scope	Claude	Codex
Project	`<project>/.claude/agents/*.md`	`<project>/.codex/agents/*.toml`
Personal	`~/.claude/agents/*.md`	`~/.codex/agents/*.toml`

Merge the individual files from this pack's matching .claude/agents/ or .codex/agents/ source directory. Create only the destination agents directory, enumerate every same-name target, abort if any collision exists, and only then copy the individual files. Never replace an entire destination .claude or .codex directory.

Run this project-scoped Claude example from the repository root after replacing the target-project placeholder:

$packRoot = (Resolve-Path '.\agents').Path
$projectRoot = (Resolve-Path 'C:\path\to\target-project').Path
$source = Join-Path $packRoot '.claude\agents'
$destination = Join-Path $projectRoot '.claude\agents'
New-Item -ItemType Directory -Path $destination -Force | Out-Null
$sourceFiles = @(Get-ChildItem -LiteralPath $source -File)
$collisions = @($sourceFiles | Where-Object {
  Test-Path -LiteralPath (Join-Path $destination $_.Name)
})
if ($collisions) {
  throw "Refusing to overwrite: $($collisions.Name -join ', ')"
}
$sourceFiles | Copy-Item -Destination $destination

For Codex, apply the same procedure with .codex\agents as both source and destination suffixes. Use the same collision check for personal destinations; overwriting is never the default.

Route work

Agent	Delegate when	Do not delegate when	Access
`codebase-mapper`	A task needs repository structure, ownership, entry points, data flow, or change-surface mapping before a decision	Current external documentation, implementation, or post-change review is the primary job	Read-only
`official-docs-researcher`	A decision depends on current official documentation, releases, schemas, supported models, or version-specific behavior	The answer primarily requires tracing local code or implementing a change	Read-only plus web access
`solution-architect`	Multiple viable designs or cross-component boundaries require explicit trade-offs before implementation	A small fix is already specified or the root cause is still unknown	Read-only
`root-cause-debugger`	A failure must be reproduced, isolated, and explained before a fix is written	The cause is established and implementation is authorized	Runtime-capable; source read-only
`change-implementer`	Requirements or root cause are clear and one scoped, complete change is authorized	The task is still exploratory, requires product direction, or asks only for review	Workspace write
`code-reviewer`	An existing diff or implementation needs correctness, regression, and maintainability review	Deep exploitability analysis or active implementation is the main task	Read-only
`security-reviewer`	Trust boundaries, attacker control, exploit paths, or security-impacting changes need specialist review	Generic correctness review without a meaningful security boundary is sufficient	Read-only
`runtime-verifier`	A completed change must be exercised through the real user-facing or integration boundary	Implementation is incomplete or only static analysis is requested	Runtime-capable; source read-only

Invoke roles

Claude can select agents from their descriptions. Codex custom-role selection is parent-mediated and must not be treated as guaranteed automatic routing. For high-stakes work, name the role explicitly and provide a self-contained target, goal, available evidence, constraints, success criteria, and required output.

claude --agent codebase-mapper -p "Map the request path for authentication. Do not edit files."
codex exec --strict-config --sandbox read-only "Spawn the codebase-mapper custom agent to map the authentication request path and return its response verbatim."

Quality workflow

codebase-mapper and official-docs-researcher may run independently when their inputs do not depend on one another.
solution-architect follows established repository and platform evidence.
For an unknown failure, root-cause-debugger reproduces and explains it before implementation.
One change-implementer owns all writes unless work is explicitly partitioned into independent surfaces.
After a diff exists, code-reviewer and security-reviewer may run independently.
runtime-verifier runs last against the completed change and the real user-facing or integration boundary.

Keep dependent phases sequential. Parallelize only independent read-heavy work, and keep write-heavy work single-owner.

Model policy — 2026-08-10

Claude Fable with maximum effort: official-docs-researcher and solution-architect.
Claude Opus with maximum effort: codebase-mapper, root-cause-debugger, change-implementer, code-reviewer, security-reviewer, and runtime-verifier.
Codex gpt-5.6-sol with maximum effort: every role.
Parent orchestration may use Ultra for genuinely divisible work; custom workers do not.

Permissions and live research

Child configuration expresses intent, not an absolute enforcement boundary. Parent Claude modes such as acceptEdits, bypassPermissions, and auto, and live Codex parent sandbox overrides, can override child restrictions. Use a constrained parent for enforcement, then inspect Git state and content state after every read-only invocation.

Codex documentation research requires live web search. If managed policy or provider restrictions prevent live search, official-docs-researcher must return STATUS: blocked instead of relying on stale or cached information.

Compatibility

VS Code and Copilot CLI can consume the Claude-format agents. GitHub.com cloud requires separate .github/agents/*.agent.md files; this pack intentionally does not duplicate the definitions there.

Validate

Use the native diagnostics and an explicit invocation:

claude doctor
claude --agent <name> -p "Perform the scoped task and return the ROLE and STATUS markers."
codex doctor --summary
codex exec --strict-config --sandbox read-only "Spawn the <name> custom agent and return its response verbatim."

Run a real smoke invocation for every role. Confirm its exact ROLE: marker, observable result, and side effects; after read-only work, confirm Git and content state are unchanged. Diagnostic success alone is not role-discovery or behavior proof.

Migration

The 109 generic or overlapping legacy personas, broken prose-only routing, stale version pins, and the third-party installer were removed deliberately. There are no compatibility aliases.

README.md

Quality-First Claude and Codex Agent Pack