Core Concepts

Agents

Focused subagents with narrow responsibilities.

Subagents live in .codex/agents/*.toml and are intentionally narrow so routing stays predictable.

Codex Kit keeps responsibilities separate: agents own execution roles, skills own knowledge, and workflows own process.

Agent Design Principles

Use focused subagents for bounded work instead of one broad parallel swarm.
Prefer the narrowest agent that still matches the task.
Pass skills explicitly when they matter instead of assuming the agent name is enough.
Avoid parallelism when the result is needed immediately on the critical path.

Planning, sequencing, risks, and acceptance criteria.

Read-only repository mapping and dependency tracing.

Small, targeted code changes once the task is clear.

UI, component architecture, accessibility, and frontend behavior.

APIs, validation, data access, and server-side logic.

Schemas, migrations, indexes, queries, and data integrity.

Mobile UX, platform conventions, and runtime performance.

Reproduction, evidence gathering, and root-cause isolation.

Correctness, security, regressions, and missing tests.

Focused tests that prove intended behavior.

CI, environments, deployments, pipelines, and operations.

Read-only verification of framework and API behavior.

READMEs, setup guides, handoff notes, and technical docs.

Profiling, bottleneck analysis, bundle size, and runtime speed.

Threat review, auth flows, validation, and attack surface.

SEO, GEO, metadata, content structure, and citation readiness.

planner pairs well with planning, plan-writing, and architecture.
debugger pairs well with debugging, systematic-debugging, and testing-patterns.
reviewer pairs well with code-review, code-review-checklist, and release-readiness.
test-writer pairs well with testing-patterns, tdd-workflow, and webapp-testing.