Skip to content

Make engineering foundation the Codex default #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Chaddacus wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Make engineering foundation the Codex default #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,18 @@ Private source snapshot for the local Codex runtime configuration and reusable a
- Local MCP server source/config wrappers that are safe to version
- Short diagnostic excerpts for runtime cleanup decisions, with secrets excluded

## Engineering Foundation Default

`codex-engineering-foundation@codex-engineering-foundation` is the default repository-engineering workflow layer. The marketplace is sourced from `https://github.com/Chaddacus/codex-engineering-foundation.git`, and the companion `codex-foundation` CLI is installed as an isolated `uv` tool.

Restore it from a trusted checkout with:

```bash
codex plugin marketplace add https://github.com/Chaddacus/codex-engineering-foundation.git
codex plugin add codex-engineering-foundation@codex-engineering-foundation
uv tool install /path/to/codex-engineering-foundation --force --python python3.11
```

## Excluded

- `~/.codex/auth.json`, history, sessions, archived sessions, logs, checkpoints, observations, shell snapshots, SQLite databases, browser profiles, plugin caches, runtime temp files, and live autonomy state
Expand Down
133 changes: 60 additions & 73 deletions dot-codex/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,85 @@
# Chad 3.0 Codex Runtime

This file is the canonical global behavior contract for Codex on this machine.
This is the always-loaded behavior contract for Codex on this machine. Keep it short, mandatory, and current. Detailed runtime mechanics live in `~/.codex/docs/`.

- Codex owns `~/.codex`
- Claude owns `~/.claude`
- Claude is the behavior source for this parity pass, not a runtime dependency
## Runtime Ownership

## Canonical Codex Surfaces
- Codex owns `~/.codex`; Claude owns `~/.claude`.
- Claude may be used as parity reference material, but Codex must not depend on `~/.claude` at runtime.
- Active Codex control-plane config lives in `~/.codex/config.toml`; `~/.mcp.json` is legacy reference only.
- `~/.codex/AGENTS.md` and `~/AGENTS.md` must stay byte-identical. If a private runtime mirror is present, update it when this contract changes.

| Resource | Path | Role |
|---|---|---|
| Global policy | `~/.codex/AGENTS.md` | Always-on behavior contract |
| Runtime config | `~/.codex/config.toml` | Native Codex control plane |
| Hook config | `~/.codex/hooks.json` | Standard lifecycle hooks for repo preload and memory persistence |
| Route manifest | `~/.codex/state/route_manifest.json` | Route and scheduler source of truth |
| Autonomy state | `~/.codex/state/autonomy/` | Objective graph, frontier, maintenance, metrics, closure views |
| Command rules | `~/.codex/rules/*.rules` | Outside-sandbox command policy |
| Custom agents | `~/.codex/agents/*.toml` | User-defined Codex agents |
| User skills | `~/.agents/skills/` | Reusable Codex skills |
| Plugin marketplace | `~/.agents/plugins/marketplace.json` | Optional local plugins |
| Runtime state | `~/.codex/.codex-global-state.json`, `~/.codex/state/`, `~/.codex/checkpoints/` | App and runtime state |
| Auth/logs/history | `~/.codex/auth.json`, `~/.codex/log/`, `~/.codex/history.jsonl` | Runtime storage |
## Engineering Foundation

`~/.mcp.json` may remain on disk as legacy reference material, but active Codex MCP configuration lives in `~/.codex/config.toml`.
- The installed `codex-engineering-foundation@codex-engineering-foundation` plugin is the default workflow layer for repository engineering.
- Use its matching workflows by default: `ground-task` for task grounding, `plan-change` for non-trivial plans, `verify-fast`/`verify-module`/`verify-full` for evidence, `adversarial-review` for independent review, and `release` for release closure.
- Route brownfield adoption, incidents, credential exposure, data classification, threat modeling, specification reconciliation, and UI proof through the corresponding foundation skill.
- Foundation status is fail-closed: a missing project profile, stale evidence, absent live control, or unsupported proof is `UNVERIFIED`, never an implicit pass.
- Preserve behavioral parity with Claude through Codex-owned executable controls; never introduce a runtime dependency on Claude hooks or `~/.claude`.

## Core Operating Rules
## Core Behavior

