Before asking, read User Questions.

Manage¶

Guarded Codex config management for agents, skills, rules, and local config.

The installed plugin tree is immutable input. Resolve requested targets against consuming project or explicit user-approved external scope; never edit this skill's plugin cache, packaged role cards, shared helpers, runtime assets, or package manifests. Codex Rig agent links are managed only by bundled agent-shims workflow, not by this general-purpose skill.

Input Schema¶

{
  "intent": "create|update|delete|rename|add-permission|remove-permission",
  "target": "required agent, skill, rule, config key, or path",
  "change": "required description or spec path",
  "execution": "optional auto|serial|parallel-read|parallel-write; default auto",
  "done_when": "target and all references are updated or explicitly left unchanged"
}

Lightweight Local Work¶

Read and apply Proportional Execution before choosing the direct or detailed path.

Use a parent-only path for a small, understood, reversible local change with bounded impact and existing task authorization. A code fix plus its regression test remains one change. Routing examples are optional; tests and documentation for one change do not create separate domains.

Inspect the affected flow and applicable instructions; define a concise plan with core acceptance and deferred scope. Investigate an unknown cause before editing. Perform a brief parent self-challenge (not independent); accept the challenged plan under existing authority. Assign execution to the parent for indivisible work; management mutations remain parent-serial.
Make the authorized change with the smallest coherent core. Consolidate the actual result and handoffs; reconcile conflicts and integrate before result review. Obtain one bounded independent challenge of the actual result and retain its findings and independence limits. Run the relevant acceptance check and configured lint/format checks; inspect the diff.
Report the outcome, verification, and material limits concisely. Do not create unnecessary standalone execution-plan artifacts, specialist packs, confidence worksheets, five-entry gate bundles, or final-handoff/result artifacts solely for this path. Reuse still-valid checks for unchanged source and environment.

This path takes precedence over the detailed workflow and role examples below. Select the detailed workflow for medium/large or unexpectedly nontrivial work under Proportional Execution, an explicitly requested structured report/review, or work requiring independent specialist coverage. Actual runtime permissions, protected-state decisions, and project-required checks still apply. Missing parallel controls select parent-serial work; they do not require another permission request for already-authorized local edits.

Execution Route Selection¶

Before preparing or dispatching any child, resolve invocation --execution=<mode> → CODEX_RIG_EXECUTION → auto and apply the loaded Proportional Execution selector. Honor serial; parallel-read chooses only the strict portable section; reject unsupported parallel-write. Absent, explicit, or environment auto chooses suitable observed native bounded work or parent-serial work, never the portable route. Native support is read-only; all management mutations remain parent-serial.

Record the choice and reason in the existing plan or concise outcome. Use portable helpers and digest receipts only after selecting parallel-read; native work does not inherit their helper-level auto resolver.

Parallel Adoption (Portable read-only)¶

Only when Execution Route Selection resolves to parallel-read, read portable-parallel-read.md before any child preparation; serial, auto, and native routes do not load it. The reference preserves the shared route gate, write-policy and approval rules, host-compatibility barrier, preflight and runtime-validation qualifiers, resource-lock declaration, fallback, acceptance, and stop rule; the consumer values below stay authoritative for this skill.

This portable section permits only its promoted portable read-only route. Native disjoint read-only support may follow Proportional Execution; protected-target, approval, and propagation rules stay unchanged.

Follow the canonical G0–G8 execution flow for shared gate order and fork outcomes. This consumer's read-only inventory passes are bounded by G0–G5; parent owns deterministic G6 integration, G7 verification, and G8 verdict/promotion.

Safe parallel work¶

The promoted route permits read-only inventory, reference, ownership, and policy-impact scans over immutable disjoint targets with separate outputs. Disjoint propagation is not enabled; config, policy, documentation, calibration, cache, generated-output, artifact, and result writes remain outside this portable route.

Required barrier¶

Before any dispatch, freeze intent, target, baseline, ownership map, exact references, calibration and routing impact, context packs, role-card hashes, checks, resource locks, and plan digest. Dispatch at most one fixed dependency-ready wave, then join every terminal scan before edits, propagation, gates, or acceptance; changed scope requires new plan.

