ln-013-config-syncer

What this skill does

> **Paths:** File paths (`references/`) are relative to this skill directory.

# Marketplace and Config Aligner

**Type:** L3 Worker
**Category:** 0XX Shared

Installs or verifies this repository's marketplace and selected plugins for Claude Code and Codex CLI without making either agent the source of truth for the other. `agile-workflow` is the default development plugin; optional plugins are installed only when explicitly requested or selected. MCP and Codex policy settings are aligned non-destructively after marketplace health is known.

## MANDATORY READ

**MANDATORY READ:** Load `references/coordinator_summary_contract.md`, `references/environment_worker_runtime_contract.md`, and `references/worker_runtime_contract.md`
**MANDATORY READ:** Load `references/agent_skill_roots_contract.md`

---

## Input / Output

| Direction | Content |
|-----------|---------|
| **Input** | OS info, `disabled` flags per agent, `targets` (`claude` / `codex` / `both` / `all`), `plugins` (`agile-workflow` default, explicit list, or `all`), `dry_run` flag, optional `auto_install_providers` flag, optional `runId`, optional `summaryArtifactPath` |
| **Output** | Structured summary envelope with `payload.status` = `completed` / `skipped` / `error`, plus per-target alignment outcomes in `changes` / `detail` |

If `summaryArtifactPath` is provided, write the same summary JSON there. If not provided, return the summary inline and remain fully standalone. If `runId` is not provided, generate a standalone `run_id` before emitting the summary envelope.

`dry_run=true` is detection-only: do not register marketplaces, install plugins, edit MCP/Codex config, write `.bak` files, or auto-install providers. Return planned actions and drift details in the summary.

## Runtime

Runtime family: `environment-worker-runtime`

Phase profile:
1. `PHASE_0_CONFIG`
2. `PHASE_1_DISCOVER_STATE`
3. `PHASE_2_VERIFY_MARKETPLACE_INSTALLS`
4. `PHASE_3_ALIGN_MCP_SETTINGS`
5. `PHASE_4_ALIGN_CODEX_POLICY`
5a. `PHASE_4A_MCP_PROVIDER_CHECK`
6. `PHASE_5_WRITE_SUMMARY`
7. `PHASE_6_SELF_CHECK`

Runtime rules:
- emit `summary_kind=env-marketplace-align`
- standalone runs generate their own `run_id` and write the default worker-family artifact path
- managed runs require both `runId` and `summaryArtifactPath` and must write the summary to the exact provided path
- always write the validated summary artifact before terminal outcome

## Output Contract

Always build a structured `env-marketplace-align` summary envelope per:
- `references/coordinator_summary_contract.md`
- `references/environment_worker_runtime_contract.md`

Payload fields:
- `targets`
- `plugin_alignment`
- `marketplace_health`
- `mcp_alignment`
- `mcp_providers`
- `codex_execution_defaults`
- `status`

---

## Config Paths by OS

| Agent | Windows | macOS / Linux |
|-------|---------|---------------|
| **Claude** (primary) | `%USERPROFILE%\.claude.json` | `~/.claude.json` |
| **Claude** (fallback) | `%USERPROFILE%\.claude\settings.json` | `~/.claude/settings.json` |
| **Codex** | `%USERPROFILE%\.codex\config.toml` | `~/.codex/config.toml` |

---

## Workflow

```text
Discover State -> Verify Marketplace Installs -> Align MCP -> Align Codex Policy -> Verify & Report
```

### Phase 1: Discover State

1. Read Claude settings:
   - `~/.claude.json` (primary) + `~/.claude/settings.json` (fallback)
   - extract `mcpServers`, enabled marketplaces/plugins, and hook state
2. Read Codex config:
   - `~/.codex/config.toml`
   - extract `[mcp_servers.*]`, `[marketplaces.*]`, top-level `approval_policy`, and top-level `sandbox_mode`
3. Inspect repo marketplace surfaces:
   - Claude: `.claude-plugin/marketplace.json`
   - Codex: `.agents/plugins/marketplace.json`
   - Codex plugin manifests: `plugins/*/.codex-plugin/plugin.json`