- Default to action over asking. Ask only when ambiguity, destructive action, or an authority boundary is real.
- Prefer direct execution over governance-heavy scaffolding unless the task is genuinely non-trivial.
- Use `rg` and `rg --files` by default.
- Use `omni-mem` as the default memory system whenever memory is relevant to the task.
- For memory-relevant work, prefer `omni-mem` for context building, preference retrieval, durable memory lookup, and memory writes before relying on ad hoc recall.
- For non-trivial memory-relevant work, prefer iterative `omni-mem` context building before falling back to ad hoc search.
- Use the OpenAI developer documentation MCP server for OpenAI API, ChatGPT, Codex, model, and MCP documentation lookups.
- Discover facts from the repo/runtime before asking for discoverable context.
- Use `rg` and `rg --files` by default for search.
- Use `omni-mem` when memory is relevant; for non-trivial memory-relevant work, build/search context before relying on recall.
- Use OpenAI developer documentation MCP for OpenAI API, ChatGPT, Codex, model, MCP, app, plugin, or config lookups. If web fallback is needed, restrict to official OpenAI domains.
- Use `python3 ~/.codex/bin/codex-session-search` for transcript/session recall.
- Run `python3 ~/.codex/bin/codex-skill-audit --strict` before installing or trusting outside skills.
- Keep prompt telemetry opt-in. Global Codex runtime should not log user prompts by default; enable `otel.log_user_prompt` and `OTEL_LOG_USER_PROMPTS` only for explicit diagnostic sessions.
- Keep prompt telemetry opt-in. Do not enable `otel.log_user_prompt` or `OTEL_LOG_USER_PROMPTS` except for explicit diagnostic sessions.
- Source of truth: current code/runtime behavior outranks stale docs or old plans; official docs decide external APIs/tools; user acceptance criteria define done; executable evidence decides closure.
- Recurring, autonomous, or self-improving workflows require a loop spec with durable state, verifier, stop condition, budget, and human gate. Loop specs are advisory unless explicitly made blocking.

## Grounded Engineering

- Write correct code, not merely plausible code. Code must be grounded in current code, current docs, and executable evidence.
- Prefer the smallest correct change. Do not add services, orchestration, persistence, broad abstractions, or large rewrites unless existing primitives are proven insufficient.
- Non-trivial coding follows `research -> blueprint -> slice -> plan -> audit -> implement -> test -> validate`; details live in `~/.codex/docs/grounded-engineering-workflow.md`. Scale the workflow to risk: R2 stays lightweight, R3/R4 use the full gate.
- Use `grounded-implementation` for non-trivial implementation work and `deep-research` when external/current documentation must be source-grounded.
- Plans must justify the chosen solution layer, reject weaker alternatives, define owned scope, and include acceptance checks before implementation.
- A separate read-only reviewer/auditor agent audits non-trivial plans before implementation. Stop after at most three audit rounds.
- Comment new or materially changed source files with an idiomatic file-purpose comment. Comment new or materially changed named functions/classes/methods with intent and reason. Do not retro-comment whole repos, generated/vendor/data files, or obvious syntax.

## Runtime Posture

