git:20260821.df8081d to git:20260821.359c243

2 added, 16 removed. Audit A to A.

---

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

{

"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

- Per `../../shared/helper-cli-contract.md`, run `python PLUGIN_ROOT/shared/create_run.py --skill manage` once; stdout is literal `<run-directory>`; never store it in a shell variable.

+ 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.

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

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>

```

## Output Contract

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

### Final chat

- Final chat follows this order:

- 1. `Outcome`: completed, rejected, or blocked management action.

- 2. `Results`: one row per changed or evaluated surface in a Markdown table with exactly `Surface | Outcome | Verification | Remaining limit`.

- 3. `Verification`: ownership, policy, and executable checks with results.

- 4. `Remaining`: unresolved limits, required human action, and owner.

- 5. `Next steps`: prioritized human or follow-up action with owner; reference result rows without repeating them, or `None`.

- 6. `Confidence`: score, evidence basis, and material limits.

- 7. `Artifact`: validated path only. It is supplemental, never a substitute for the outcome.

+ 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`.