codex-maintenance

Codex Maintenance

Use this skill when maintaining Cascade itself, auditing Codex surface choices, or changing Codex-specific surfaces: AGENTS.md, CODEX.md, .codex/config.toml, .codex/skills/, .codex/agents/, hooks, MCP/tool guidance, plugin guidance, permissions, memory, observability, evals, scope, validator wiring, or docs that define how Codex agents gather context and hand off work.

This skill keeps harness maintenance grounded in current Codex behavior while preserving Cascade's local role contracts, templates, rules, invariants, checklists, and validation gates. It does not patch product/runtime code unless the user explicitly redirects the work through implement-change.

Source Order

1. Latest user request, selected text, active goal, and explicit constraints.
2. Current branch, diff, untracked files, and recent local edits.
3. Complete file tree and reference inventory:
   • rg --files -uu --hidden -g '!/.git/**'
   • git status --short
   • targeted rg -n searches for each skill, agent, path, command, or stale reference being changed.
4. Current Cascade surfaces:
   • AGENTS.md
   • CODEX.md
   • .codex/README.md
   • .codex/config.toml
   • .codex/skills/*/SKILL.md
   • .codex/agents/*.toml
   • .codex/agents/*/AGENT.md
   • .codex/agents/*/skills.yaml
   • docs/structure.md
   • docs/patterns/_index.md
   • docs/patterns/{entry}/index.md
   • docs/patterns/{entry}/*.pack.yaml
   • docs/work/active.md
   • docs/specs/
   • docs/product/
   • docs/design/
   • docs/brand/
   • docs/backlog/_index.md
   • scripts/cascade/validate.ts
5. Official Codex guidance when Codex behavior or file placement matters:
   • best practices;
   • skills;
   • AGENTS.md;
   • project .codex/config.toml;
   • MCP/tool configuration;
   • rules and permission policies;
   • hooks;
   • plugins;
   • subagents and custom agent files.
6. agents-best-practices for provider-neutral harness invariants before adapting them to Codex/Cascade surfaces.
7. Existing templates, checklists, and validator invariants before adding new artifacts.

Surface Decision Rules

• Prompt or current thread: one-off task constraints and temporary context.
• AGENTS.md: durable repo conventions, commands, verification steps, review expectations, and thin pointers only.
• CODEX.md: Cascade route, role references, work packet rules, and write targets.
• .codex/config.toml: trusted project-scoped Codex settings plus Cascade Codex registry values. Do not place user-only provider, credential, notification, profile, or telemetry settings here.
• Skill: reusable workflow with trigger, anti-trigger, source order, outputs, artifacts, templates, checklists, and validation rules. In Cascade, document and maintain skills under .codex/skills/. Treat native Codex repo-skill or plugin layouts as packaging targets, not the primary harness documentation surface.
• Agent role contract: local Cascade role behavior in .codex/agents/{name}/AGENT.md, with skills.yaml for the role skill map.
• Codex custom subagent: every standalone .codex/agents/{name}.toml is loaded by Codex as spawned-session configuration and therefore requires top-level name, description, and developer_instructions. Keep Cascade-only scope, delegation, path, and workflow detail in the companion AGENT.md and skills.yaml, not in unsupported TOML tables.
• Hook: lifecycle enforcement around tool calls, prompts, compaction, subagent starts/stops, or turn-stop events. Use hooks.json or inline [hooks] next to an active config layer; project hooks load only for trusted projects.
• Rule: command approval policy in rules/*.rules next to an active config layer when the need is controlling commands outside the sandbox.
• MCP server or connector: live external data, private workspace context, or authorized tools. Configure MCP servers in config.toml with narrow tool allow/deny lists and per-tool approval modes when needed.
• Plugin: installable distribution bundle for skills plus optional MCP, hooks, app integrations, or marketplace metadata. Plugin packages require .codex-plugin/plugin.json; repo-local marketplace entries live under .agents/plugins/marketplace.json.
• Docs/patterns: reusable project-neutral rules that do not belong to one skill or role. Pattern entries are first-level folders with index.md and at least one *.pack.yaml containing summary, routing, graph-like documents, and selectable sections; use pattern-context for creation, retrieval, and context-pack assembly.
• Validator: mechanical checks for required files, stale paths, registered skills, agent wiring, surface contracts, and packaging invariants.

Codex Audit Rules

For every proposed Codex surface, record:

• objective;
• autonomy level;
• risk level;
• state duration;
• tool surface;
• permission gate;
• validation signal;
• owning file or artifact.

Apply these rules before approving a harness design or file change:

• Separate model responsibility from harness responsibility. The model can propose and explain; schemas, permissions, hooks, tests, and validators enforce.
• Do not rely on prompt text for a rule that must always hold. Put durable enforcement in .codex/config.toml, a hook, a tool contract, or scripts/cascade/validate.ts.
• Keep tool contracts narrow: typed inputs, typed results, explicit error states, permission checks, and source links for live or private data.
• Make each skill trigger-focused. The description should say when to load it, not summarize every rule inside it.
• Keep skills progressively disclosed. Add references, templates, checklists, or scripts only when they prevent a real missed step or make validation deterministic.
• Keep AGENTS.md thin. Route inventories, long architecture notes, product facts, learned rules, and active work to the dedicated docs tree.
• Treat memory as scoped context, not authority. Required team rules belong in tracked files; memory can point to them or summarize recent state.
• Define compaction and rehydration paths when a workflow spans enough context to lose source references. Handoffs must name the source files that matter.
• Require source paths for product-sensitive work. Skills that benefit from product specs must name the relevant docs/specs/, docs/product/, docs/design/, docs/brand/, docs/work/, and backlog sources.
• Use the shared Doc Routing Decision Matrix in docs/patterns/workflow/index.md when a harness change creates, changes, validates, or closes out durable facts across product, design, brand, specs, backlog, glossary, patterns, skills, agents, config, or validator wiring.
• Add planning loops only when objective, budget, checkpoint cadence, and done condition are clear.
• Prefer direct replacement of stale names, paths, and routes unless a live compatibility contract requires a temporary bridge.
• Add observability before autonomy grows: command evidence, validator output, traceable tool calls, failure probes, evals, and launch gates.
• Keep handoffs scoped: changed surfaces, reference inventory, validation evidence, unresolved risks, and next workflow entry. A handoff never replaces the source docs it cites.

Codex Structure Invariants

• Every new skill has SKILL.md frontmatter with name and trigger-focused description.
• Every skill used by an agent appears in that agent's skills.yaml with an existing source path.
• Every Cascade agent has Codex-compatible standalone TOML identity, AGENT.md, skills.yaml, delegation policy, use scope, and avoid scope.
• Skill, agent, config, hook, MCP, plugin, subagent, and docs changes update scripts/cascade/validate.ts when they add a required surface or invariant.
• File-tree and reference inventories are required for changes that can miss skills, agents, templates, docs, specs, work lanes, tools, or validator references.
• Product/spec/design/brand/backlog context must stay separated by source: product facts in docs/product/, design facts in docs/design/, brand facts in docs/brand/, normalized specs in docs/specs/{slice-slug}/, raw sources in docs/specs/source/, execution state in docs/work/, and candidates in docs/backlog/_index.md.
• Shared doc routing decisions live in docs/patterns/workflow/index.md; reusable closeout matrices use .codex/skills/closeout/templates/doc-routing-decision.md.

Codex Documentation Basis

Use current official Codex guidance as the external source of truth for Codex behavior and surface choice:

• Best practices: start with task context, keep durable guidance in AGENTS.md, configure Codex for the workflow, turn repeated work into skills, and validate/review changes.
• Skills: keep each skill focused, make the description trigger-focused for implicit invocation, use SKILL.md as the primary contract, keep optional agents/openai.yaml metadata aligned when present, and add scripts only when deterministic tooling is needed. Cascade documents harness skills under .codex/skills/; if a skill must be mirrored into native Codex repo-skill or plugin packaging, record that as a packaging/migration decision.
• AGENTS.md: keep durable repo guidance concise, practical, and scoped by directory precedence. Codex loads global and project instructions once per run/session, closest files override broader files, and large instruction chains can hit project_doc_max_bytes.
• Config: keep project-scoped Codex settings in trusted project config and personal defaults outside the repo. Project .codex/config.toml cannot own provider credentials, provider routing, profiles, notification commands, or telemetry settings; keep those in user/system config.
• MCP/tools: use connectors or MCP servers for live external data or actions; keep server instructions narrow, configure tools in

Content truncated.