Update Target Capabilities

---
name: update-target-capabilities
description: Use when an AI tool gains support for a feature agentsmesh does not yet expose — or exposes wrongly — and you must raise or correct an existing target's capability for project and/or global scope (rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions). Also use to audit every target for capability gaps, or to act on an audit/feature-request someone else wrote. Start by verifying the claim against the tool's OWN primary docs — such findings are frequently fabricated, stale, or wrong-scoped, so be ready to reject. Covers verification-first research, descriptor wiring, round-trip symmetry, global-only scopeExtras emission, settings-merge and plugin safety, format/path-change blast radius, strict TDD, two-stage review, and matrix/docs sync. Start with `pnpm capabilities:audit`; research only STALE/MISSING cells; the ledger memoizes verified formats so audits stay fast.
---

## Purpose

# Update Target Capabilities

Use this skill when an existing target already lives in `src/targets/<target>/` and the underlying tool has started supporting a canonical feature that agentsmesh declares as `none` (or under-declares as `partial`/`embedded`) — **or** declares as `native` but doesn't actually work (wrong path, wrong key, wrong shape, generate-only with no importer, or a file the tool never reads). The job is to raise or correct that capability — for the right scope(s), with the generate **and** import sides symmetric — and to prove it.

> **The meta-rule: verify the claim before you build it.** Most invocations of this skill act on a *claim* — an audit row, a feature-request, a changelog rumor, or a comment in our own code. In real use, a large fraction of those claims are wrong: the surface is fabricated (no such file exists), already-correct (the claim is stale), wrong-scoped (claimed "both scopes" but the tool only reads it globally), or GUI-only (no writable file → `partial`, not `native`). Treat every claim as a hypothesis and confirm it against the tool's **own** primary docs/source before writing a line. Rejecting a bad finding is a successful outcome — ship a guess and you ship a broken capability the matrix now advertises as real.

This is the skill `add-agent-target` defers to under "changing capability levels for an existing target." Use `add-agent-target` only for a brand-new target id; use `add-global-mode-target` only for first-time global wiring of a target that predates global support.

Read `./references/capability-update-checklist.md` before editing code. It holds the decision matrices, the format/path-change blast-radius list, and the full touchpoint/test/review list.

## When To Use

- A tool shipped a new feature surface (a config file, a settings key, a hooks format) that agentsmesh does not yet generate or import.
- You are auditing all targets for gaps ("which features do tools now support that we declare `none`?"), or working through an audit/feature-request someone else produced (verify each row — see the meta-rule).
- A capability is declared `partial`/`embedded` but the tool now has a dedicated file surface agentsmesh could own natively.
- A capability is declared `native` but is **broken**: wrong path/key/shape, a file the tool never reads, or generate-only with no importer. Fixing it so the tool actually loads it (or so it round-trips) is in scope and counts as a real capability gain even though the matrix level doesn't move.

## Do Not Use This Skill For

- Adding a brand-new target id — use `add-agent-target`.
- First-time global-mode architecture for a target — use `add-global-mode-target`.
- Pure refactors that do not change any capability level or fix any broken surface.
- Downgrades/removals (`native → none/partial`) — those are breaking changes that need a product decision, not this skill's expansion-first flow.

## Non-Negotiable Rules

### MUST

