Codex Agent Team Sample

A shareable sample configuration for a hybrid Codex development team. It combines project-scoped custom agents, a repo-local plugin, prompt shortcuts, lifecycle hooks, command rules, and spec templates for a plan-build-review workflow.

Jump to Quick Start.

This repository is a sample configuration, not a production-ready control plane. Review every agent instruction, hook, rule, plugin file, and security note before using it on real projects.

Overview

The sample is built around a main-thread coordinator and six optional role agents. These published roles mirror their maintained definitions as of October 6, 2026:

.codex/config.toml defaults the main thread to openai.gpt-6.1-sol at medium, with 14 threads and depth 2. These are the maintained team’s exact model IDs and effort settings. This public repo omits private provider/backend configuration, credentials, region, profile, project trust, and account-specific settings. Configure a provider exposing these IDs before running agents; catalog-valid IDs do not guarantee account permission to invoke.

The sync includes current agent prompts, global guidance, the five team workflow skills, their Testing Standards reference, referenced standalone skills and spec templates. Public packaging retains repo-relative hook wiring, the marketplace, public plugin metadata and the additional pip-install approval rule. Personal default approval rules, installed caches, session state, logs, auth files and past task/review artifacts are excluded. The plugin version is 0.1.1+codex.20261005; restart the Codex thread after installing the refreshed public bundle.

The reusable workflow lives in the codex-agent-team plugin under plugins/codex-agent-team. The custom agents live in .codex/agents because Codex custom agents are project or user configuration files rather than ordinary plugin contents. The sample also includes AWS security review guidance, concurrent external-fetch guidance, git workflow guidance, AWS Core/AWS Data Analytics/Superpowers plugin routing, and project-scoped MCP entries for AWS IaC help, Context7, and DeepWiki.

Mental Model

Codex does not need a large team for every request. The default coordinator is still the main Codex thread. Use role agents when the work benefits from parallelism, role specialization, or a dedicated review gate.

The workflow has three practical rules:

1. Put durable planning artifacts in .codex/specs//.
2. Split parallel work by files or ownership boundaries.
3. Give each independently reviewable task group a durable group identifier and its own non-resetting three-cycle review budget.

This sample does not provide a shared task database. Coordination happens through explicit prompts, repo-local spec files, and main-thread consolidation.

Parallel Worker Pools

The installed team can run multiple instances of the same role when the work is genuinely file-disjoint. The public sample config sets .codex/config.toml to max_threads = 14 and max_depth = 2, which leaves room for the largest intended first-level worker pool and explicit recursive delegation. The main Codex thread is the preferred lead; fullstack-agent can also produce a spawn plan when the user explicitly asks for a lead profile.

These are ceilings, not quotas. Use fewer agents when there are fewer independent scopes, and serialize any work that must touch the same files. Codex does not provide Claude-style shared task tools in this workflow, so the coordinator assigns each spawned instance an explicit name, file scope, expected output, and verification command.

The earlier disposable smoke project has been removed. Validate model access, pool behavior and trusted hook execution in your own sandbox before production use. Local checks establish configuration and prompt consistency; they do not prove provider inference, future model compliance or cloud behavior.

How The Workflow Runs

For non-trivial work, the flow is:

1. Capture requirements in .codex/specs//requirements.md or create an initial spec.md.
2. Create or refine spec.md, design.md, and tasks.md.
3. Partition tasks into stable, independently reviewable task groups with durable group identifiers, then into small file-disjoint waves.
4. Spawn role agents only for slices that can proceed independently.
5. Give each spawned agent an explicit prompt with its role, spec path, file scope, expected output, and verification command.
6. Wait for all requested agents, then consolidate their results in the main thread or fullstack-agent.
7. Select review-lite-agent for mechanical/docs-only or narrow low-risk fixes; use review-agent for standard-risk changes. A synthesizer spawn consumes the named task group’s next cycle.
8. A group FAIL in cycle 1 or 2 may create one scoped fix wave. Group cycle 3 is terminal; preserve evidence and report that group BLOCKED rather than spawning its cycle 4.
9. After all required groups PASS, review integrated seams and final gates in review-e2e.md under its separate non-resetting three-cycle budget. This cannot bypass an exhausted group.

