integration

Adapter over `codemap-py integrate` — audit, plan, source-wire, locally sync, and demonstrate the codemap-py integration with its supported consumers. Trigger with `/codemap-py:integration audit|plan|

SKILL.md

GitHub
<objective>

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

</objective> <inputs>
  • $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.
</inputs> <workflow>

Step 1: Resolve mode

Parse $ARGUMENTS case-insensitively: empty or starts audit → audit; plan → plan; apply → apply; sync → sync; demo → demo. Otherwise ask AskUserQuestion: "Unrecognized command $ARGUMENTS. Which of the five modes did you mean?" Options: (a) audit, (b) plan, (c) apply, (d) sync, (e) demo. Wait for reply.

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.

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate audit [--runtime <r>] [--json] [--since YYYY-MM-DD]  # timeout: 15000

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 [--runtime <r>] [--consumers <csv>] [--source <s>] [--out <artifact>]  # timeout: 15000

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

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate apply --plan <artifact> --approve <sha256>  # timeout: 30000

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: <consumers>; operations: <count>\nPlan SHA-256: <sha256>\n→ <artifact>", 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.

"${CLAUDE_PLUGIN_ROOT:-plugins/codemap-py}/bin/codemap-py" integrate sync --source <s> --plan <artifact> --approve <sha256> [--runtime <r>]  # timeout: 60000

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 [--runtime <r>]  # timeout: 20000

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: 0 success; 1 runtime/filesystem failure or partial-sync journal (see table); 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.

</workflow>