- **Verify the claim against the tool's own primary docs/source first — and reject what doesn't hold up.** A claim is real only when you can point at the tool's docs/source that say it reads this file/key in this shape at this scope. Reject (and write down why) when you find: a **fabricated** surface (no such file/key exists — e.g. a permissions path the tool never reads); an **already-correct** state (the claim is stale; the current code is right); a **wrong scope** (claimed "both" but the tool only reads it globally, or vice versa); or a **GUI/cloud-only** surface (no writable file → `partial`, not `native`). Do not trust the audit row, *our own code comments*, the README, or memory — they are exactly what produced the wrong claims. A rejection with evidence is a complete, valuable result.
- **Research the real, current format from primary sources** (only after the claim survives verification): the exact file path, the exact JSON/YAML/Markdown shape, and the exact top-level key (`mcpServers` vs `servers` vs `extensions` vs `context_servers` all differ). Separate the target product from the assistant runtime (a generated `codex-cli` target ≠ Codex desktop), and note when a project moved orgs/paths (e.g. Goose → AAIF).
- **Global-only settings-backed features emit via `globalSupport.scopeExtras`, not a plain `generateX`.** The permissions/settings feature loop invokes generators *without* a scope, and `resolveTargetFeatureGenerator` does not gate by level — so a plain `generatePermissions`/`generateX` for a feature that's `native` global but `none` project will **leak the file into project scope**. Emit it from `scopeExtras` (which receives the scope) and gate on `scope === 'global'`; the descriptor schema accepts `scopeExtras` as the implementation of a settings-backed global capability. (MCP/hooks generators *do* receive a `ctx` and can scope-gate via `ctx?.scope`.)
- **When two or more targets share a file format, extract one shared helper instead of duplicating per-target logic** (e.g. the wrapped command-hook serialize/import shared by codex-cli, factory-droid, and goose). Existing targets' tests then prove the extraction is behavior-preserving. Duplicated per-target format logic is the anti-pattern the architecture guide calls out.
- **Decide the level per scope, independently.** Project and global capabilities are separate fields and frequently differ (e.g. Goose MCP is global-only; Rovo Dev hooks/permissions are global-only). Use the level matrix in the checklist: `native` (dedicated file/key), `embedded` (folded into another file), `partial` (tool supports it but only via UI/managed settings agentsmesh cannot write), `none`.
- **Round-trip symmetry is the first-class requirement.** A `native` generate side MUST have a matching import side, or the capability is broken — this is the trap that slips through most often. After wiring a generator, wire the importer (descriptor `importer` block or custom `importFrom`) and assert canonical output in a test. The support matrix says "Native"; users read that as both directions.
- **`partial` requires a no-op generator stub plus a lint warning.** The descriptor schema requires a `generateX` returning `[]` even when the level is `partial`; add a `lint.<feature>` warning (reuse `createWarning`) pointing the user at the tool's UI/settings.
- **Settings-file merge discipline.** If a target emits *multiple* writes to one settings file in a pass (separate per-feature generators, or an array from one emitter), its `mergeGeneratedOutputContent` MUST use `pending?.content ?? existing` as the merge base, never just `existing` — otherwise earlier keys (e.g. `mcpServers`) are silently clobbered. If the target emits a *single combined* write (one `emitScopedSettings` output carrying every key), `_pending` is correctly unused — do not "fix" it.
- **Plugin safety.** The engine resolves every hook via `getBuiltinTargetDefinition(id) ?? getDescriptor(id)` — builtins and plugin descriptors share the path. If you change a descriptor hook *contract* (new field, new hook), update `tests/fixtures/plugins/rich-plugin` and add a registered-plugin-descriptor test, not only builtin coverage. If you merely *use* an existing hook, no fixture change is needed.
- **No target-name hardcoding in shared/core.** Extend shared infrastructure with data-driven, optional, default-preserving fields (e.g. `mcpServersKey?` on the mcpJson import mode), never `if (target === 'x')` branches.
- **Write failing tests first** for every new behavior: generator/emitter edge cases (`null`, empty, valid, each of allow/deny/ask), strict contract path arrays, and global-layout capability assertions.
- **Keep every file ≤ 200 lines.** Capability wiring grows `index.ts`; split into `capabilities.ts`, `importer-spec.ts`, `layout.ts`, `merge.ts`, `settings.ts` as the existing targets do. Check `wc -l` after wiring.
- **Reference rewriting.** If you add a new generated directory that contains cross-references (e.g. a commands dir), register it in `src/core/reference/import-maps/<target>.ts` both directions, and confirm the prose-vs-link classifier still holds.
- **Keep target data single-source.** Capabilities live only in the descriptor; the matrix builds dynamically. Run the matrix regen and sync README + `website/src/content/docs/reference/supported-tools.mdx` (the single per-target support page).
- **Run the lessons ritual.** Recall before each file edit / state-changing command; capture immediately after any failure or correction.
- **Run `post-feature-qa`** before claiming done.

### MUST NOT

- Do not implement a claim you could not confirm from the tool's own primary source — reject it with a one-line reason instead.
- Do not declare `native` and ship generate-only — that is a broken round-trip, not a feature.
- Do not infer the format from old fixtures, the README, our own code comments, or memory.
- Do not add a generator for a feature the tool only manages in its GUI — that is `partial`, with a lint warning.
- Do not use a plain `generateX` for a global-only feature — it leaks into project scope (use `scopeExtras`).
- Do not let `index.ts` cross 200 lines "temporarily."
- Do not update README without the website page, or vice versa.
- Do not hand-edit `package.json` version or the matrix tables; they are generated.

## Workflow (audit-driven)

Run `superpowers:subagent-driven-development` when touching more than one (target, feature).

1. **Audit (deterministic, ~0 tokens):** `pnpm capabilities:audit --json`. It joins descriptors × the capability ledger (`src/targets/catalog/capability-ledger.json`) and returns four buckets:
   - **GAPS** — `descriptor < maxAchievable`: raise-opportunities. Do NOT leave these on the table (coverage bias: overstatement beats understatement).
   - **STALE** — provenance is null (seeded but unverified) or older than the window, or the descriptor over-declares vs the ledger: re-verify.
   - **MISSING** — a native/embedded cell with no ledger provenance: research and add an entry.
   - **BROKEN** — surfaced by `pnpm test` (the conformance test): a native/embedded cell whose generated output fails its ledger fingerprint (wrong path / extension / top-level key / shape).
