Skip to content

SKILL

Runtime adapter over codemap-py integrate engine (src/codemap_py/integration/__init__.py). Targets Claude Code, Codex, or both. Never invokes another runtime's model; uses only its native plugin-manager CLI.

Five exact pinned CLI modes; retired check removed:

Mode Args Mutation Exit
audit [--runtime {claude,codex,both}] [--json] [--since YYYY-MM-DD] none 0 pass/warn; 1 fail; 2 bad syntax
plan [--runtime ...] [--consumers <csv>] [--source {local-candidate,release}] [--out <artifact>] report artifact only 0; 2 bad syntax
apply --plan <artifact> --approve <sha256> verified source checkout only 0; 1 drift/fs; 2 bad approve/syntax
sync --source {local-candidate,release} --plan <artifact> --approve <sha256> [--runtime ...] local runtime plugin state 0; 1 partial-fail/journal; 2 bad approve
demo [--runtime ...] disposable evidence only 0; 1 fail

--approve requires explicit mutation mode (apply/sync), saved plan artifact, and its user-shown SHA-256. It never authorizes new targets, remote publication, Git history/remote mutation, marketplace or user instruction-file edits, or data deletion.

Closed integration/reinstall set: Claude consumers foundry, oss, develop, research (provider codemap-py); Codex consumer codex-rig (provider codemap-py). Explicit mapping, not discovery/extension registry; cross-check both marketplace and plugin manifests before mutation. --runtime codex: only codex-rig; --runtime claude: four Claude consumers; --runtime both or omitted: all five.

Shared-engine safety invariants:

  • plan records schema/protocol version, op ID, exact targets, before-state hashes, desired versions/refs/hashes, exact argv, ordered ops, rollback identities, expected post-state, and plan SHA-256.
  • Every mutation revalidates target + before-state immediately before action; drift invalidates approval.
  • Source writes use before-images + atomic per-file replace; apply refuses foreign/modified markers, path escapes, symlinks, installed-cache roots, dirty working-tree overlap, and unverified product identity.
  • sync refuses plans whose source is absent from selected candidate, installed bytes mismatch selected hash, or release/rollback evidence names mutable/default-branch source. No implicit "latest".
  • First-target success + second-target failure stops immediately. Rollback performs only approved-plan actions. Claim completion/rollback only after post-state hash verification.
  • "Push" means only (1) updating allowlisted version-controlled consumer source integration from codemap-py.integration.v2, and (2) installing/reinstalling those built plugin versions locally via native runtime CLI. Never git push, remote marketplace mutation, release publication, or direct installed-cache edits.

Active consumer guidance is separate from provider metadata. For Codex, codex-rig's shipped shared/codemap-contract.md (requires codex-rig plugin) is the active consumer contract: its adapter validates CODEMAP_BIN first or PATH fallback once, runs provider-owned probe/query surface, persists one context artifact, lets specialists reuse it. Provider-managed codemap-py-integration.md block is metadata-only; identity/protocol/timestamp fields don't wire a launcher or prove active guidance. Audit checks provider identity and reachable active consumer guidance separately, reports missing/unreachable/outdated guidance as bounded source maintenance (or remediation_kind: plan_sync, when the existing approved target map permits it). Never borrow another plugin's shared script or edit installed caches. Installed-byte/hash evidence is separate from current-session activation; native listing without session provenance is not proof, and matching source hashes alone don't prove semantic currency.

NOT for: structural queries (use /codemap-py:query-code); standalone index rebuilds (use /codemap-py:scan-codebase).

  • $ARGUMENTS: optional:
  • Omitted or audit — zero-write inspection of provider, consumer, managed-block, index, runtime-log, and usage evidence.
  • plan — persist report artifact (targets, argv, hashes, rollback identities, plan SHA-256); no mutation.
  • apply — atomically update current-version managed blocks in allowlisted consumer source from approved plan.
  • sync — install/reinstall approved targets locally via native plugin-manager CLIs.
  • demo — run audit plus one representative structural smoke query; disposable evidence only.

Step 1: Resolve mode

First, if the request is a structural query (callers, callees, imports, symbol lookup) or a standalone index rebuild, print one line naming the owning skill (/codemap-py:query-code or /codemap-py:scan-codebase) and stop — never answer, investigate, or run the query here; demo's own smoke query is the only structural query this skill runs. Otherwise parse $ARGUMENTS case-insensitively: empty or starts audit → audit; plan → plan; apply → apply; sync → sync; demo → demo. Otherwise print ! Unknown mode '<first token>'. Modes: audit, plan, apply, sync, demo — re-invoke with one of them. and stop. Never AskUserQuestion here: five modes exceed the four-option cap.

Step 2: Run the mode

Launcher pinned to $CLAUDE_PLUGIN_ROOT — provider binary identity is the audited subject here, and the Codex counterpart has no PATH entry; a bare-name PATH shadow would audit the wrong binary.

Each block below runs as written. Optional flags are appended only when the user asked for them; a value the block needs arrives through a variable whose unsubstituted <placeholder> aborts the block.

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate audit  # timeout: 15000

