compatibility-audit

---
name: compatibility-audit
description: This skill should be used when the user asks to "audit ycc compatibility",
  "check Cursor/Codex bundle health", "verify cross-target parity", "run a compatibility
  report for ycc", "is ycc ready to release", "are the generated bundles up to date",
  "check if the bundles are in sync", "validate generated targets", "are Cursor and
  Codex bundles current", "check bundle drift", "report on target feature gaps", or
  when the user wants a structured per-target health report covering drift detection,
  install-assumption validation, and feature-capability gaps across the Claude, Cursor,
  Codex, and opencode targets without bumping versions or committing anything.
---

# compatibility-audit

This skill audits the health of every generated compatibility target for the
`ycc` plugin — Claude, Cursor, Codex, and opencode — and produces a structured,
per-target triage report. It detects bundle drift between the `ycc/` source
tree and the generated bundles, validates install assumptions (path conventions,
shebang lines, executable bits), and surfaces feature-capability gaps using the
shared capability matrix. It never bumps versions, never commits, and never
modifies any file.

## When to use

- You want to know whether the Cursor or Codex bundles are in sync with the
  `ycc/` source tree.
- You are preparing a release and need a pre-flight compatibility snapshot
  before running `$bundle-release`.
- A CI job reported a bundle validation failure and you need a structured
  breakdown.
- You suspect a newly added skill or agent was not propagated to all targets.
- You want to confirm that install-path assumptions (e.g. the plugin-root
  variable references) are consistent across all generated artifacts.
- You want to identify which features are unavailable on a specific target due
  to platform capability limits.

## Arguments

Parse `$ARGUMENTS` for:

- **--target** (optional, default `all`) — restrict the audit to a single
  target. Accepted values: `claude`, `cursor`, `codex`, `opencode`, `all`. When `all` is
  specified, phases 2–5 run once per target in the set `{claude, cursor, codex, opencode}`.
- **--json** (flag, default off) — emit the final triage report as a
  machine-readable JSON envelope instead of Markdown. Per-target sections are
  preserved inside the envelope as structured objects.
- **--fail-fast** (flag, default off) — stop after the first target that
  reports any error or drift. Do not proceed to remaining targets. Surface the
  failure immediately.
- **--dry-run** (flag, default off) — print the full audit plan (which scripts
  will be invoked, in what order, against which targets) and then STOP without
  running anything.

## Phases

### Phase 0: Load capability matrix

Read
`~/.codex/plugins/ycc/shared/references/target-capability-matrix.md`.

This document defines which features (skills, agents, slash commands, hooks)
are available on each target. Load it into context before any per-target work
begins. If the file is missing, surface a clear error and STOP — the matrix is
required for Phase 5.

### Phase 1: Parse arguments and resolve target set

Parse `$ARGUMENTS` as described above. Resolve `--target` to a concrete list:

- `all` → `[claude, cursor, codex, opencode]`
- any single value → a one-element list

If `--dry-run` was passed, print the resolved target list, the scripts that
would be invoked for each target (Phases 2–5), and the output format
(`--json` or Markdown). Then STOP without invoking anything.

### Phase 2: Bundle drift detection (per target)

For each target `<t>` in the resolved list, invoke:

```
~/.codex/plugins/ycc/shared/scripts/report-bundle-drift.sh --target=<t> --format=json
```

Capture the JSON output. A non-zero exit means drift was detected or the
script itself failed. On failure, surface the full stderr. If `--fail-fast` is
active, STOP after the first non-zero exit.

### Phase 3: Validate generated bundle (per target)

For each target `<t>`, invoke:

```
./scripts/validate.sh --only <t>
```

Capture stdout and stderr. A non-zero exit means validation failed for that
target. Surface the full output. If `--fail-fast` is active, STOP after the
first non-zero exit.

### Phase 4: Audit install assumptions (per target)

For each target `<t>`, invoke:

```
~/.codex/plugins/ycc/skills/compatibility-audit/scripts/audit-install-assumptions.sh --target=<t> --format=json
```

