plugin

<objective> The {{! plugin_name !}} plugin's resolved version and agent-delivery state reported or reconciled in the scope that carries its skills. </objective>

<verbs>

Read $verb, trim it, and match it against the table. One verb runs per invocation; help is the default when $verb is empty. Text matching no row is an error naming all five verbs.

Verb	Result
help	This plugin's verbs, mutation boundaries, reload requirement, and changelog locations
version	The version resolved by the running session
init	Missing plugin-owned Codex definitions established in the selected agent home
upgrade	Plugin-owned Codex definitions reconciled to this version, including safe stale-file pruning
check	Selected-home drift, collision, and checkout scope-split state reported without mutation

{!% if target == 'claude' %!}init, upgrade, and check report that Claude Code receives this plugin's agents through the plugin manifest and change nothing.{!% else %!}init, upgrade, and check use the bundled reconciliation script. The script never writes into a checkout.{!% endif %!}

</verbs>

<changelogs>

help names where a reader answers "what changed for me, and what must I now do?", reading from disk without network access.

{!% if plugin_name == 'product-tree' %!}This plugin carries two changelogs. Read one only when the reader asks what changed.

Line	Records	Path
Marketplace	events no single plugin owns: harnesses, plugins renamed	${CLAUDE_SKILL_DIR}/../../MARKETPLACE-CHANGELOG.md
Plugin	what changed in this plugin	${CLAUDE_SKILL_DIR}/../../CHANGELOG.md

The marketplace line is current through its topmost ## heading. Report that date with the result.{!% else %!}This plugin carries one changelog:

Line	Records	Path
Plugin	what changed in this plugin	${CLAUDE_SKILL_DIR}/../../CHANGELOG.md

Marketplace-wide events ship in the methodology plugin's marketplace changelog; this plugin carries no copy.{!% endif %!}

</changelogs>

<version_reporting>

version reads exactly one skill-directory-relative manifest:

${CLAUDE_SKILL_DIR}/../../{!% if target == 'claude' %!}.claude-plugin{!% else %!}.codex-plugin{!% endif %!}/plugin.json

Report the version from the plugin copy backing this running session. Never search for another manifest elsewhere on disk.

</version_reporting>

<agent_delivery>

{!% if target == 'claude' %!}The plugin manifest delivers this plugin's agents. Every footprint verb reports that fact and writes nothing. The bundled scripts/place_agents.py serves only the Codex rendering of this skill and is never invoked here.{!% else %!}The plugin ships generated TOML definitions inside this skill. They belong in the selected CODEX_HOME/agents/ directory beside the installed skill content they invoke.

Before every verb, resolve the selected home from CODEX_HOME. When it is absent, require an explicit absolute --home value; never guess another account or fall back to a checkout. Resolve the invocation checkout root and pass it with --checkout so the read-only scope-split preflight can report shadowing plugin copies.

Run the check form first:

python3 "${CLAUDE_SKILL_DIR}/scripts/place_agents.py" --home <selected-codex-home> --checkout <repository-root> --check

check ends there. For init or upgrade, stop on any collision or scope split. Otherwise name every destination the check reported, state that the ownership record changes with them, and run the mutating form only after the harness grants that external write:

python3 "${CLAUDE_SKILL_DIR}/scripts/place_agents.py" --home <selected-codex-home> --checkout <repository-root>

An interrupted init or upgrade leaves no partial definition: each destination and the ownership record are replaced atomically, and re-running init or upgrade recomputes every owned destination from the shipped definitions, adopting a destination that already carries the shipped bytes into the ownership record instead of reporting it as a collision.

Run the check form again afterward. Success requires zero remaining drift, collision, or scope-split report. An interrupted init or upgrade is safe to re-run: every write is atomic per file and the ownership record is recomputed from the shipped definitions on each run. A collision: <path> (changed after preflight) line means the home changed while the run was planning; re-run the check form for a fresh plan instead of retrying the mutating form.{!% endif %!}

</agent_delivery>

<ownership_boundary>

