/harness-port-guide

name: harness-port-guide
description: 'Use when the user asks to make the skills framework work in a new harness, IDE, or CLI. Not for remote, credential, publish, deploy, or irreversible changes.'
disable-model-invocation: true

Harness port guide

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to make the skills framework work in a new harness, IDE, or CLI. | | Authority | Reversible local: writes only named harness artifacts (manifest, bootstrap injector, tool-mapping reference, tests, install docs) and edits to other harnesses' sync-exclude files; rollback is deleting those added files and restoring the prior content of any edited sync-exclude files. No credential, paid, published, deployed, remote, or VCS-history mutation. Never edit the user's global or personal config, and never edit a skill body to fit the harness. | | Side effect | Adds a manifest, a bootstrap injector, a tool-mapping reference and tests for the target harness; the version is tracked in the source manifest. | | Done | All six done-conditions hold: session-start bootstrap with no per-session opt-in, a tool mapping exists, skills are invocable natively or via a read-the-skill-file fallback, the acceptance test passes with a captured transcript, tests pass, and install works through the harness's own mechanism. |

Inputs

The target harness name and its install mechanism (plugin, extension, marketplace, git-URL, package-manifest field, or local installer) must be supplied. Optional: a prior port attempt for this harness, and the closest existing reference integration to copy.

Procedure

1. Search open and closed PRs and issues for a prior attempt at this harness; if one exists, understand why it stalled before starting a fresh attempt. Done when: the search returns zero prior attempts or a named prior attempt with its stalling reason, and no fresh code is written yet. 2. Check the capability checklist before writing code. Hard requirement: the harness must inject text into the model's context at the start of every session with no per-session opt-in: a hook or event system that runs a shell command and reads its stdout; an in-process plugin or extension with a session-start or message lifecycle callback that can mutate the message array; or an instructions-file convention where the harness loads a context file that the installed extension ships and the manifest declares. If the only path is per-session opt-in by the human partner, stop: the harness cannot be properly supported and the acceptance test will fail. Done when: the capability checklist is answered for the target harness, and the session-start injection requirement is confirmed met or the run stops with a stated inability. 3. Confirm the rest of the checklist: skill discovery and invocation (a native skill tool, or the sanctioned fallback of reading the relevant SKILL.md with the file-read tool: a harness with neither cannot work); file read, write, and edit (essential, no workaround); run shell commands (essential); subagent or task dispatch (degradable: point at the real tool when present, else reuse the skill's own fallback wording, and never invent a Task call); todo or task tracking (degradable: fall back to a plan file); web fetch or search (degradable). Before building, check whether the harness can load an existing manifest; a port that adds nothing but a README paragraph is a valid outcome. Done when: every checklist capability is confirmed present, degradable, or absent with a named workaround, and no capability is silently assumed. 4. Discover the harness's actual mechanism empirically; do not assume it behaves like a harness it forked from. Search the web for its docs; find and read an existing third-party extension, because a working example beats docs; check what it loads at startup. If it is underdocumented, reverse-engineer it: run strings or grep the binary and install tree for hook event names, config paths, and the instructions file it reads; ask the running model to list the exact machine names of every tool it can call, which is the authoritative way to get tool names without inventing them; and prove every assumption with a unique-marker test: inject a nonsense token through the mechanism believed to work, start a fresh session, and confirm the token reached the model. A fork does not inherit its parent's behavior, so verify with a marker even when the parent's recipe looks transferable. Done when: the harness injection mechanism is confirmed by a unique-marker test that injected a nonsense token and observed it reach the model in a fresh session, and every tool name is sourced from the running model or a working extension, not assumed. 5. Select and implement the integration branch in `references/integration-shapes.md`: shell hook, in-process plugin/extension, or always-loaded instructions file. Keep skill discovery and bootstrap delivery as separate decisions, use only the harness's real tool names, and ship everything through its own installer without editing user config or skill bodies. Done when: the chosen branch auto-injects the bootstrap every session, exposes skill invocation and the tool mapping, and its branch-specific tests pass.

6. Install locally from the working tree, not a published build; reinstall after each change and restart the harness, because the bootstrap loads at startup. Drive a live instance: most harnesses are interactive REPLs or TUIs that cannot be driven by piping stdin, so run the harness inside a detached tmux session and control it with send-keys and capture-pane. Clear first-run gates (onboarding, trust-this-folder, sandbox, or permission prompts) before the run, or the detached session stalls silently with no error while it waits. Run the smoke check first: ask the model to describe its skills; if the bootstrap injected it knows it has them, and if not, fix the bootstrap before the acceptance test. Then run the acceptance test in a clean session with the fr