---
name: cross-harness-compatibility-standards
description: >-
  The engineering/architecture standard for actually BUILDING a Claude
  agent-family (or any multi-runtime capability) so it genuinely works
  across Claude Code, Codex, Pi, and Hermes, not the consumer-facing
  install docs once it already works (that's
  cross-harness-authoring-standards). Use when deciding whether a
  capability earns a new user-facing skill or should stay a thin
  runtime-specific agent/seat/extension, before writing a Pi extension or
  Hermes command and unsure whether the target API actually exists,
  defining a structured handoff record two or more runtimes must exchange,
  or naming a new plugin distribution/marketplace channel alongside an
  existing one. NOT for writing the resulting per-harness install commands
  (cross-harness-authoring-standards owns that, once the capability
  already works).
disable-model-invocation: false
user-invocable: true
---

# cross-harness-compatibility-standards, build it portable, don't just document it

`cross-harness-authoring-standards` covers the downstream concern: writing the
consumer-facing install instructions once a capability already works across
harnesses. This skill covers the upstream concern, the engineering standard
for actually **building** that capability so it works on Claude Code, Codex,
Pi, and Hermes in the first place. If you're drafting a "how to install"
block, you want the other skill; if you're deciding whether something needs
a new skill, writing a Pi/Hermes adapter, or designing a structured record
two runtimes must exchange, you're in the right place.

This standard is not invented doctrine: it is extracted from
[ADR-0091](../../../../../docs/ops/adr/adr-0091-ui-architect-cross-harness-portability.md)
and its companion
[PRD](../../../../../docs/ops/prd/prd-ui-architect-cross-harness-portability.md)/
[SPEC](../../../../../docs/ops/spec/spec-ui-architect-cross-harness-portability.md)/
[LLD](../../../../../docs/ops/lld/lld-ui-architect-cross-harness-portability.md),
ratified and built across four merged PRs (#1997 docs, #1998 skill + contracts
+ Codex marketplace, #1999 agent pinning, #2000 Pi extension + Hermes
command) that made `ui-architect` portable. Every rule below cites the
decision or requirement it comes from, re-read the source before extending
this standard, don't paraphrase from this skill alone.

## Rule 1, skill vs. thin adapter: earn the promotion `[gate]`

Substantive reusable behavior belongs in a portable skill body; a
runtime-specific agent/seat/extension stays **only if** it provides one of:
restricted tools, isolated context, parallelism, multi-skill preload, or a
distinct model/effort configuration (ADR-0091 D1). Delete an agent, or fold
it into its skill, if it provides none of those structural properties. Never
convert every internal seat into a user-facing skill merely because
portability is required, a capability is user-invocable only when a user
has a sensible reason to request it directly, not because promoting it was
convenient.

Apply the rule by checking each existing seat against it, on the record, not
by assertion:

- `ui-architect` was the one seat of four in `adia-ui-factory` missing its
  skill twin, it earned `skills/ui-architect/SKILL.md` because the
  Gear-selection/wave/generator-≠-reviewer/four-lap-cap/failure-routing
  procedure is exactly the "substantive reusable behavior" class the rule
  routes to a skill, and Codex/Pi/Hermes users are the concrete "sensible
  reason to request it directly." The agent seat was **retained, not
  replaced**: no Write/Edit (restricted tools), dispatches into isolated
  per-screen contexts (isolated context + parallelism), pinned `fable`/
  `high` never-`inherit` (distinct model/effort), independently sufficient
  to keep it.
- `app-planning-agent`, `screen-composition-agent`, `surface-qa-agent`
  already each preloaded a same-named user-invocable skill before this
  change touched anything: the rule was already satisfied; nothing about
  their shape changed beyond the same Claude-adapter slimming (Rule 3)
  applied to all four seats equally.
- `wave-coordination` stayed `user-invocable: false`, Claude-only,
  unpromoted, team-pattern *mechanics* for one runtime's dispatch model,
  not a capability a Codex/Pi/Hermes user has a sensible reason to request
  directly. Failing the rule's own admission test on purpose is a legitimate
  outcome, not an oversight to fix later.

## Rule 2, verify before coding, per harness, every time `[gate]`

Never assume a target harness's API, extension mechanism, or delegation
surface from documentation alone. Check the actually-installed version
live, read its real source, run its real CLI, before writing one line of
adapter code against it. This is the single most load-bearing lesson from
how `ui-architect`'s Pi and Hermes adapters were actually built (PR #2000):

- **Pi** was verified present by reading the installed
  `@earendil-works/pi-coding-agent` package directly: its own shipped
  `examples/extensions/subagent/` proved a real subprocess-based
  subagent-dispatch pattern (`registerCommand` + `child_process` spawn of a
  nested `pi --mode json -p --no-session`), and `package.json`'s
  `pi.extensions` field was confirmed real and documented, not inferred by
  analogy to Claude's Agent tool. Once verified, the extension was
  **live-tested end to end**: a real `pi` session ran `/ui-architect`
  against a live model, dispatched all three isolated passes, wrote a real
  file, took a real screenshot, and returned a clean `VerifyProof`.
- **Hermes** was verified sufficient by reading the installed Hermes
  Agent's own source, `PluginContext.register_command` + `dispatch_tool`,
  and, inside that same external Hermes Agent install (not a path in this
  repo), `tools/delegate_tool.py`'s `delegate_task(goal, context, role, ...)`,
  confirmed as real, current APIs before the generator surgery (Rule 3)
  was written against them. The generated command was built behind its own
  `--selftest` fixture (a real `py_compile` check plus a fake `delegate_task`
  double driving the actual generated logic against the real linters)
  *before* wiring it into the real plugin tree, then verified live via
  `hermes plugins doctor --ci`. A full interactive dispatch was blocked by
  the build sandbox refusing to mutate Hermes's global plugin-enable
  state: that limitation was **noted honestly in the README rather than
  worked around or silently dropped**.