The frozen <run-directory>/execution-plan.json must include exact consumer_policy values consumer_id=manage, capability=portable-read-only, promotion_status=promoted, parent_mutations=serial, and canonical_gates=serial.

The plan must also freeze schema-3 dispatch_choices for each node as specified in portable-parallel-read.md; omitted spawn settings are represented by null and inherit observed parent controls.

Bootstrap exception: run-directory creation (Step 01), the inventory.txt/references.txt/ownership.md writes from Step 03, and the write-approval.json write itself are exempt from requiring a prior approved plan digest — these precursor writes must exist before a plan digest can be computed or approved.

Before dispatch, run PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/parallel_execution.py preflight --consumer manage --plan <run-directory>/execution-plan.json --approval <run-directory>/write-approval.json; pass --execution=parallel-read for the selected portable route, including an environment-selected value.

After every spawned child reaches a terminal handoff, run PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/parallel_execution.py validate-runtime --consumer manage --manifest <run-directory>/execution-manifest.json --plan <run-directory>/execution-plan.json --parent-rollout <authoritative-parent-rollout> --sessions-dir <authoritative-sessions-directory> --run-dir <run-directory> --roles-dir PLUGIN_ROOT/roles. Require runtime_promotion_eligible=true, consumer_id=manage, and write_parallel_eligible=false.

Serial parent decisions¶

Parent owns all create, update, delete, rename, and permission mutations; same-file policy or config changes; shared AGENTS.md, README, and config edits; calibration version advancement; propagation; artifacts and result writes; canonical quality gates; verdict; and promotion. Installed plugin-root and generated codex-rig-*.toml safety decisions remain serial and unchanged.

Resource conflicts¶

Shared targets, paths, indexes, caches, generated outputs, test environments, ports, devices, or undeclared resources force serial execution or re-planning.

Stop rule¶

Generic parallel writes remain disabled.

Workflow¶

01: Create run directory¶

Run create_run.py --skill manage per ../../shared/helper-cli-contract.md. Apply Execution Route Selection before any child preparation. Native or parent-serial work follows its selected route; only selected parallel-read work enters Parallel Adoption and its helper/receipt lifecycle.

02: Parse intent and target¶

Intents:

create: scaffold new skill/agent/rule/config entry.
update: edit existing target.
rename: move target and update references.
delete: remove target only after dependency scan.
add-permission / remove-permission: modify permission policy with rationale.

Unknown intent => fail before edit.

03: Resolve owned files and blast radius¶