2. **Research ONLY STALE + MISSING** against the tool's OWN primary docs (the §0 verification rules below still apply — reject fabricated / GUI-only / wrong-scope claims). Update the ledger cell's `path`, `ext`, `format`, `fingerprint`, `source` (primary-doc URL), `verifiedAt` (today), `maxAchievable`, and `verdict: "confirmed"`. Never re-research a cell whose provenance is fresh. Directory/projection features (commands, agents, skills) and extensionless ignore files are intentionally unseeded — research those by hand and add cells (or leave `none`).
3. **Fix BROKEN** — correct the generator/importer until `pnpm test` conformance passes for that cell.
4. **Flip GAPS** — for each, follow `./references/capability-update-checklist.md` in full (TDD generator + importer, round-trip symmetry, blast-radius). The format is already in the ledger — do not re-research it. A flip to `native` still requires proven generate **and** import; the matrix never advertises an unproven native.
5. **Guard:** `pnpm capabilities:verify` (every native/embedded cell has provenance) + `pnpm matrix:verify` + the full stack.

The ledger is an oracle, not a source of truth: current levels always come from the descriptor (the matrix derives from there); the ledger records where the tool's docs say the file/shape is, so we validate — never generate — against it. Re-run `pnpm capabilities:seed` after adding or changing a native/embedded feature to refresh fingerprint skeletons.

## Fast Execution Playbook

Optimise for zero wasted tokens. Treat each phase as a gate: only enter the next if the previous signals real work.

**Phase 0 — Deterministic triage (~0 tokens).**
Run `pnpm capabilities:audit --json` then the full verification stack (`pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm matrix:verify`, `pnpm capabilities:verify`), capturing the **real exit codes** — never pipe any of those commands through `tail`/`grep`; a non-zero exit masked by the pipeline is the single most common source of false-green audits. If the audit returns 0 gaps, 0 stale, 0 missing, 0 broken **and** all verification passes, **stop** — there is nothing to do.

**Phase 1 — One pipelined pass per target.**
Work only the targets that appear in the gaps/stale/missing/broken buckets or in the current diff. For each such target, execute research → primary-doc verification → ledger update → descriptor fix as **one uninterrupted unit of work**. Do not split into separate "research wave" then "fix wave" — that forces redundant diff re-reads and doubles context. Assignment rules:
- Shared cross-cutting test suites (layout-metadata, agents-folder-structure-research, skill-mirror, reference-rewrite matrix, e2e content contracts) each get **exactly one owner target** designated up front; other targets import from or assert against that owner's output rather than duplicating coverage.
- Verify majors (level raises) once with primary-doc evidence; verify criticals (round-trip symmetry claims, scopeExtras gating, multi-write merge base) twice — run the test and re-read the generator path to confirm the gate is actually reached.
- Ledger cell `path`, `ext`, `format`, and `fingerprint` values MUST be derived from the conformance fixture's actual generated output — not from docs. Docs determine `maxAchievable`, `verdict`, and `source` only.

**Phase 2 — Single-writer close.**
After all per-target fixes are in, merge ledger provenance in one pass, then run `catalog:generate` → `matrix:generate` sequentially. Follow with exactly **one** full-stack run: `pnpm test` to completion, then `pnpm test:e2e` — never concurrent with a build, never interleaved. If any command fails, diagnose before retrying; a second blind retry without root-cause analysis wastes more context than it saves.

## Required Verification

Before claiming completion, every command must pass:

- `pnpm typecheck`
- `pnpm lint`
- `pnpm build` — **before** any e2e/round-trip run. The e2e matrix spawns the built `dist/cli.js`; the in-process contract test does not. If the contract round-trip passes but the e2e fails with a missing/extra/relocated file, the dist is stale — rebuild, don't chase the importer.
- `pnpm test`
- `pnpm matrix:verify`
- `pnpm capabilities:verify`

Run narrower target-scoped tests while iterating, but do not skip the full stack at the end. (Note: a few test runs rewrite `tests/e2e/agents-last-run.md` as a side effect — `git checkout --` that file before committing so it doesn't ride along.)

## Completion Standard

The task is not done until all of the following are true:

- Either the claim was **confirmed** from the tool's own primary source and implemented, or it was **rejected** with a one-line evidence-backed reason — never implemented on faith.
- The new level is declared in the descriptor for each scope it applies to, and `pnpm matrix:verify` passes.
- Generate **and** import are both covered by tests for every level raised to `native`; round-trip preserves content where the format permits.
- Global-only features emit via `scopeExtras` (not a project-leaking `generateX`), gated to `scope === 'global'`, with project scope staying `none`.
- `partial` features have a no-op generator stub and a lint warning verified by tests.
- Multi-write settings files merge with a `pending?.content ?? existing` base; single-combined-write mergers are left untouched.
- Every output path/format change is reflected in all blast-radius sites (contract arrays, e2e exclusion sets, both `reference-targets` chains, `dirTreeExactly`, layout/matrix tests) — verified by a tree-wide grep for the old string.
- No file exceeds 200 lines; no target-name branch was added to shared/core.
- Plugin path holds (rich-plugin fixture updated only if a hook *contract* changed).
- README matrix and the website supported-tools page agree with the descriptor.
- A changeset exists at the right level — `minor` for a new capability (level raise), `patch` for a same-level fix that makes an existing `native` claim actually work. `post-feature-qa` has been applied and any gaps closed.
- The full verification stack passes.