The synthesizer alone issues the verdict. Critical/Severe/High findings or failing executed tests produce FAIL; lower-severity findings and open required runtime gates remain explicit. PASS does not close an unexecuted acceptance gate. Analyst evidence uses unique append-only scratch filings outside the spec tree; the synthesizer reads and reconciles the original findings before writing.

Specs created during real work are ignored by .gitignore; they are runtime project artifacts, not part of this reusable sample.

When To Use Each Agent or Skill

Prerequisites

• Codex installed and authenticated.
• Python 3.11+ on PATH for the complete validation suite. The hooks themselves use only the Python standard library and remain compatible with Python 3.8+.
• A git repository root. Hook commands resolve repo-local paths with git rev-parse --show-toplevel.
• A trusted Codex project. Project .codex config, agents, hooks, and rules load only after you trust the project.
• For the AWS-optimized path, install and enable aws-core@agent-toolkit-for-aws, aws-data-analytics@agent-toolkit-for-aws, and superpowers@openai-api-curated. The sample .codex/config.toml reflects those enabled plugins.
• Optional: organization approval for Codex, OpenAI usage, plugin distribution, hooks, and any future MCP/server integrations.

Quick Start

1. Clone or copy this repository.

2. Open Codex from the repository root and mark the project trusted when prompted.

3. Register the repo marketplace:

codex plugin marketplace add /absolute/path/to/sample_codex_agent_team

4. Open /plugins, switch to the Sample Codex Agent Team marketplace, and install Codex Agent Team.

5. Install or enable the companion plugins if your environment has access to their marketplaces:

aws-core@agent-toolkit-for-aws
aws-data-analytics@agent-toolkit-for-aws
superpowers@openai-api-curated

6. Start a new Codex thread so plugin skills, commands, and custom agents are discoverable.

7. Start with an explicit workflow prompt:

Use the Codex hybrid team to plan this feature. Create a .codex/specs plan, split implementation into file-disjoint scopes, spawn role agents where useful, and run an independent review wave.

For a rough idea, use the brainstorm command or skill:

Use $team-brainstorm for: 

For an existing spec, use:

Use $team-spec-workflow for .codex/specs/. Build the next file-disjoint wave, then run review.

Personal Marketplace Install

If you want this sample to load from your default personal Codex marketplace instead of registering the repo marketplace, use the installer script:

python3 scripts/install_personal_plugin.py --refresh-cache

The script updates ~/.agents/plugins/marketplace.json, creates the canonical ~/plugins/codex-agent-team symlink to this repo’s plugins/codex-agent-team, and refreshes the installed plugin cache with codex plugin add codex-agent-team@personal.

This path matters: in the default personal marketplace, ./plugins/codex-agent-team resolves to ~/plugins/codex-agent-team, not to ~/.codex/plugins/codex-agent-team and not to ~/.agents/plugins/plugins/codex-agent-team. Do not also symlink the plugin skills into ~/.agents/skills; duplicate discovery can surface duplicate skill selectors. If skills or role agents are present on disk but missing in a new Codex thread, verify the canonical symlink and rerun the installer.

If ~/plugins/codex-agent-team already points to an older or private copy that you intentionally want to replace with this public sample, rerun with:

python3 scripts/install_personal_plugin.py --force --refresh-cache

Common Usage Prompts

Create requirements from an idea:

Use $team-brainstorm for a small internal dashboard that tracks service deployment health, owners, and stale alarms.

Plan a feature before coding:

Use the Codex hybrid team for this feature. Create .codex/specs/deployment-health/, write spec.md, design.md, and tasks.md, then propose the first implementation wave before editing code.

Run parallel implementation:

Use fullstack-agent as the coordinator. Split the work in .codex/specs/deployment-health/tasks.md into file-disjoint coding and devops scopes. Spawn up to 6 coding-agent instances and up to 2 devops-agent instances only where the files do not overlap, wait for all of them, and consolidate.