If a required capability is genuinely absent, or materially different from
what the docs claimed (SPEC REQ-011/012's capability-boundary discipline):
stop that adapter at an explicit, clearly-labeled capability boundary and
record four things, the API checked, the observed mismatch, the smallest
viable fallback, and the remaining work. Never simulate success with an
unverified manifest field or a dead adapter file that looks like it works
but was never actually exercised. One of the two outcomes (working adapter
+ passing native smoke test, or a capability-boundary record with all four
fields) must exist, never neither, never both.

## Rule 3, one authored copy, many thin consumers

The portable behavior lives in exactly **one** skill body. Every runtime's
own adapter mechanism *consumes* that one body, it never gets a second,
hand-copied prose duplicate:

- **Claude** preloads it (`skills:` frontmatter on the owning agent file).
- **Codex** auto-derives its manifest sibling
  (`skills/<name>/agents/openai.yaml`) from the same skill frontmatter via
  this repo's own generator (`scripts/build/codex-manifests.mjs`), no
  manual authoring, ever.
- **Pi**'s extension reads the skill file *at runtime* rather than copying
  its prose into the extension source (`ui-architect`'s
  `pi/ui-architect.extension.ts` loads agent descriptions from the
  plugin-local skill directly).
- **Hermes**'s command derives from the same source
  (`scripts/build/harness-manifests.mjs`'s generated `__init__.py`
  registers the skill; the generated `/ui-architect` command runs the same
  planning/composition/QA loop through `delegate_task`, gated by the same
  contracts).

A change to the workflow means editing one file, not four. If you find
yourself pasting a skill's prose into an agent file, an extension, or a
generator template instead of citing or reading it, stop, that's the
duplication this rule exists to prevent.

## Rule 4, one contract grammar, not a schema per runtime

When two or more runtimes need to exchange a structured handoff record,
define it once as a plain strict-prose-record shape validated by a small
stdlib CLI linter, never introduce JSON Schema or another
schema-validation library into every runtime's own toolchain to do the same
job (ADR-0091 D3). This repo's own `record-lint` family is the reusable
grammar: `<script> <file>|-|selftest`, exit 0 clean / 1 on findings, with
`UNMEASURED, <reason>` as a legal per-slot value (silent omission is not
legal). `OrientationRecord` (`scripts/record-lint`), `VerifyProof`
(`scripts/verify-proof-lint`), and `BuildResult`
(`scripts/build-result-lint`), all three in `adia-ui-factory`'s
`scripts/`, are structurally identical siblings, not three different
formats doing the same job. Every runtime adapter that produces or consumes
one of these contracts calls the same linter script; a second,
runtime-specific parsing or validation implementation for the same contract
is a defect, not a stylistic choice.

Before minting a new contract shape, check whether an existing one already
covers it under a different name, reuse beats a fourth near-duplicate
grammar.

## Rule 5, name distribution channels distinctly

When the same plugin ships **both** an in-repo/access-gated channel and a
public/npm-sourced channel for the same runtime, name them distinctly. A
collision, both channels sharing one marketplace name, makes
`<plugin>@<marketplace-name>` resolution ambiguous for a consumer trying to
install from a specific channel.

The confirmed, working precedent is Claude's own two-channel split: the
repo-root, access-gated `.claude-plugin/marketplace.json` is named
`adia-ui-kit`; the public, npm-sourced
`packages/plugins/adia-plugins/marketplace.json` is named `adia-plugins`
(ADR-0091 D2's own table), two distinct names, two distinct reachability
tiers, no ambiguity for a consumer running `/plugin install
<plugin>@<marketplace-name>`.

ADR-0091 D2 designed the Codex side to mirror that same split (a
repo-root/local-source channel alongside the existing
`packages/plugins/adia-plugins/.agents/plugins/marketplace.json` npm
sibling), but the LLD (§C7) flagged the new manifest's `name` field as an
explicit, unverified, build-time question: does Codex key off `name` for
`<plugin>@<marketplace-name>` resolution the way Claude does? **Verify this
against the actually-shipped manifests before citing the Codex side as a
settled precedent**, Rule 2's verify-before-coding discipline applies to
this rule's own worked example, not only to Pi/Hermes adapters. Diff the
`name` field of both Codex marketplace manifests against each other before
assuming they follow the Claude-side pattern.

## Failure branches

A capability promoted to a user-facing skill with none of Rule 1's five
qualifying properties on its remaining agent seat → fold the seat into the
skill or delete it; don't keep a Write/Edit-free, non-isolated, no-model-pin
shell around "for consistency." An adapter written against a harness's
documented API with no live verification → stop, verify against the
installed runtime first (Rule 2); a passing test against a mocked or
assumed API is not verification. A second hand-copied prose block for a
skill's workflow anywhere outside its one `SKILL.md` → delete the copy,
point the consumer at the source (Rule 3). A new structured record
introduced as JSON Schema, or as a shape that already has a linter under a
different name → stop, extend `record-lint`'s family instead or reuse the
existing contract (Rule 4). A new distribution manifest reusing an existing
sibling's marketplace name → rename before shipping (Rule 5).

Done when: every new or promoted seat cites the specific Rule 1 property
that keeps it (or is deleted/folded); every harness adapter names the API
it verified live and how (Rule 2); the skill body has exactly one authored
copy with every consumer citing or reading it, never duplicating it (Rule
3); every cross-runtime contract has exactly one shape and one stdlib
linter (Rule 4); and every distribution channel's marketplace name is
diffed against its siblings and confirmed distinct (Rule 5).
