manage ยท diff
git:20260822.615ca20 to git:20260902.894e657
34 added, 0 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
{
"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`.