External Tool Contract
Required CLI tools and how agents report tool blockers
External tools are part of the Harness operating baseline.
skills, opensrc, agent-browser, portless, debug-agent, clawpatch, and stack belong to the expected harness workspace. Some runs may skip a tool because the surface does not need it. The baseline still expects every tool to be available so agents can choose the right evidence path without renegotiating the environment.
skills
skills makes shared workflow and implementation skill contracts installable and updateable. Harness guidance can assume the relevant skill entrypoints exist instead of pasting every workflow contract into prompts.
skills lsopensrc
opensrc makes dependency and curated example source inspection repeatable when package behavior shapes a decision.
Official docs come first. Source inspection matters when docs are stale, vague, or too abstract for the implementation question. Agents are good at reading code, following real call paths, and comparing examples against the repo in front of them. Cloning or locating source gives the agent concrete behavior to inspect instead of relying on memory of how a library is supposed to work.
opensrc path --cwd . <package>
opensrc path <owner>/<repo>Repo-local opensrc/*.md files are source guide cards, not cloned source. A card tells the agent which package command to run, which fallback repository lookup to use, and where to start reading after opensrc returns the cache path. The source itself stays in the global ~/.opensrc cache unless the operator explicitly chooses a different cache root.
The required tool baseline expects opensrc >=0.7.2.
Scaffold setup must not invent concrete opensrc repositories. The post-scaffold agent identifies the detected core libraries whose source behavior matters and asks the user only when that set is ambiguous.
agent-browser
agent-browser turns routed and interactive web validation into observable browser evidence. For pages, forms, dashboards, auth flows, or visual states, the harness should prefer observing the running app over inferring behavior from a successful build. See Validation Gates for when browser evidence is required.
agent-browser open <url>
agent-browser snapshotportless
portless provides stable *.localhost origins and avoids raw port collisions across worktrees.
Use portless local subdomains in examples, callback URLs, allowed origins, CORS, and app-to-app proxy targets. Raw localhost:<port> values are acceptable as transient command output, but stable docs and generated guidance should prefer the portless baseline.
portless run <cmd>
portless get <name>debug-agent
debug-agent supports runtime evidence workflows when logs, repros, traces, screenshots, or timing matter. It belongs in Debugging when validation or review exposes a runtime failure and the agent needs evidence before patching.
debug-agent serveclawpatch
clawpatch supports AFK static bug discovery, durable finding ledgers, report generation, triage, and selected-finding revalidation. It belongs in Massive Bug Hunt And Fix.
Discovery runs should use read-oriented commands and record provider/model as automatic default or explicit override. clawpatch fix --finding and clawpatch open-pr are explicit mutation paths and are not part of the default discovery story.
By default, ClawPatch inherits the current agent/launcher provider. Add --provider or --model only when the operator explicitly selects an override.
clawpatch doctor
clawpatch review
clawpatch report --output .clawpatch/reports/<name>.mdstack
stack supports squash-safe stacked PR workflows when backlog-dependent work is represented by an open parent PR. It is required for stack-dependent planning and delivery, but missing stack does not block independent trunk-based work.
Harness uses PR bases as the normal source of stack truth. stack sync --dry-run is the inspection gate. stack sync is the mutation gate after the preview is correct.
stack status
stack sync --dry-run
stack sync
stack merge --auto
stack undo --applyPhase skills decide when these commands apply. $create-spec records dependency readiness, $implement-spec enforces recorded branch/base intent, $delivery-phase may sync, and $review-phase stays readonly.
Failure Reporting
Tool absence is part of the evidence trail. If a required tool is unavailable, the agent records the exact blocker or limitation and the validation path it affected.
The agent should not silently replace browser validation with a guess, skip source inspection when package behavior is central, claim portless-compatible setup when only a raw port was tested, treat ClawPatch findings as proven runtime root causes without runtime evidence, or mutate a stacked PR chain without a correct stack sync --dry-run preview.
Done Signal
Tool usage is complete when required tools were checked or used for the relevant surface, unavailable tools were reported as blockers, and generated manifests remain aligned with the repo's selected packs.