This script checks path conventions, shebang lines, executable permissions, and
plugin-root variable reference consistency for all artifacts belonging to
`<t>`. Capture JSON output. On non-zero exit, surface stderr. If `--fail-fast`
is active, STOP after the first failure.

### Phase 5: Audit target feature gaps (global)

Run once, not per-target:

```
~/.codex/plugins/ycc/skills/compatibility-audit/scripts/audit-target-features.sh
```

This script cross-references the capability matrix loaded in Phase 0 against
the actual contents of each generated bundle to identify features that exist in
the source tree but are absent or degraded on one or more targets. Capture JSON
output. On non-zero exit, surface stderr and continue to Phase 6 with partial
data — do not STOP, because feature-gap data is informational, not a hard
failure.

### Phase 6: Synthesize triage report

Combine the outputs from Phases 2–5 into a structured per-target report.

**Markdown output (default):**

Produce one section per target. Within each section, list drift findings,
validation results, install-assumption issues, and feature gaps as separate
subsections. Conclude with a per-target verdict: `PASS`, `WARN`, or `FAIL`.
Do not emit a single aggregate verdict — see the Anti-parity stance section.

**JSON output (`--json`):**

Wrap the per-target objects in a top-level envelope:

```json
{
  "schema": "compatibility-audit/v1",
  "targets": {
    "claude":  { "drift": {...}, "validation": {...}, "install": {...}, "features": {...}, "verdict": "PASS|WARN|FAIL" },
    "cursor":  { "drift": {...}, "validation": {...}, "install": {...}, "features": {...}, "verdict": "PASS|WARN|FAIL" },
    "codex":   { "drift": {...}, "validation": {...}, "install": {...}, "features": {...}, "verdict": "PASS|WARN|FAIL" },
    "opencode":{ "drift": {...}, "validation": {...}, "install": {...}, "features": {...}, "verdict": "PASS|WARN|FAIL" }
  },
  "audited_at": "<ISO-8601 timestamp>"
}
```

Omit targets that were excluded via `--target`.

## Output format

A typical Markdown report looks like this:

```
## compatibility-audit report

### claude

- Drift: none detected
- Validation: passed
- Install assumptions: all checks passed
- Feature gaps: none

Verdict: PASS

---

### cursor

- Drift: 2 skills missing from .cursor-plugin/ (bundle-author, compatibility-audit)
- Validation: FAILED — .cursor-plugin/rules/ycc.mdc missing section [skills]
- Install assumptions: 1 script missing executable bit (audit-install-assumptions.sh)
- Feature gaps: slash commands not supported on Cursor (expected, per capability matrix)

Verdict: FAIL

---

### codex

- Drift: none detected
- Validation: passed
- Install assumptions: all checks passed
- Feature gaps: hooks not supported on Codex (expected, per capability matrix)

Verdict: WARN
```

Note: `WARN` indicates expected capability gaps documented in the capability
matrix, not actionable failures. `FAIL` indicates drift, validation errors, or
install issues that must be resolved before release.

## Anti-parity stance

Each target operates under a different runtime contract. Cursor does not support
slash commands; Codex does not support hooks. These are expected, documented
gaps — not failures. This skill reports results in per-target sections and
assigns a per-target verdict. It does NOT produce a single aggregate pass/fail
across all targets, because collapsing cross-target results into one verdict
obscures which target needs attention and why.

For guidance on reading per-target verdicts and distinguishing expected gaps
from actionable failures, see
`~/.codex/plugins/ycc/skills/compatibility-audit/references/reading-the-report.md`.

## Notes

- This skill does not bump versions, does not commit, and does not modify any
  file. It is a read-only diagnostic tool.
- To act on the findings — bump versions, regenerate bundles, tag a release —
  use `$bundle-release`.
- The capability matrix at
  `~/.codex/plugins/ycc/shared/references/target-capability-matrix.md`
  is the authoritative source for what is and is not expected on each target.
  If a gap appears in the report but is documented in the matrix, it is a `WARN`
  not a `FAIL`.