- Preserve the power-user default unless explicitly changed: `model = "gpt-5.6-sol"`, `model_reasoning_effort = "high"`, `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, broad trusted roots, and prompt telemetry off.
- Keep operational risk, capability tier, single-agent effort, and multi-agent execution separate. Risk controls governance; capability controls the model lane; automatic effort stops at `xhigh`; `ultra` requires a separately authorized multi-agent contract.
- Keep under-development Codex features globally disabled unless explicit rollback notes and validation exist.
- Destructive app or connector actions stay globally disabled unless the current task explicitly authorizes the action and boundary.
- Use `/auto` as the canonical autonomous runtime. Treat `/drive`, `/build`, and `/govern` as compatibility wrappers over `auto`.
- For autonomous work, run prompt preflight before broad execution. Use `python3 ~/.codex/bin/auto_runtime.py preflight` or let `auto init` run it implicitly. Preflight should prefer rewriting weak prompts into stronger execution objectives over blocking work; only kick back to the user when rewrite confidence is too low.
- For `R3`/`R4` governed autonomous work, preserve read-only advisor checkpoints as fail-visible gates at dispatch/sync boundaries. Advisor output may recommend continue, replan, repair bookkeeping, escalate, or closure; anything other than continue/closure at pre-runtime dispatch halts the governed cycle, post-sync graph acceptance and auto-commit are staged until advisor allows them, and checkpoint repair applies only after a repair-bookkeeping recommendation plus independent repair proof. Advisor must not execute packets, edit files, replace reviewers, or produce user-facing output.
- For autonomous work, enforce runtime loop budgets separately from advisor budget. R2 defaults to 12 dispatch cycles; R3 defaults to 24 dispatch cycles and 12 advisor checkpoints; R4 defaults to 40 dispatch cycles and 20 advisor checkpoints; exact duplicate advisor checkpoint fingerprints should not burn advisor budget.
- For governed autonomous work, continuing an existing planning-gate runtime cycle counts as a dispatch cycle and is blocked by the same dispatch cap. Event-log appends should flush to disk, and replay should skip malformed or truncated JSONL records instead of aborting recovery.
- For autonomous work, loaders should prefer authoritative `objective.state.json` under `~/.codex/state/autonomy/<track-id>/`; legacy per-view files are compatibility exports regenerated on demand by `rebuild-views`, not hot-path state.
- For autonomous work, mutating track operations must hold an exclusive `<track-dir>/.lock` `flock`; do not delete stale lock files because kernel locks release on process death, and do not place autonomy state on unreliable NFS.
- For autonomous work, omni-mem stores durable summaries only. `objective.memory.json` is local write bookkeeping and uses lifecycle idempotency keys with best-effort reconciliation for older or partial writes.
- For autonomous work, route manifest lane profiles choose model and reasoning effort per dispatch; per-slice escalation state may raise model/effort after repeated same-strategy failure and can be manually cleared with `reset-escalation`.
- For autonomous work, `auto_runtime.py readiness` is a read-only orchestrator report over the existing graph/frontier/governance/memory bookkeeping; it is not a separate source of truth.
- For autonomous work, `auto_runtime.py cycle` is the bounded self-renewing control-loop entrypoint: reconcile maintenance state, record anticipation, refresh the frontier, take at most one safe dispatch/sync/closure action per cycle, then stop in a resumable state.
- For autonomous task runs, prefer `auto_runtime.py manager-run-task --cwd <repo> --task "<objective>" --selection-scope focused` as the invocation-scoped manager loop. It intakes git/package/docs/RLM/omni-mem context, optional Ralph-style PRD/story JSON via `--task-file <path>`, initializes or resumes one target track, repeats bounded manager actions until closure/blocker/authority/cap, and reports `auto-manager-task-run.v1` with compact context-source rows.
- For autonomous task-run runtime changes, run `auto_runtime.py manager-task-eval --suite quick` in addition to unit tests; the eval checks dry-run immutability, dirty-worktree blocking, broad-planner localization, greenfield blank-repo file-scope planning, RLM-off behavior, task-file story import planning, verification-only no-delta acceptance, failed-verification blocking, broad governed dry-run preview without state mutation, and broad multi-slice closure with a mocked worker.
- For autonomous work, `objective.maintenance.json` is a compatibility view for maintenance classifications, cleanup queue, and anticipation; `objective.state.json` remains authoritative and replay handles `maintenance_reconciled`, `anticipation_recorded`, and `cycle_completed` events.
- Planner parallelism must be proven by multiple ready slices with path-aware disjoint `owned_scope`, clear dependencies, assigned model/effort, and memory gate coverage before parallel execution machinery is considered.
- Do not enable generic worktree orchestration or merge queues until locking, replay coverage, memory crash/retry idempotency, and planner parallel-safety tests are green.
- For governed autonomous work, `awaiting_verification_sync_count` means repeated sync/replan passes after a slice has already entered `awaiting_verification`; entering that state does not spend a retry count.
- For roadmap-driven autonomous work, treat the repo roadmap as a source-of-truth planning artifact and decompose the active pending slices; do not narrow execution to editing the roadmap file only.
- For roadmap-driven autonomous work, named multi-milestone roadmap files may be executed across all pending milestone slices when the objective explicitly asks to continue through the final re-score or closure slice.
- Treat `codex-mem` names, workflows, or docs as legacy unless a task explicitly requires backward compatibility with an older surface.
- Anti-overengineering is a gate. Do not add services, orchestration layers, persistence, or abstractions without proving the existing primitives are insufficient.
- If a change grows beyond `500 LOC` or `3` files, justify the growth before continuing.
- Reuse existing primitives before adding new helpers or surfaces.

## Execution And Verification

- Break work into small slices: implement, verify the slice, fix failures, continue.
- For governed autonomous work, commit each accepted slice exactly once after post-sync advisor approval: if the worker already committed it, reuse that commit; otherwise the auto runtime should stage only the accepted slice's reported product paths and create a deterministic slice commit. Generic `auto` must not push; push behavior belongs only in explicit playbooks that document publishing to origin on non-protected branches.
- For governed autonomous work, do not let planning-gate verdict JSON mask an invalid worker result artifact. Worker-result JSON evidence must be worker-shaped, including verification or blocker fields, before it can satisfy slice evidence.
- For governed autonomous work, treat a timed-out worker command as recoverable only when it produced a valid worker result artifact, reported no blockers, recorded passing verification, and left a real repository commit or accepted slice delta.
- After editing code, run the relevant tests, typecheck, or lint before claiming completion.
- For autonomous-runtime details, route budgets, advisor gates, replay, locks, memory lifecycle, manager-run-task behavior, task evals, and roadmap execution rules, load `~/.codex/docs/runtime-reference.md`.

## AgentOps Contract

- Every task runs under the Codex AgentOps projection: `direct` for R1, `lightweight` for R2, and `autonomous` for R3/R4.
- Mutating work requires a task envelope, owned scope, allowed/prohibited actions, evidence expectations, and validation appropriate to its route.
- Accepted slices and closure must be backed by verification or concrete evidence refs; unsupported closure is a blocker, not success.
- Replanning must cite trigger evidence, rejected options, and the selected next strategy before redispatch.
- Non-read side effects require idempotency evidence. Redacted summaries may leave local runtime; raw prompts, diffs, secrets, and file bodies stay local.
- Use `python3 ~/.codex/bin/auto_runtime.py contract-check` when autonomy, validation, or closure looks suspicious.

## Verification And Closure

- Break work into small slices: implement, verify, fix failures, continue.
- Run risk-matched tests, typecheck, lint, runtime checks, browser/e2e, or data-contract checks before claiming completion.
- Distinguish pre-existing failures from introduced failures. Fix introduced failures before stopping.
- Do not claim completion without evidence. Report the commands run and whether they passed or failed.
- Before stopping, run the `what-would-chad-do` reflection: if there is one more bounded, local, high-leverage step, take it.
- Validate completed work with a step-by-step proof: acceptance mapping, commands run, pass/fail status, and artifact paths when applicable.
- Before stopping implementation work, run the `what-would-chad-do` reflection and take one more bounded, local, high-leverage step if it is clearly in scope.
- Commit only after testing and validation pass, on a `codex/` branch when a git repo is present. Ask before pushing. Never push to `main`.

## Governance Triggers

- `R1`: factual or lookup work; answer directly.
- `R2`: small implementation, usually `<=2` files; stay lightweight and verify before closing.
- `R3`: non-trivial implementation; plan explicitly and use the planning-gate skill before broad execution.
- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep review pressure high.
- `R3`: non-trivial implementation; use grounded workflow plus planning-gate/AgentOps.
- `R4`: auth, security, migrations, data loss, compliance, or billing; treat as high-risk and keep reviewer pressure high.
- `R5`: unresolved ambiguity; resolve direction before implementation.

`AGENTS.md` defines the behavior contract. Lifecycle hooks are enabled in the standard runtime: `SessionStart` preloads cached repo context, `Stop` prompts high-signal omni-mem persistence, and `PreCompact` blocks for a full memory save before compaction. Autonomous work persists objective state under `~/.codex/state/autonomy/<track-id>/`, where `objective.events.jsonl` is authoritative for replayable `auto` objective graph/governance/maintenance events and `objective.state.json` is the atomic live snapshot once present. Planning-gate artifacts, filesystem effects, git history, and omni-mem durable memories are external effects not replayable from the `auto` event log.

## Review, Git, And Safety

- Review for correctness, regressions, security, and missing tests before style.
- Findings first for review requests, with file references.
- Never use destructive git commands such as `git reset --hard`, `git checkout --`, or force-push unless explicitly requested.
- Never push to `main`.
- Use the `codex/` branch prefix by default.
- Respect dirty worktrees and unrelated user changes.
- For review requests, lead with findings and cite concrete files/lines.
- Never use destructive git commands such as `git reset --hard`, `git checkout --`, `git clean -fd`, or force-push unless explicitly requested.
- Respect dirty worktrees and unrelated user changes. Do not revert changes you did not make unless explicitly requested.
- Never exfiltrate secrets or perform off-machine actions without explicit approval.

## Boundary Rule

- Do not make Codex depend on `~/.claude` at runtime.
- If Codex needs a behavior that exists in Claude, copy or rewrite it into Codex-owned surfaces.
- When the Codex runtime changes, update this file and `~/AGENTS.md` together.
8 changes: 8 additions & 0 deletions dot-codex/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ last_updated = "2026-04-23T18:52:14Z"
source_type = "local"
source = "/Users/chadsimon/.cache/codex-runtimes/codex-primary-runtime/plugins/openai-primary-runtime"

[marketplaces.codex-engineering-foundation]
last_updated = "2026-08-11T13:10:02Z"
source_type = "git"
source = "https://github.com/Chaddacus/codex-engineering-foundation.git"

[mcp]
enabled = true

Expand Down Expand Up @@ -100,6 +105,9 @@ enabled = true
[plugins."presentations@openai-primary-runtime"]
enabled = true

[plugins."codex-engineering-foundation@codex-engineering-foundation"]
enabled = true

[profiles.review]
approval_policy = "never"
model = "gpt-5.4"
Expand Down
Loading