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; the run delivers a port whose bootstrap auto-injects every session and passes the captured acceptance transcript. Don''t use for remote, credential, publish, deploy, or irreversible changes.'
---

# 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 — add only the named harness artifacts (manifest, bootstrap injector, tool-mapping reference, tests, install docs); rollback is deleting those added files. 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 simply 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 with a named fallback, or absent with a stated consequence, and the harness own manifest-loading path is checked before building.
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 framework's defined trigger prompt and confirm the relevant skill auto-triggers before any code is written. Poll capture-pane in a loop rather than capturing once; send the prompt text and Enter as separate send-keys calls with a short sleep between them, because sending them together races on some TUIs; use the harness's own transcript or log file as the record of truth for long conversations; always kill-session when done. Capture the full transcript — it is required proof. Done when: the chosen integration branch auto-injects the bootstrap every session (confirmed by marker test), exposes skill invocation and the tool mapping, and its branch-specific tests pass.
7. Write install docs whose only supported install action is running the harness's own install command; hand-copying skill files and editing the user's global or personal config are both off-limits. Register the version: if the harness introduces a new versioned manifest, add its path and version field to the version-tracking source so the bump script keeps it in lockstep; if it rides an already-tracked file, there is nothing new to add. If no existing distribution channel fits, stand up a new one — clone the closest sync template, note its anchored include/exclude list, and add the per-harness directory to the other harnesses' sync excludes so it does not leak into their distributions. Done when: install docs name only the harness own install command, the version is registered in the tracking source or confirmed riding an existing tracked file, and any new distribution channel is stood up with its sync excludes added.

## Failure and recovery
- Per-session opt-in only: the harness cannot be properly supported. Stop; do not ship a partial port. The acceptance test will fail.
- Wrong JSON field, nesting, or event-matcher (Shape A): the hook silently never fires or double-injects. Re-source the exact field, nesting, and matcher strings from the harness or a marker hook; do not guess.
- Bootstrap not loading (smoke check fails): fix the bootstrap before running the acceptance test; never run the acceptance test against a broken bootstrap.
- Acceptance test fails (the skill does not auto-trigger before any code): the port is not done. Re-check the bootstrap injection, the tool-mapping reachability, and — for the surfaced-index fallback — that the test ran on the model or models users will actually use.
- Installer strips the bootstrap: declare the bootstrap as a recognized component, such as a manifest-declared context file; never substitute a user-config edit.
- Include treated as a hint rather than an expansion (Shape C): inline the content rather than include it.
- Undeclared type import fails under type-check or bundle: confirm the approach with the maintainer rather than quietly adding a runtime dependency.
- Partial-result rule: a port that satisfies some but not all six done-conditions is non-converged. State exactly which conditions hold and which do not; do not merge and do not claim the done predicate holds.
- Rollback: delete the added harness artifacts — manifest, bootstrap injector, tool-mapping reference, tests, and install docs. The framework's shared skill bodies were never edited, so no skill rollback is needed.

## Output
A port for the target harness comprising a manifest or entry point, a bootstrap injector or extension-declared context file, a tool-mapping reference, tests, and install docs — all delivered through the harness's own install mechanism, with the version tracked in the source manifest. A captured acceptance-test transcript showing the relevant skill auto-triggering before any code is written. A terminal classification: done, when all six done-conditions hold, or non-converged, naming which conditions fail.