harness-port-guide

Harness port guide

Contract

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.