Give Codex a disciplined, direct-first engineering operating model.
An open-source Codex playbook for installable instructions, self-contained skills, optional Luna/max assistance, independent review, and validation.
Install · Operating Model · Quick Start · Harness Editions · Why This Exists · Real-World Use · Evidence · What's Inside · Subagent Model · Task Graphs · Worktrees · Branch Lifecycle · Legacy Paths · Parallel Threads · Structure
Using Claude Code instead? Open the Claude Code edition.
The easiest install path is to give this repo URL to your coding agent:
Install this globally: https://github.com/ArcanEdge-AI/coding-agent-playbook-codex
Follow the repository's INSTALL.md exactly. Use full mode even when an older installation exists; do not infer support-only mode unless I explicitly request it. Preserve my existing instructions, back up anything you change, install the global instructions, self-contained skills, and custom subagents where supported, then report the installed files and validation results.
That is the intended public experience: users should not need to understand the file layout before installation. The agent should read INSTALL.md, clone or fetch the repo, install into user-level Codex/agent configuration locations, validate the result, and report what changed.
Support-only is an explicit pointer-only configuration, not an update mode. Use it only when the user confirms the global instructions already live in Codex Personalization:
Install this in support-only mode: https://github.com/ArcanEdge-AI/coding-agent-playbook-codex
I already added the global custom instructions manually. Follow INSTALL.md, but do not duplicate the full instructions into AGENTS.md. Install self-contained skills and custom subagents only.
This is more than one large AGENTS.md or a generic set of custom instructions. It is a reusable delivery model for real repositories, where local conventions, concurrent work, and incomplete evidence make a single giant context window a weak engineering process: the root agent acts as the senior engineer, while bounded supporting work is routed to an appropriate role using Luna/max when the task and available evidence justify it.
The root owns understanding, architecture, decomposition, routing, coordination, integration, acceptance, and final validation. Supporting roles can handle bounded planning, engineering, testing, documentation, and independent review; they do not replace human authority or root accountability. Every supporting role uses Luna with max reasoning, with bounded assignments and independently checked evidence.
It installs global instructions, self-contained reusable skills, and custom subagent profiles where Codex supports them. Each skill carries its own supporting references and templates. Try it with the one prompt above, then adapt the repository-level guidance to the codebase in front of you. You may fork, modify, redistribute, and test the approach under the MIT License.
Ask your coding agent to install the repo URL and follow INSTALL.md. Normal installs and updates use full mode.
git clone https://github.com/ArcanEdge-AI/coding-agent-playbook-codex.git
cd coding-agent-playbook-codex
python3 install/install.py --fullSupport-only mode:
python3 install/install.py --support-onlyDry run:
python3 install/install.py --full --dry-rungit clone https://github.com/ArcanEdge-AI/coding-agent-playbook-codex.git
cd coding-agent-playbook-codex
py -3 install/install.py --fullSupport-only mode:
py -3 install/install.py --support-onlyDry run:
py -3 install/install.py --full --dry-runCopy this template into individual projects as a starting point:
skills/reference-doc-routing/references/templates/repository-AGENTS.md
Then fill in the actual build commands, test commands, architecture rules, generated-file rules, and release expectations for that repository.
Coding Agent Playbook ships as separate harness-native editions. This repository is the Codex edition.
| Edition | Repository | Use when |
|---|---|---|
| Codex | ArcanEdge-AI/coding-agent-playbook-codex |
You want global Codex custom instructions, reference docs, skills, and subagent definitions. |
| Claude Code | ArcanEdge-AI/coding-agent-playbook-claude-code |
You want the harness-native edition tuned for Claude Code. |
The editions are maintained independently for their respective harnesses. This repository governs only the Codex edition; use the Claude Code repository for Claude-specific behavior and installation.
AI coding agents are powerful, but they often fail in predictable ways:
- They start coding before understanding the codebase.
- They over-engineer simple requests.
- They refactor unrelated code.
- They trust editor diagnostics over real builds.
- They claim tests passed when they did not run them.
- They delegate poorly or blindly accept subagent output.
- They allow parallel features to develop incompatible contracts or ownership.
- They turn every task into a context dump instead of a focused engineering loop.
This playbook gives Codex a durable operating model:
Understand → Plan → Implement → Verify → Review → Report
The intent is not to make the agent slower for its own sake. The intent is to make it less wrong, especially on real repositories with existing conventions, local changes, and concurrent work.
The Coding Agent Playbook grew out of ArcanEdge's day-to-day use of coding agents on real software engineering work, not synthetic prompting exercises. ArcanEdge uses these patterns while developing production systems, including work supporting United Tradesmen, a live construction workforce and operations platform, as well as unreleased internal products.
Client and unreleased-product repositories remain private. ArcanEdge and United Tradesmen provide the public context; this repository does not publish private source, implementation details, or internal engineering records. The playbook is one part of ArcanEdge's engineering practice, not a claim that AI or this playbook alone built a product.
Real-world use establishes provenance, but private field evidence is not the public reproducibility layer. docs/evidence/ defines a compact benchmark and run-record format so outside developers can inspect prompts, routing, delegation, review, corrections, validation, and outcomes without needing access to private repositories.
Benchmark 001 has one published measured record: Benchmark 001 Run 001. Its fixture baseline is frozen at benchmark-001-baseline-v1 and exact commit; the documented implementation remains in public, open and unmerged Benchmark PR #1. The evidence framework is designed to make results inspectable; it does not claim universal cost, token, speed, or quality advantages.
| Area | Path | Purpose |
|---|---|---|
| Install guide | INSTALL.md |
Agent-readable install contract for one-prompt installation. |
| Installer | install/install.py |
Canonical standard-library Python 3.8+ installer; thin PowerShell and Bash launchers remain available. |
| Global instructions | custom-instructions/ |
Tool-agnostic behavior rules for elegant, maintainable code. |
| Prompts | codex-prompts/ |
Setup and active-project coordination prompts. |
| Skill resources | skills/*/references/ |
Supporting guidance and templates packaged with the workflow that owns them. |
| Skills | skills/ |
Self-contained workflows for task graphs, subagents, worktrees, feature-branch promotion, legacy-path retirement, multi-session coordination, handoffs, session cleanup, doc routing, and senior review. |
| Custom agents | agents/ |
Luna/max Codex subagent definitions for planning, engineering, review, testing, and documentation. |
| Repo guidance | AGENTS.md |
Instructions for maintaining this public playbook repository. |
Use this for normal installs and updates. Full mode is the default and safely replaces the playbook-owned marked section and current managed files.
Full install writes the global instructions into the user's Codex home AGENTS.md, installs self-contained skills and custom subagents, and records their paths and hashes in a managed-file manifest. Later updates can back up and retire unchanged files removed upstream while preserving customized or unrelated files.
Use this only when the user explicitly says the global instructions already live in Codex Personalization → Custom instructions.
Support-only mode avoids duplicating the full instruction file and installs only the self-contained skills, their packaged references, and custom subagents.
The main agent is the senior engineer and orchestrator.
It owns:
- task understanding
- the working plan
- architecture and design judgment
- routing, decomposition, and delegation decisions
- parallel-work coordination
- integration and final acceptance
- final diff
- validation strategy
- final response
The main agent completes coherent work directly by default, including substantial or multi-file work. It delegates only when a bounded helper would provide useful independent evidence, genuinely parallel progress, or worthwhile context reduction. Independent project threads may own separate workstreams, but the main coordinating agent still owns compatibility and integration decisions.
Delegation is optional assistance, not a completion requirement. No direct-execution exception report is needed when no helper is used.
For broad work, the main agent maps bounded work nodes, real blocking dependencies, write ownership or read scope, and verification gates. A graph node is not automatically a helper assignment. When delegation is useful, root sets a finite helper-launch and retry allowance, dispatches only ready work that fits runtime, safety, and ownership capacity, and expands execution cost only for an identified new dependency, invalidated gate, or changed user scope. Real dependencies, verified isolation, and user instructions constrain concurrency; serialize genuine conflicts.
Subagents share the current workspace by default. Worktrees have a separate finite budget that starts at zero; they are created only by the root for a verified isolation need, not per agent. The root may authorize one active auxiliary without additional approval; two or more require user approval for the exact count and reasons. Every task-created auxiliary worktree is integrated and safely removed inside the task or preserved with an exact blocker. No scheduled cleanup task is required for this lifecycle.
This playbook uses five Codex subagent roles that mirror a practical software delivery loop.
| Subagent | Default mode | Best for |
|---|---|---|
planner |
Read-only | Decomposing non-trivial tasks, identifying risks, sequencing work, and defining validation. |
engineer |
Bounded write | Implementing small, well-scoped changes after the plan and constraints are clear. |
reviewer |
Read-only | Reviewing diffs, designs, and implementations for correctness, risk, maintainability, and scope discipline. |
tester |
Read-mostly | Reproducing failures, analyzing test output, finding validation gaps, and recommending targeted checks. |
docs |
Read-only | Finding, interpreting, and summarizing relevant repo docs, reference docs, and authoritative external documentation. |
Every delegated subagent execution uses gpt-5.6-luna with max reasoning. This applies to all roles, retries, and replacements, independently of the main session's model or reasoning effort. It does not require model settings on ordinary tool calls or messages.
Subagents report through team collaboration messaging or a normal final return. They must not alter parent or peer model settings. Any separately authorized task report must omit destination model and reasoning overrides; see skills/subagent-orchestration/references/model-routing.md for the execution/reporting boundary.
The base role names and -luna profile files remain available as compatible names; all ten profiles pin the same Luna/max settings. For child execution, select a compliant profile or pass its model and reasoning effort explicitly. If the host cannot honor both settings, report the limitation rather than silently substituting or inheriting defaults. Consult skills/subagent-orchestration/references/model-routing.md for dispatch and acceptance rules.
The delegation rule is simple:
Precise assignment → Evidence-backed output → Main-agent verification → Accept or reject
A good subagent prompt includes role, goal, context, selected profile or model, reasoning effort, scope, non-goals, permissions, required evidence, escalation conditions, output format, and stop conditions.
For multi-node work, it also identifies the node, its inputs and accepted output, blocking dependencies, ownership or read scope, and verification gate. The orchestration skill explains fan-out, handoff validation, selective retries, and final combined validation.
Root assigns work directly to helpers, and bundled helpers execute their assignment without spawning descendants. Before dispatch, root records the bounded result, acceptance check, expected benefit, exact workspace, and finite launch/retry allowance. Record the actual root model only when provenance requires it, and verify each helper uses gpt-5.6-luna with max reasoning. When capacity is full, continue useful local work or wait; do not queue speculative helpers. Recursive orchestration is outside the default workflow and requires separate explicit authorization and controls.
Use task-graph-orchestration for complex work with substantial fan-out, genuine dependencies, broad scope, layered consolidation, or separate implementation and verification paths. Prompt engineering defines each node; task-graph orchestration defines how the nodes connect, become ready, merge, fail, and require approval. Small or linear work may skip the formal graph.
The graph is an instruction and Markdown artifact. It does not add a graph database, scheduler, runner, dependency, or orchestration framework. Medium tasks can keep the graph in the working plan. Long-running, multi-phase, or multi-session implementation may use .codex/task-graphs/<task-slug>.md when repository policy permits it.
Supporting files:
skills/task-graph-orchestration/SKILL.md
skills/task-graph-orchestration/references/templates/task-graph.md
Run multi-session coordination first when active threads, branches, worktrees, or pull requests may create external ownership or hidden dependency edges. Keep simple or genuinely linear tasks on the normal engineering loop.
The worktree policy prevents swarm fan-out from becoming checkout fan-out:
Current workspace + auxiliary budget 0
↓
Concrete isolation need verified
↓
Root issues one finite worktree permit
↓
Assigned nodes reuse that exact workspace
↓
Root integrates and validates the result
↓
Remove safely, or preserve with an exact blocker
Only the root may create, adopt, repurpose, move, or remove an auxiliary worktree. It may authorize one active auxiliary without additional approval; two or more require approval for the exact count and reasons. Helpers receive an exact workspace assignment and report any additional isolation need upward. Retries reuse compatible worktrees. Overlapping writers normally serialize because separate checkouts do not remove design or merge conflicts.
Before the final response, the root reconciles every task-created auxiliary worktree. It either verifies safe non-force removal inside the task or reports the exact path, owner, branch or HEAD, blocker, and next action. The workflow does not defer task-owned cleanup to scheduled automation and does not treat host-managed or pre-existing user worktrees as disposable.
Supporting files:
skills/worktree-lifecycle/references/worktrees.md
skills/worktree-lifecycle/references/templates/worktree-manifest.md
skills/worktree-lifecycle/SKILL.md
Use feature-branch-lifecycle when a feature, change, or update may use one or more development branches in a repository with established long-lived integration and production branches:
development branches
↓
feature integration branch
↓
integration branch (for example, staging)
↓
production branch (for example, main)
The feature integration branch is the complete review and validation unit. Development branches converge there, one pull request promotes the accepted feature to the integration branch, and production promotion originates only from the integration branch. Temporary branches are deleted only after verified incorporation, required checks, unique-work and dependency checks, worktree reconciliation, exact-target resolution, and authority for local or remote deletion.
The skill detects actual branch names and repository instructions. It does not invent a missing staging branch, replace a repository's selected workflow, or turn branch sequencing into blanket authority for pull requests, merges, remote deletion, or production release.
Supporting files:
skills/feature-branch-lifecycle/SKILL.md
skills/feature-branch-lifecycle/references/branching-rule.md
Use legacy-path-retirement when an authorized change raises a decision about superseded code, duplicate writers, old contracts, or compatibility fallbacks.
Prefer one authoritative implementation within the affected scope. Retain compatibility only for a demonstrated current dependency or explicit retention requirement; migrate or remove confirmed obsolete paths rather than automatically adding more guards around them. Incomplete dependency coverage is an evidence gap, not proof of non-use.
Code retirement, data disposition, and correctness guarantees are separate decisions. Useful development data may need preservation or migration, destructive resets require authority, and pre-production status does not weaken stable identifiers, authorization, validation, persistence integrity, or cleanup safeguards.
The skill is self-contained in:
skills/legacy-path-retirement/SKILL.md
Subagents are delegated from one main thread. Independent Codex threads may already have separate plans, branches, worktrees, assumptions, and implementation ownership.
Use the multi-session coordination workflow when related project work is happening in parallel:
Current project
↓
Threads active within the previous 72 hours
↓
Branches, worktrees, pull requests, and unmerged changes
↓
Shared change map and conflict detection
↓
Ownership, sequencing, and integration verification
Repository state takes precedence over recency. Older work still matters when it remains unmerged, incomplete, blocked, contract-relevant, or otherwise active.
New project threads should use this naming format:
Project - Three-to-Four-Word Description
Examples:
ArcLedger - Validate Billing Evidence
LoreBound - Implement Campaign Imports
The project name should be detected automatically, and the description should be derived from the primary objective. The square brackets used when explaining the format are not part of the actual title.
Start the workflow with:
codex-prompts/coordinate-active-project-work.md
Supporting files:
skills/multi-session-coordination/references/multi-session-coordination.md
skills/multi-session-coordination/references/templates/active-work-record.md
skills/multi-session-coordination/SKILL.md
The optional active-work record gives repositories a local fallback when direct sibling-thread discovery is unavailable. It is advisory and must be verified against current repository evidence.
Large documents are useful only when routed correctly.
The main agent should:
- Identify which docs matter for the task.
- Read only relevant sections when possible.
- Classify docs as authoritative, advisory, or historical.
- Pass only relevant context to subagents or active project threads.
- Resolve conflicts using primary evidence.
Primary evidence includes current code, tests, schemas, configuration, logs, build output, typecheck output, runtime behavior, and authoritative external documentation.
See:
skills/reference-doc-routing/references/engineering-design.md
skills/subagent-orchestration/references/model-routing.md
skills/reference-doc-routing/references/reference-doc-routing.md
skills/subagent-orchestration/references/subagents.md
skills/multi-session-coordination/references/multi-session-coordination.md
skills/worktree-lifecycle/references/worktrees.md
.
├── .gitattributes
├── AGENTS.md
├── CONTRIBUTING.md
├── INSTALL.md
├── LICENSE
├── README.md
├── assets/
│ ├── codex-engineering-team.svg
│ └── coding-agent-playbook-codex-hero.png
├── agents/
│ ├── docs.toml
│ ├── docs-luna.toml
│ ├── engineer.toml
│ ├── engineer-luna.toml
│ ├── planner.toml
│ ├── planner-luna.toml
│ ├── reviewer.toml
│ ├── reviewer-luna.toml
│ ├── tester.toml
│ └── tester-luna.toml
├── codex-prompts/
│ ├── coordinate-active-project-work.md
│ └── setup-global-codex-support-system.md
├── custom-instructions/
│ └── global-coding-agent-instructions.md
├── docs/
│ ├── global-instruction-evaluation.md
│ └── evidence/
│ ├── BENCHMARK-001-RUN-001.md
│ ├── BENCHMARK-001.md
│ ├── METHODOLOGY.md
│ ├── README.md
│ └── RUN-TEMPLATE.md
├── install/
│ ├── install.py
│ ├── install.ps1
│ ├── install.sh
│ └── support-only-pointer.md
└── skills/
├── feature-branch-lifecycle/
│ ├── SKILL.md
│ └── references/branching-rule.md
├── handoff/
│ ├── SKILL.md
│ ├── agents/openai.yaml
│ └── references/context-contract.md
├── legacy-path-retirement/
│ └── SKILL.md
├── multi-session-coordination/
│ ├── SKILL.md
│ └── references/
│ ├── multi-session-coordination.md
│ └── templates/active-work-record.md
├── reference-doc-routing/
│ ├── SKILL.md
│ └── references/
│ ├── README.md
│ ├── engineering-design.md
│ ├── reference-doc-routing.md
│ └── templates/
│ ├── api-contracts.md
│ ├── architecture.md
│ ├── data-model.md
│ ├── design-system.md
│ ├── release.md
│ ├── repository-AGENTS.md
│ ├── security.md
│ └── testing.md
├── session-cleanup/
│ ├── SKILL.md
│ ├── agents/openai.yaml
│ └── references/post-session-cleanup-methodology.md
├── senior-code-review/
│ └── SKILL.md
├── subagent-orchestration/
│ ├── SKILL.md
│ └── references/
│ ├── model-routing.md
│ └── subagents.md
├── task-graph-orchestration/
│ ├── SKILL.md
│ └── references/templates/task-graph.md
└── worktree-lifecycle/
├── agents/
│ └── openai.yaml
├── SKILL.md
└── references/
├── worktrees.md
└── templates/worktree-manifest.md
Bad delegation:
Look into this and fix it.
Better delegation:
Role:
You are the Planner subagent for this task.
Goal:
Identify the smallest safe implementation plan for adding a customer exemption flag to checkout tax calculation.
Scope:
Inspect checkout, cart, customer, and tax calculation code paths only.
Non-goals:
Do not edit files. Do not refactor. Do not propose a new tax engine.
Evidence required:
Return file paths, function names, likely insertion points, relevant tests, and existing exemption concepts.
The main agent still decides the design, applies or rejects recommendations, and verifies the final diff.
1. Ask your coding agent to install this repository URL.
2. Let the installer configure global instructions, self-contained skills with packaged references, and subagents.
3. Add repo-specific AGENTS.md guidance to each project.
4. Let the main agent frame, route, and coordinate each repository task.
5. Complete coherent work directly; when a helper has a concrete benefit, give it a bounded root-to-helper assignment and select `gpt-5.6-luna` with `max` reasoning through a compliant profile or explicit programmatic route. Helpers execute directly and do not spawn descendants.
6. For multi-node work, identify real blocking dependencies, parallel-safe nodes, ownership, and verification gates. If helpers are used, set a finite launch/retry allowance and dispatch only ready assignments that fit runtime, safety, and ownership capacity; get immediate user approval before materially expanding execution cost.
7. Keep the auxiliary-worktree budget at zero unless root verifies a real isolation need. Before completion, remove each task-created auxiliary worktree safely or preserve it with an exact blocker.
8. When a repository uses long-lived integration and production branches, use the feature-branch lifecycle for development-branch convergence, complete-feature validation, promotion, and authorized cleanup.
9. When independent project threads run in parallel, use the multi-session coordination skill.
10. Verify the final combined diff and integrated behavior before accepting completion.
This repository is public so others can star it, fork it, adapt it, and propose improvements.
Please keep contributions generic, reusable, and safe for public use. Do not add private project details, internal URLs, sensitive access material, local machine quirks, or one-off incident logs.
See CONTRIBUTING.md for contribution guidance.
MIT © 2026 ArcanEdge AI. See LICENSE.
This is a living playbook. Treat it as a strong baseline, not a universal law.
The best setup is:
Global behavior + local repository truth + evidence-backed validation