Run a focused review:

Use review-agent to review the changes against .codex/specs/deployment-health/. If the changed files are separable, split review across up to 4 review-agent instances. Return findings by severity, exact verification evidence, open live gates, and one authoritative verdict for the named scope.

Run a lightweight review:

Use review-lite-agent to review this docs-only diff against .codex/specs/deployment-health/. Prove the diff shape, cite matching verified evidence, and report any escalation or remaining coverage gap.

Request architecture advice:

Use sa-agent to review the proposed design in .codex/specs/deployment-health/design.md for reliability, operational risk, cost, and security. Write findings to sa-review.md.

Audit your Codex setup:

/optimize-my-codex

Scope the audit to one area:

/optimize-my-codex agents
/optimize-my-codex hooks
/optimize-my-codex plugins

Repository Layout

.
|-- .agents/plugins/marketplace.json     # Repo marketplace exposing the plugin
|-- .codex/
|   |-- agents/                          # Custom Codex subagent roles
|   |-- config.toml                      # Shared subagent thread/depth defaults
|   |-- hooks.json                       # Repo-relative lifecycle hook wiring
|   |-- hooks/                           # Fail-open session/subagent loggers
|   `-- rules/                           # Command approval rules for risky operations
|-- plugins/codex-agent-team/
|   |-- .codex-plugin/plugin.json        # Plugin manifest
|   |-- commands/                        # Prompt shortcuts
|   `-- skills/                          # Team workflow skills
|-- docs/design.md                       # Architecture and design notes for this sample
|-- docs/specs/templates/                # Starting templates for .codex/specs work
|-- scripts/install_personal_plugin.py   # Optional personal-marketplace installer
|-- scripts/test_prompt_invariants.py    # Six-agent prompt, portability and matrix regressions
`-- SECURITY.md                          # Threat model and user responsibilities

Key Concepts

Agents

Agents are .toml files in .codex/agents. Each file defines a name, description, explicit model, model_reasoning_effort, optional nickname candidates, and detailed role-specific developer instructions. The descriptions tell Codex when a role is appropriate; the full prompts preserve role ownership, approval boundaries, learned failure modes, required evidence, output contracts, and stop conditions.

The prompts intentionally constrain agents to their assigned scope:

• fullstack-agent owns requirements, contracts, file-disjoint waves, worker liveness, consolidation, closure, and each task group’s three-cycle review budget; it returns a Spawn Plan when nested delegation is unavailable.
• coding-agent may run as coding-1 through coding-6; each instance follows exact-file ownership, TDD/debugging routes, interface contracts, CI-blocking verification, and task-local documentation close-out.
• devops-agent may run as devops-1 or devops-2; each instance checks caller-input precedence, pipeline status, parsed-output isolation, authoritative state backends, teardown residue, rollback, and open live validation.
• review-agent may run as one synthesizer plus up to three analysts; analysts return evidence-backed slice findings, while only the synthesizer owns review.md and the PASS/FAIL verdict.
• review-lite-agent first reads the project’s .codex/agents/review-agent.toml, using the user-home definition only when no project definition exists. A missing or unreadable selected definition stops the review. It keeps the same authority and cycle budget, reuses exact-subject evidence, and runs no analyst or mutation campaign.
• sa-agent covers all six Well-Architected pillars and produces concrete current-source, ownership, rollout, rollback, cost, and residual-risk handoffs rather than generic advice.

Prompt optimization in this repository is behavior-preserving, not a line-count minimization exercise. Shorter text is not considered an improvement when it removes a measured safeguard, role contract, verification requirement, or stop condition. Reusable procedure stays in progressively loaded skills so detailed role prompts remain focused on role-specific failure prevention.

Plugin

The repo-local plugin lives at plugins/codex-agent-team. Its manifest points Codex at the skills/ directory and exposes prompt shortcuts under commands/.

Install it from the repo marketplace when you want the reusable workflow in a Codex session. Keep the plugin small and reviewable: the plugin itself does not bundle executable MCP servers, app integrations, dependency installers, or network scripts. Project-scoped MCP server configuration lives separately in .codex/config.toml.

Skills

Skills are reusable instructions that the main thread or agents load on demand.

The AWS security guidance strengthens AWS-facing planning and review by making data controls explicit: KMS encryption, TLS enforcement, S3 Block Public Access, access logging, data-classification tags, least-privilege IAM, production-readiness checks, and .codex/specs// security evidence for durable review notes.

Plugins And MCP Servers

The sample expects current AWS facts to come from installed AWS plugins, not from legacy standalone AWS MCP endpoints. Project-scoped MCP servers are configured in .codex/config.toml; plugin-provided MCP tools are supplied by the installed plugins themselves. Review these entries before use because some servers start local uvx or npx processes and may download packages or access remote documentation services.

Companion plugin routing:

Configured project MCP servers:

Commands

Prompt shortcuts live under plugins/codex-agent-team/commands.

Commands are convenience wrappers. The same workflows can be invoked by naming the skills directly in a prompt.

Use /optimize-my-codex after Codex updates, model changes, plugin changes, or when a local setup feels slow, noisy, stale, or inconsistent. Pass an optional focus area such as config, agents, hooks, rules, skills, plugins, marketplace, or commands to limit the audit:

/optimize-my-codex rules

The command presents findings and one exact migration set first, then waits for approval. Once approved, it applies the complete migration automatically without per-file confirmation and validates changed JSON, TOML, YAML, skills, plugins, hooks, and model assignments as applicable.

Specs

Runtime specs live under .codex/specs//. The sample includes templates in docs/specs/templates/. The public spec skill checks project-local .codex/specs/templates/ first, then the published templates, before user-home templates or its inline structures.

Common artifacts:

Testing And Evidence

The Testing Standards reference plans applicable T1 unit, T2 integration, T3 deployed service and T4 end-to-end checks. Trace producer/consumer contracts and denied calls, bound fixtures and validate an unmutated copy before perturbations, and use the application’s identity for deployed evidence. UI claims require browser inspection where applicable. Reuse proven evidence only when subject, command and environment match; re-run changed, missing or concretely doubted checks. Static validation cannot substitute for required live behavior.

Hooks

Hooks are configured in .codex/hooks.json and implemented in .codex/hooks.

The hooks are intentionally lightweight:

• They use only Python standard-library modules.
• They fail open so logging problems do not trap Codex.
• They filter incoming payloads to an allowlist.
• Session events write under ~/.codex/team-logs; subagent lifecycle events honor $CODEX_HOME/team-logs and otherwise use ~/.codex/team-logs.
• They rotate each log at 1 MiB with three backups.
• Subagent lifecycle writes and rotation are serialized with a file lock so parallel start/stop events do not race.

Review and trust hooks with /hooks before relying on them. Disable them in stricter environments if local metadata logging is not acceptable.

Rules

Rules in .codex/rules/codex-agent-team.rules keep selected high-risk commands explicit. They prompt or block operations such as:

• git push
• git push --force and git push --force-with-lease
• git reset --hard
• git clean
• gh pr create
• python3 -m pip install
• cdk deploy and cdk destroy
• terraform apply and terraform destroy
• sam deploy and sam delete
• aws cloudformation deploy and aws cloudformation delete-stack
• aws s3 rm and aws s3 rb
• kubectl delete
• docker system prune

Rules reduce accidental risky operations and keep dependency installs explicit. They do not replace sandboxing, code review, least-privilege credentials, project-local dependency isolation, or careful approval decisions.

Writing Good Subagent Prompts

Subagent prompts should be concrete enough that the agent can finish without inventing scope.

Include:

• Role agent to use.
• Instance name when using a pool, such as coding-3, devops-1, or review-api.
• Spec path and task or wave reference.
• Exact file scope.
• Expected output artifact or summary.
• Verification command or concrete evidence expected.
• Instruction not to edit outside the listed scope.
• Reminder that peer instances may be editing nearby files concurrently.
• Whether the coordinator should wait for all agents before consolidating.

Example:

Use coding-agent.
You are coding-3, one of up to 6 parallel coding instances.

Spec: .codex/specs/deployment-health/
Scope: implement the API response types in src/api/types.ts and tests in src/api/types.test.ts.
Do not edit files outside that scope. Other coding/devops instances may be running concurrently; do not overwrite their work.

Acceptance:
- Exports match the contract in spec.md.
- Invalid state names are rejected.
- Existing callers keep compiling.

Verify:
- npm test -- src/api/types.test.ts
- npm run typecheck

Return:
- Summary of changes
- Commands run and outcomes
- Any required scope expansion

Operating Safely

Use this sample with normal production safeguards:

• Treat unknown accounts, stages, clusters, and workspaces as production.
• Prefer read-only, list, describe, get, plan, synth, diff, and dry-run operations before mutating commands.
• Do not inline secrets in prompts, code, docs, config, tests, or command examples.
• Keep runtime specs, logs, local state, .env files, and provider credentials out of git.
• Use least-privilege credentials for investigation.
• Require explicit user direction and an impact statement before destructive operations.
• For ops smoke tests, require a disposable or non-production target, bounded retries and timeouts, abort criteria, and evidence capture before any external endpoint checks.

Troubleshooting

If a subagent fails before doing work with an engine routing error such as 404 Not Found: Engine not found, close that failed agent and retry the same bounded scope. If retries keep failing, use a currently supported role-appropriate model only after confirming availability, and record the override in the relevant spec or review artifact.

Customization

• Add or edit custom agents in .codex/agents/*.toml.
• Add workflow skills under plugins/codex-agent-team/skills//SKILL.md.
• Add prompt shortcuts under plugins/codex-agent-team/commands/.
• Add more marketplace entries in .agents/plugins/marketplace.json.
• Adjust subagent concurrency and recursion defaults in .codex/config.toml.
• Keep machine-specific provider settings, secrets, model providers, local paths, installed plugin caches, and runtime artifacts out of this repo.

When adding a new role agent, update:

1. .codex/agents/.toml
2. This README’s role tables
3. docs/design.md
4. Relevant skills or prompt shortcuts

Validation

Useful checks after editing:

python3 scripts/test_prompt_invariants.py -v
python3 .codex/hooks/test_subagent_lifecycle.py -v
python3 -m py_compile .codex/hooks/session_start.py .codex/hooks/subagent_lifecycle.py
python3 -m json.tool .codex/hooks.json
python3 -m json.tool .agents/plugins/marketplace.json
python3 -m json.tool plugins/codex-agent-team/.codex-plugin/plugin.json
python3 scripts/install_personal_plugin.py --dry-run
python3 -c "import pathlib, tomllib; files=[pathlib.Path('.codex/config.toml'), *pathlib.Path('.codex/agents').glob('*.toml')]; [tomllib.loads(p.read_text()) for p in files]"
ruby -e 'require "yaml"; ARGV.each { |f| YAML.load_file(f) }; puts "yaml ok"' plugins/codex-agent-team/skills/*/agents/openai.yaml

The prompt invariant suite checks all six model/effort pairs, the main-thread settings, README/design table parity, project-first lite inheritance, review/testing dependencies, public portability, and retained lifecycle and three-cycle contracts. The hook regression covers malformed payloads, allowlist filtering, fail-open behavior and race-safe rotation through the sidecar lock. No test command invokes a model or deploys cloud resources.

For plugin manifest validation, use Codex’s bundled plugin-creator validator if available:

python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/codex-agent-team

To check that Codex can load the project prompt/config context:

codex debug prompt-input "validate repo config"

If this command fails under a strict sandbox, rerun it in a normal shell or through your approved local Codex execution path.

Troubleshooting

Legal And Security Review

Before adopting this sample for organization use, complete your own approvals:

See SECURITY.md for the threat model.

License

This sample is licensed under the MIT-0 License. See LICENSE.