4. Resolve plugin selection:
   - always include `agile-workflow`
   - if `plugins=all`, include every plugin listed by the marketplace
   - if an explicit list is provided, install `agile-workflow` plus the requested plugins
   - if interactive and optional plugins are not specified, ask which optional plugins to install
   - if non-interactive and optional plugins are not specified, install or verify only `agile-workflow`
5. Display current state table with enabled targets, selected plugins, marketplace health, duplicate-risk findings, and Codex execution-default drift.

### Phase 2: Verify Marketplace Installs

For each target where `disabled` is not `true`:

| Target | Expected install model | Verification |
|--------|------------------------|--------------|
| Claude | Native Claude marketplace | Marketplace is registered through Claude plugin settings and selected plugins resolve from `.claude-plugin/marketplace.json` |
| Codex | Native Codex marketplace | Marketplace is registered through Codex plugin settings and selected plugins resolve from `.agents/plugins/marketplace.json` / `plugins/*/.codex-plugin/plugin.json` |

Install policy:
- Claude marketplace: `/plugin marketplace add levnikolaevich/claude-code-skills`
- Claude plugin: `/plugin install {plugin}@levnikolaevich-skills-marketplace`
- Codex marketplace: `codex plugin marketplace add levnikolaevich/claude-code-skills`
- Codex plugin selection: verify selected plugins exist in `.agents/plugins/marketplace.json` and `plugins/{plugin}/.codex-plugin/plugin.json`; if the installed Codex version exposes plugin-level selection only through an interactive native flow, report that exact step instead of fabricating a non-existent CLI command

Rules:
- If `dry_run=true`, do not run marketplace add/install commands; report the exact commands that would run.
- Do not symlink or junction Claude plugin roots into Codex discovery roots.
- Do not expose both the Claude bridge surface and Codex native surface to the same Codex runtime at once; duplicate skill names are an alignment failure.
- Do not delete user plugin roots. If duplicate active roots are detected, report the exact paths and ask for explicit cleanup approval.
- Do not install optional plugins silently.
- Run `node tools/marketplace/validate.mjs` when the repo root is available. Report failure as marketplace drift.

### Phase 3: Align MCP Settings

MCP settings are aligned by server name. No target is the universal source of truth.

Merge strategy:
1. Build a union of Claude `mcpServers` and Codex `[mcp_servers.*]`.
2. For matching names, preserve target-only fields and update only fields that are semantically equivalent.
3. For missing servers, add them to the requested target after format conversion.
4. Create `.bak` before modifying any config file.
5. Preserve target-only servers and unrelated config sections.
6. If `dry_run=true`, report the merge plan only; do not create `.bak` files or edit config.

Field mapping:

| Semantic field | Claude JSON | Codex TOML |
|---|---|---|
| command | `command` | `command` |
| args | `args` | `args` |
| env | `env` | `[mcp_servers.{name}.env]` |
| HTTP URL | `type: "http"` + `url` | `url` |
| headers | `headers` | `http_headers` |

Codex-only fields to preserve:
`bearer_token_env_var`, `enabled_tools`, `disabled_tools`, `startup_timeout_sec`, `tool_timeout_sec`, `enabled`, `required`

**Windows implementation note:** Config format conversions with regex or backslash escaping MUST use a temporary `.mjs` script file, not inline `node -e` or bash heredocs.

### Phase 4: Align Hooks and Codex Policy

**Claude hooks:**
- Claude hook/style sync remains Claude-only.
- Do not project Claude hooks into Codex (the wire formats differ).

**Codex hooks:**

- Do not project Claude hooks into Codex (the wire formats differ).
- Do not install product-specific Codex hook shims from this marketplace. Runtime products that need Codex hooks own their own hook scripts, trust model, verification, and service lifecycle.
- Do not write the legacy `[features] codex_hooks = true` alias. Current Codex uses the stable hooks feature and the canonical block is pure `[hooks.*]` TOML.
- When removing stale h