{!% if target == 'claude' %!}This plugin claims no standalone agent file because its manifest delivers the agents.{!% else %!}The shared agent home is reconciled through .outcomeeng-marketplace-ownership.json. This plugin may create, replace, or prune only entries that record {{! plugin_name !}}, or a plugin id the marketplace catalog renames to {{! plugin_name !}}, as owner and whose on-disk digest still matches the record. A changed or linked definition of a renamed id is reported as retained:, stays in place and recorded, and blocks no placement. An unrecorded destination, a modified owned file, malformed ownership data, or a destination owned by another plugin is a collision: report it and change nothing.

A checkout definition byte-identical to a shipped definition is a scope split with directed removal. A changed checkout definition, or one that claims this plugin by filename prefix or by enabling one of its skills, is a scope-split collision requiring inspection. Either state stops home mutation; never refresh the home skills underneath a shadowing checkout definition.{!% endif %!}

</ownership_boundary>

<examples>

{!% if target == 'claude' %!}check, init, and upgrade each print one line: manifest delivery is in effect and nothing was written.{!% else %!}A --check run against a home carrying one stale owned definition, one recorded definition the plugin no longer ships, and one developer file the ownership record does not know prints its plan and exits 2 on any collision or scope split, 1 when writes or prunes are pending, and 0 when the home already matches:

write: /Users/dev/.codex/agents/{{! plugin_name !}}_reviewer.toml
prune: /Users/dev/.codex/agents/{{! plugin_name !}}_verifier.toml
collision: /Users/dev/.codex/agents/{{! plugin_name !}}_notes.toml (unrecorded)

write names a destination whose bytes differ from the shipped definition, prune a recorded {{! plugin_name !}} destination the plugin no longer ships or a recorded destination of an id the catalog renames to it, and collision a present file the ownership record does not authorize, with its cause: symlink, unrecorded, owned by <plugin>, not a regular file, or digest mismatch. A retained line names a recorded definition of a plugin id the catalog renames to {{! plugin_name !}} that was changed or replaced with a link; the run leaves it in place and goes on. Each run that reports a retained line, --check runs included, also prints a partial-migration: line and exits like any other run: the retained definition stays discoverable in the registry until the operator resolves it by hand, so a 0 exit with a partial-migration: line is a completed placement and an unfinished migration. A scope-split directed-removal: or scope-split collision: line names a checkout copy under .codex/agents/ — matched by shipped bytes, by the {{! plugin_name !}} filename prefix, or by a skills.config entry naming a {{! plugin_name !}}: skill — and stops mutation. After the mutating form succeeds, the ownership record carries one entry per written destination:

{ "destination": "agents/{{! plugin_name !}}_reviewer.toml", "plugin": "{{! plugin_name !}}", "digest": "<sha256 of the installed bytes>" }

{!% endif %!}

</examples>

<reload>

Agent registries are loaded at session start. After a successful init or upgrade, reload the harness plugin index or start a new session before judging whether a role is available. Re-running the mutating verb in the same session does not refresh that session's already-loaded registry.

</reload>

<failure_modes>

Claude repaired a missing role by copying its TOML into the checkout.

The checkout copy shadows the selected-home definition while the home plugin can advance independently. Remove a byte-identical generated copy; inspect a changed or unrecognized copy. Reconcile the selected home, then reload the harness.

Claude treated a plugin-looking filename as ownership proof.

Filename prefixes collide with developer-authored files. Only the digest-bound ownership record authorizes replacement or pruning; preserve and report every other file.

Claude reported a version from another plugin copy.

A marketplace source and cache snapshot can diverge. Read only the skill-directory-relative manifest named in <version_reporting>.

</failure_modes>

<success_criteria>

• Exactly one verb runs, defaulting to help.
• version reads only the running skill copy's target manifest.
• help reports the exact changelog lines and paths declared above.
• {!% if target == 'claude' %!}Every footprint verb reports manifest delivery and writes nothing.{!% else %!}check writes nothing and reports every drift, collision, and scope split.
• init and upgrade mutate only the selected home after a clean preflight and external-write approval.
• Every replacement or prune is authorized by matching ownership, this plugin's or that of an id renamed to it, and digest; foreign or modified files remain untouched.
• A final check reports no drift, collision, or scope split, and the report claims a finished migration only when it prints no partial-migration: line.{!% endif %!}
• Missing-role repair ends with a harness plugin-index reload or a new session.

</success_criteria>