Run rg --files with the AGENTS.md, .codex/**, and .agents/** globs as argv command; sort its lines and write them to <run-directory>/inventory.txt. Run rg -n for exact target over .codex, .agents, and AGENTS.md, write results to <run-directory>/references.txt, and record unavailable inputs or command failure explicitly.

Write <run-directory>/ownership.md with the validator-required Intent, Owned Files, Verification, and Residual Limits sections: Owned Files lists exact edited and intentionally untouched files; complete Verification and Residual Limits after Step 07.

Resolve the current skill path and reject any target whose canonical path is inside the same installed plugin root. Reject generated codex-rig-*.toml targets here even when they are outside the cache; report the bundled agent-shims workflow as the only permitted owner.

04: Run safety gates before editing¶

Deletion safety required for delete and rename.

Delete/rename: no unresolved references or explicit migration plan.
Permission changes: reason, use case, risk note; security-auditor is available for advisory review of the permission change only when the user explicitly requests that pass, under the same explicit-request gating as other specialist routing in ../../shared/specialist-orchestration.md — not mandatory for every permission change.
Public behavior change: consider docs/routing/calibration.
Versioned calibration fixtures are committed-history markers: compare current value to git show HEAD:<path>; while uncommitted, advance at most one step from last committed value.
A new-commit request never authorizes rewriting existing commit. Amend, rebase, reset, squash, fixup, and equivalent history edits require explicit request for that exact operation.
Home sync out of scope unless explicitly requested.

05: Apply the smallest reversible edit¶

The parent applies this edit itself; it stays provisional until Step 07 gates pass and the parent accepts it.

Use Codex's native scope: .agents/skills/ for repository skills, AGENTS.md for repository guidance, and .codex/config.toml for project runtime settings. Use custom agent-config paths only when active Codex contract and user request require them. Never infer that source repository is present from installed cache layout.

06: Propagate references¶

For behavior changes, update relevant descriptions, mappings, routing text, calibration notes in same patch. List intentionally stale references in <run-directory>/unresolved-references.md.

For broad changes with separable config, docs, calibration, or verification workstreams, route read-only scans, proposals, and evidence through delegation-lead and shared specialist orchestration. Use lowest-cost capable canonical role per bounded workstream. Delegated roles never mutate files: accept a delegated proposal only after handover gate proves ownership, objective evidence, applicable checks, and visible unresolved limits; the parent then applies every mutation serially and owns final acceptance.

07: Run shared quality gates¶

Inspect PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/run_gates.py --help. Supply real affected-surface commands and explicit reasons for every inapplicable gate; never use true as skip reason. Review includes git diff --check -- <Owned Files paths>, limited to files listed in ownership.md so unrelated caller edits never decide the result.

08: Write mandatory result artifact¶

Completion commit: run the Local Git approval grant check. grant … → commit the verified, owned changes with the shared commit template unless the user asked for no commit, leave unstaged or to wait; no grant → an explicit commit request commits after checks, otherwise ask that section's one question (Approve / Approve always / Deny) before committing, and Deny leaves the changes unstaged. Record the check result, any answer and the commit disposition in the handoff.

Manage artifacts include ownership.md; follow ../../shared/helper-cli-contract.md. Write with MANAGE_METADATA, validate as manage, promote only validated candidate.

Fail-Fast Rules¶

Missing intent or target => fail.
Delete/rename with unresolved references => fail.
Permission/config change without rationale => fail.
Behavior change without routing/docs/calibration decision => fail.
Detailed workflow: result artifact missing => fail.
Target resolves inside installed plugin root => fail without editing.
Target is generated codex-rig-*.toml role link => fail and route to the bundled agent-shims workflow.
Existing history would be rewritten without explicit request for that exact operation => fail.

Quality Gates¶

Required:

review: inventory diff, reference scan, git diff --check on ownership.md owned paths.
artifact: ownership.md, gate logs, result JSON pass shared validator.

Conditional:

lint/format: when generated Python, TOML, shell, or Markdown formatters available.
tests: calibration or smoke checks for changed skills/agents when behavior changes.

Calibration Hooks¶

Behavior-changing management edits update or explicitly review owning project's configuration, tests, documentation, routing, and calibration fixtures. Codex Rig maintainers use PLUGIN_ROOT/runtime/calibration/ and PLUGIN_ROOT/shared/native-skill-contract.md; installed plugin cache remains immutable.

Calibration must reject premature portable read-only runtime opt-in, generic write authorization, mutable or unjoined scan packs, delegated management mutations, and quality-gate parallelism without executable resource-isolation evidence.

Versioned calibration artifact changes follow the Step 04 one-step rule against HEAD.

Commit-output management also keeps owning project's commit-response contract aligned with required message shape. Canonical packaged contract: Required Commit Message Shape.

Keep Verification: change-specific and compact: include only final checks that materially validate the committed surfaces, consolidate related gates, and omit exploratory probes, failure-first reproductions, repeated reruns, setup diagnostics, and unrelated broad checks. The canonical contract is authoritative for the full exclusion and not-run rules.

Output Contract¶

Before writing result candidate, follow ../../shared/final-handoff-contract.md: render and bind final-handoff.json, final.md, and final-handoff.validation.json; after both validators and promotion pass, emit final.md verbatim.

Use ../../shared/quality-gates.md.

Final chat¶

Final chat follows shared ordered frame. Outcome is completed, rejected, or blocked management action. Results has one changed or evaluated surface per row and exactly Surface | Outcome | Verification | Remaining limit. Apply shared Verification, Remaining, Next steps, Confidence, and supplemental Artifact rules; include ownership/policy checks and every required human action with owner.

Minimum artifact payload template: result-template.json.