Optional: --runtime <r>, --json, --since YYYY-MM-DD.

audit — bounded read-only inspection: provider/consumer versions, observed provider content identity, managed blocks, active consumer guidance reachability/content, index identity, runtime-scoped logs, usage, findings. Reports pass, warn, or fail; never invokes plan, apply, sync, index, query self-heal, native plugin-manager mutation, or global-instruction installation. Missing/unreachable/outdated active guidance reports as consumer_query_guidance_missing, consumer_query_guidance_unreachable, or consumer_query_guidance_drift, treated as source maintenance, not proof of active wiring. Same-version content mismatch = high-severity drift; native listing without session provenance = session_catalog: unobservable. Codex supplies runtime-scoped CLI/tool shards but no skill-start hook; host hooks expose no token usage. Report these evidence limits; never claim live fresh-session activation or token savings. --json emits schema 2 (codemap-py.integration.v2); --since filters telemetry by date. Default text; JSON for downstream reasoning.

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate plan  # timeout: 15000

Optional: --runtime <r>, --consumers <csv>, --source <s>, --out <artifact>.

plan — writes report artifact only. Relay CLI stdout artifact path, op count, and plan SHA-256 verbatim; never paraphrase hash.

# timeout: 30000
PLAN="<plan artifact path>"
PLAN_SHA="<approved plan SHA-256>"
case "$PLAN" in *'<'*'>'*|"") echo "! BLOCKED — substitute PLAN with the plan artifact path"; exit 1 ;; esac
case "$PLAN_SHA" in *'<'*'>'*|"") echo "! BLOCKED — substitute PLAN_SHA with the SHA-256 the user approved"; exit 1 ;; esac
"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate apply --plan "$PLAN" --approve "$PLAN_SHA"

apply — requires --plan + --approve <sha256> matching shown plan. Before execution, Read the saved plan artifact and print its full operation list and summary + SHA-256 once as the last reply text before calling AskUserQuestion; never in an option preview. The question text carries a plain summary (separate fields with actual newlines): "Apply this plan?\nTargets: ; operations: \nPlan SHA-256: \n→ ", at most 6 plain lines (target 600 characters, hard cap 1,500), no table, pipe layout, or code fence. Preserve the exact hash and name the plan artifact path. Options carry labels and one-line descriptions, no previews: (a) Approve — run apply with exact SHA-256, (b) Cancel — leave the plan unapplied; preserve order and keep the recommended option second. Never construct/pass --approve without explicit confirmation. Maintainer/source-checkout operation; immutable-release users normally use audit, sync, demo. apply never runs reported native reinstall commands; sync never rewrites consumer source.

# timeout: 60000
SOURCE="<local-candidate or release>"
PLAN="<plan artifact path>"
PLAN_SHA="<approved plan SHA-256>"
case "$SOURCE" in local-candidate|release) ;; *) echo "! BLOCKED — SOURCE must be local-candidate or release"; exit 1 ;; esac
case "$PLAN" in *'<'*'>'*|"") echo "! BLOCKED — substitute PLAN with the plan artifact path"; exit 1 ;; esac
case "$PLAN_SHA" in *'<'*'>'*|"") echo "! BLOCKED — substitute PLAN_SHA with the SHA-256 the user approved"; exit 1 ;; esac
"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate sync --source "$SOURCE" --plan "$PLAN" --approve "$PLAN_SHA"

Optional: --runtime <r>.

sync — same gate as apply: Read the saved plan artifact, print its full operation list and summary + SHA-256 once as the last reply text before AskUserQuestion, and carry targets, operation count, exact SHA-256, and plan artifact path in question text before passing --approve. At most 6 plain lines (target 600 characters, hard cap 1,500), no table, pipe layout, or code fence; options carry labels and one-line descriptions, no previews, in the same order as apply, with the recommended option second. Also requires --source {local-candidate,release}. After successful Claude-consumer or codemap-py install/reinstall, say: "Run /reload-plugins (or start a fresh session) before relying on the updated plugin — this session's tool list was resolved before the update." If --runtime included codex and synced codex-rig/codemap-py, add: "Start a new Codex session before relying on the updated plugin there too."

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate demo  # timeout: 20000

Optional: --runtime <r>.

demo — runs audit + one representative structural smoke query; records protocol/version/evidence. Disposable unless user separately approves mutation. Never claims a plain-vs-structural comparison, token savings, or current-session activation. Print returned report path.

Step 3: Report

Report exit meaning per mode (see table): 0 success (audit: pass or warn); 1 for audit/demo = a fail verdict — report the findings, not a crash; 1 for apply = drift or filesystem failure, for sync = partial failure or journal state; 2 bad syntax or approval. For apply or sync exit 1, report journal state (planned → approved → applying:<t> → verified:<t> → complete, or rollback-started → rollback-succeeded|rollback-failed → recovery-required). For recovery-required, relay only engine-reported bounded manual recovery commands; invent none.