Manage

Manage

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

The installed plugin tree is immutable input. Resolve requested targets against the consuming project or an 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 the 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",
  "done_when": "target and all references are updated or explicitly left unchanged"
}

Workflow

01: Create run directory

Run python PLUGIN_ROOT/shared/create_run.py --skill manage once. Retain its single printed path as <run-directory> and substitute that literal path into every later artifact path and helper argument. Never store or reuse the path through a shell variable; shell variables do not persist across tool calls.

02: Parse intent and target

Intents:

• create: scaffold a new skill/agent/rule/config entry.
• update: edit an 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 an argv command; sort its lines and write them to <run-directory>/inventory.txt. Run rg -n for the 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: exact edited and intentionally untouched files.

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 dedicated lifecycle 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.
• 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 an existing commit. Amend, rebase, reset, squash, fixup, and equivalent history edits require an explicit request for that exact operation.
• Home sync out of scope unless explicitly requested.

05: Apply the smallest reversible edit

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 the active Codex contract and user request require them. Never infer that the source repository is present from the 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 through delegation-lead and shared specialist orchestration. Use the lowest-cost capable canonical role per bounded workstream. Accept delegated change only after the handover gate proves ownership, objective evidence, applicable checks, visible unresolved limits, and parent-owned final acceptance.

07: Run shared quality gates

Inspect 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 clean diff check.

08: Write mandatory result artifact

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

1. Missing intent or target => fail.
2. Delete/rename with unresolved references => fail.
3. Permission/config change without rationale => fail.
4. Behavior change without routing/docs/calibration decision => fail.
5. Result artifact missing => fail.
6. Target resolves inside the installed plugin root => fail without editing.
7. Target is a generated codex-rig-*.toml role link => fail and route to the dedicated lifecycle workflow.
8. Existing history would be rewritten without an explicit request for that exact operation => fail.

Quality Gates

Required:

• review: inventory diff, reference scan, git diff --check.
• 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 the owning project's configuration, tests, documentation, routing, and calibration fixtures. Codex Rig source changes use plugins/codex-rig/runtime/calibration/ and plugins/codex-rig/shared/native-skill-contract.md; an installed plugin cache remains immutable.

For versioned calibration artifact changes, calculate version from last commit, not dirty worktree. If HEAD has 1.3, all next-commit uncommitted edits stay 1.3 or 1.4: one version step only; do not bump to 1.5, 1.6, etc. before a commit.

Commit-output management also keeps the owning project's commit-response contract aligned with required message shape. In AI-Rig, the canonical packaged contract is ../../shared/commit-response-template.md:

<type>(<scope>): <title>

Co-authored-by: Codex <[email protected]>

Output Contract

Use shared gate schema from ../../shared/quality-gates.md.

Minimum artifact payload template: result-template.json.