A reviewable control layer for smarter, safer, and more efficient OpenAI Codex workflows.
Codex Flightdeck turns one-off prompting habits into a reusable operating system: durable instructions, automatic repository bootstrap, task-aware model routing, scoped tools, validation loops, and practical cost controls.
It is intentionally file-based. You can read every rule before adopting it, copy only the parts you need, and keep project knowledge inside the repository where your team can review it.
Community-maintained and not affiliated with or endorsed by OpenAI.
Coding agents often waste capacity on orientation, missing commands, permission friction, repeated prompts, noisy context, and unnecessary parallelism. Flightdeck addresses those failure modes by making the operating model explicit:
- Give Codex accurate repo context before implementation.
- Store durable conventions in layered
AGENTS.mdfiles. - Bootstrap new or incomplete repositories automatically.
- Route simple, routine, and difficult work to appropriate models and reasoning levels.
- Delegate only bounded, independent work that benefits from a subagent.
- Validate changes with the nearest real signal: tests, builds, logs, screenshots, or health checks.
- Keep global tools narrow and make project-specific integrations local.
flowchart LR
A["Your task"] --> B["Global guidance"]
B --> C{"Repository ready?"}
C -- "No" --> D["Bootstrap project"]
C -- "Yes" --> E["Task routing"]
D --> E
E --> F["Implement or research"]
F --> G["Test and review"]
G --> H["Evidence-backed result"]
| Layer | Included | Purpose |
|---|---|---|
| Personal defaults | GLOBAL_AGENTS.md.template |
Reusable behavior across repositories |
| Repository guidance | REPO_AGENTS.md.template |
Commands, architecture, constraints, and completion criteria |
| Scoped guidance | */AGENTS.md.template |
Folder-specific rules for frontend, backend, tests, ops, and more |
| Project config | .codex/config.toml.template |
Safe, repo-scoped Codex defaults |
| Automatic setup | skills/bootstrap-project/ |
Inspect, prepare, validate, then continue the original task |
| Model strategy | CODEX_COST_AND_SAFETY_POLICY.md |
Match capability and reasoning to task value |
| Task workflows | CODEX_TASK_PROMPT_LIBRARY.md |
Reusable implementation, debugging, research, and review prompts |
| Quality gates | CODEX_PR_REVIEW_GUIDELINES.md |
Review behavior and evidence requirements |
| Integrations | CODEX_MCP_PLAN.md |
Scope MCP servers and write permissions deliberately |
git clone https://github.com/Sparvovic/codex-flightdeck.git
cd codex-flightdeck
python scripts/validate.pymacOS/Linux:
mkdir -p ~/.codex/skills
cp -R skills/bootstrap-project ~/.codex/skills/bootstrap-projectPowerShell:
New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
Copy-Item -Recurse .\skills\bootstrap-project "$HOME\.codex\skills\bootstrap-project"Restart Codex or start a new task so the skill list refreshes.
Review GLOBAL_AGENTS.md.template, then merge the sections you want into ~/.codex/AGENTS.md. Do not blindly replace an existing personal file.
Copy REPO_AGENTS.md.template to AGENTS.md in the repository root and replace placeholder commands with commands you have actually verified.
Optionally copy .codex/config.toml.template to .codex/config.toml in a trusted repository. The template starts with workspace-write and on-request; loosen permissions only when the environment and workflow justify it.
You do not need a separate setup prompt. When the global guidance and bootstrap skill are installed, the first task in an unfamiliar or incomplete repository can trigger readiness checks automatically and then continue the original request.
Model names and supported reasoning levels evolve. Verify current options in the official Codex model documentation before pinning durable configuration.
| Work shape | Starting point | Delegation |
|---|---|---|
| Mechanical, repeatable, high-volume | Luna + low | Usually none |
| Routine implementation, repo exploration, logs | Terra + medium | Optional read-only specialist |
| Ambiguous architecture, security, difficult debugging | Sol + high/xhigh | Only independent, bounded workstreams |
The goal is not minimum tokens at any cost. It is maximum useful work per unit of capacity. Subagents can protect the main context and reduce wall-clock time, but each agent performs its own model and tool work. Use them when parallelism materially improves quality or speed—not as a default ceremony.
Flightdeck ships with conservative shared defaults:
sandbox_mode = "workspace-write"approval_policy = "on-request"- no embedded credentials or provider tokens
- no automatic global config replacement
- no automatic installation of unreviewed third-party tools
- explicit approval boundaries for destructive, production, financial, messaging, and external write actions
High-autonomy profiles such as danger-full-access plus never can be appropriate in trusted or already-isolated environments, but they are an explicit operator choice—not the public default.
CODEX_PROJECT_BOOTSTRAP.md: bootstrap behavior and readiness contract.CODEX_AI_NATIVE_ENGINEERING_WORKFLOW.md: end-to-end engineering loop.CODEX_PROJECT_TYPES.md: guidance by project shape.CODEX_LOCAL_ENVIRONMENT_SETUP.md: local runtime conventions.CODEX_CLOUD_ENVIRONMENT_SETUP.md: cloud task preparation.FRONTEND_EXCELLENCE_FOR_CODEX.md: frontend quality gates.BACKEND_EXCELLENCE_FOR_CODEX.md: backend quality gates.CODEX_REVIEW_PROMPTS.md: focused review prompts.CODEX_SKILL_LIBRARY_PLAN.md: when a workflow should become a skill.CODEX_SOURCE_MAP.md: evidence and source hierarchy.
- Inspect reality first. Repo files, manifests, CI, and runtime behavior beat assumptions.
- Keep durable knowledge close to the code. Global preferences stay global; repo facts stay in the repo.
- Automate proven workflows. A skill should encode a repeated workflow, not a speculative abstraction.
- Prefer evidence over completion language. “Tests passed” is useful; “should work” is not.
- Minimize coordination overhead. Keep delegation shallow and writing ownership clear.
- Make rollback obvious. Templates are copied and reviewed, never silently imposed.
Issues and pull requests are welcome. See CONTRIBUTING.md and SECURITY.md. Changes to Codex facts or configuration keys should cite current official documentation or reproducible client behavior.
MIT. OpenAI, ChatGPT, and Codex are trademarks of their respective owner. This project provides independent workflow guidance and configuration templates.