Manage

---
name: manage
description: 'Manage Codex agents, skills, or config entries: create, update, or remove with guardrails.'
---

# 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

```json
{
  "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"
}
```

## Parallel Adoption (Disabled During P4)

This is a consumer declaration, not an enabled execution route. The shipped default remains `serial`; `--execution`, `CODEX_RIG_EXECUTION`, natural-language requests, or `auto` cannot opt this skill into parallel execution during this stage.

### Safe parallel work

The future candidate is 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 candidate.

### Required barrier

Before any future dispatch, freeze the 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 a new plan.

### Serial parent decisions

The 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

Declare only validated resource locks such as `git-index`, `cache:<path>`, `generated:<path>`, and `test-env:<name>`. Shared targets, paths, indexes, caches, generated outputs, test environments, ports, devices, or undeclared resources force serial execution or re-planning.

### Fallback

Unavailable or unsafe fan-out uses equal-gate `serial-fallback` from the same frozen plan with the same quality gates and retained evidence. Never label fallback as parallel or weaken checks because dispatch was unavailable.

### Acceptance

P3b exact-candidate native Linux/Windows evidence, separate user promotion, and this skill's shared runtime matrix must pass before any runtime opt-in. Acceptance must prove freeze, complete join, truthful execution label, resource compatibility, equal gates, and unchanged serial parent authority.

### Stop rule

During P4, generic parallel writes remain disabled. Stop without dispatch on missing promotion, mutable packs, ownership or resource overlap, sensitive or unproven controls, missing terminal evidence, or an incomplete join; no declaration authorizes writes or changes the phase default.

## Workflow

### 01: Create run directory

Run `create_run.py --skill manage` per `../../shared/helper-cli-contract.md`.

### 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 maintainers use `PLUGIN_ROOT/runtime/calibration/` and `PLUGIN_ROOT/shared/native-skill-contract.md`; an installed plugin cache remains immutable.

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

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`:

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

Changes:
- <complete meaningful change description>

Impact:
- <concrete effect>

Verification:
- <exact check and result>

Residual limits:
- <remaining limit or "None known">

---

Co-authored-by: Codex <codex@openai.com>
```

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 the 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 the shared ordered frame. `Outcome` is a completed, rejected, or blocked management action. `Results` has one changed or evaluated surface per row and exactly `Surface | Outcome | Verification | Remaining limit`. Apply the 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`.