Maintain Dual-Target Plugin

Maintain Dual-Target Plugin

Keep attached plugins synchronized between Claude Code and Codex after incremental changes.

Source of truth

Source of truth is explicit:

• .plugin-cross-port.marketplace.yaml records the canonical marketplace.
• Each plugin .plugin-cross-port.yaml records plugin-level source_of_truth.
• Mixed repositories are valid: one plugin can be Claude Code-first and another Codex-first.
• Generated-side staged edits are rejected unless explicitly marked manually_maintained.

When to activate

• Commands were added, removed, or edited in commands/
• New skills were added to skills/
• agents/ changed (new agent, description update)
• Hooks changed in plugin.json
• User says "sync Codex", "update dual-target", "re-run cross-port"

Workflow

Step 1 — Read state

1. Read .plugin-cross-port.marketplace.yaml
2. Read <plugin-path>/.plugin-cross-port.yaml
3. Read the authoritative manifest for the plugin source
4. Run marketplace check before switching source

Step 2 — Diff commands

Prefer the deterministic CLI:

python3 plugins/plugin-cross-port/scripts/cross_port.py marketplace sync
python3 plugins/plugin-cross-port/scripts/cross_port.py marketplace check
python3 plugins/plugin-cross-port/scripts/cross_port.py \
  plugin attach plugins/example --source codex
python3 plugins/plugin-cross-port/scripts/cross_port.py \
  plugin switch-source plugins/example --to claude-code

Step 3 — Check manually_maintained

If .plugin-cross-port.yaml lists a generated file as manually_maintained, skip overwriting it. Emit a reminder: "Manually maintained: - review manually."

Step 4 — Strict mode check

If --strict or the user said "strict mode":

• Any unresolved agent or hook that is NOT listed in .plugin-cross-port.yaml under decisions causes a hard stop:

  "Strict mode: new agents/hooks detected — update .plugin-cross-port.yaml decisions before continuing."

Otherwise emit warnings only.

Step 5 — Update .plugin-cross-port.yaml

Update plugin status after sync. The state is JSON-compatible YAML and must remain readable without PyYAML.

Step 6 — Validate Codex manifest

Re-read .codex-plugin/plugin.json. Verify:

• hooks key is absent from Codex manifests
• skills points to ./skills/
• version matches .claude-plugin/plugin.json

If version mismatch, update .codex-plugin/plugin.json version to match.

Step 7 — Summary

Report what changed:

• N commands re-generated
• N commands deleted
• N commands added
• Warnings for agents/hooks

Pre-commit integration

See references/continuous-mode.md for full details.

The hook at .githooks/pre-commit runs automatically:

1. Developer modifies authoritative files and stages the changes
2. Pre-commit hook runs cross_port.py marketplace sync --changed-only ... --stage
3. Generated files and deletions are staged in the same commit automatically
4. Generated-side edits are rejected based on plugin-level state

Generated vs manually maintained

Files in skills/generated-from-commands/ are generated by default.

To mark a file as manually maintained (e.g., after heavy customization):

# .plugin-cross-port.yaml
manually_maintained:
  - skills/generated-from-commands/my-command/SKILL.md

The converter will skip overwriting files listed here.

Semantic adaptation workflow

Use this when hooks, permission behavior, tool IDs, or ecosystem-specific paths cannot be resolved mechanically:

python3 plugins/plugin-cross-port/scripts/cross_port.py plugin adapt plugins/example
python3 plugins/plugin-cross-port/scripts/cross_port.py plugin adapt plugins/example --apply

Review plugins/example/.plugin-cross-port/adaptation-plan.md before applying. If source files change after planning, rerun plugin adapt.

Publication and deletion

Codex failed or review-required targets are published as policy.installation: "NOT_AVAILABLE". Failed Claude Code targets are omitted from the Claude Code marketplace.

When a canonical marketplace entry is removed, sync removes the whole plugins/<name>/ directory only after validating that the path is local, inside plugins_dir, and has a basename matching the plugin name. Use Git for recovery.