docs/TOOL_REGISTRY.md

Tool Registry

The harness deals with two distinct kinds of "tool". Keep them separate.

	Capability manifest (outbound)	Inbound tool registry
Direction	harness offers it to the agent	a project equips it for the harness to use
Examples	the harness-cli subcommands below	gitnexus, c3, a linter, a deploy check
Presence	always compiled in	optional; may be absent on any machine
If missing	n/a (it is the harness)	clean skip; never blocks the main process

This document describes both. The inbound registry is the extension base: it is where the harness learns what extra capability is equipped, what purpose it serves, and whether it is actually present right now, so a workflow step can adapt to what is installed without the core ever depending on it.

Inbound Registry: Register A Tool

scripts/bin/harness-cli tool register \
  --name deploy-check \
  --kind cli \
  --capability deploy-verification \
  --command ./scripts/deploy-check.sh \
  --description "Verify deploy health before release" \
  --responsibility Verification \
  --args "env:enum:required:staging,production"

Fields specific to inbound tools:

• --kind — how the tool is reached and probed. One of cli, binary, mcp, skill, http. Defaults to cli. The kind tells each agent runtime what it can orchestrate (a non-Claude agent simply treats a skill it cannot run as absent) and tells tool check which probe to use.
• --capability — the workflow purpose a step looks the tool up by. Free-text but normalized to kebab-case, so Impact Analysis, impact_analysis, and impact-analysis all register as impact-analysis. This is the only coupling between a step and a tool; steps reference the capability, never the tool name.
• --scan — for mcp/skill/http, a declarative path or URL that tool check resolves to decide presence (e.g. .c3, ~/.claude/skills/c3, https://localhost:8080/health). cli/binary are probed via their command.

--force is only needed for cli/binary whose command is intentionally absent on the current machine. mcp/skill/http are not on PATH by nature, so they register without --force; their presence is resolved later by tool check.

Registering an MCP server or a Claude skill (examples):

scripts/bin/harness-cli tool register --name gitnexus --kind mcp \
  --capability impact-analysis --scan ".gitnexus" --command "mcp:gitnexus" \
  --description "Code-graph blast radius" --responsibility Verification
scripts/bin/harness-cli tool register --name c3 --kind skill \
  --capability impact-analysis --scan ".c3" --command "skill:c3" \
  --description "Component model and drift audit (Claude skill)" \
  --responsibility Verification

Remove a tool with:

scripts/bin/harness-cli tool remove --name deploy-check

Inbound Registry: Check Presence

Registration records intent. tool check reconciles intent with reality by scanning each registered tool and persisting the verdict (status and checked_at). Run it at intake start so status reflects current reality.

scripts/bin/harness-cli tool check            # scan all registered tools
scripts/bin/harness-cli tool check --name c3  # scan one
scripts/bin/harness-cli tool check --json     # machine-readable for agents

Probe per kind:

Kind	Probe	present means
cli, binary	command resolves on PATH or as a path	installed and runnable
mcp, skill	scan_target path resolves (~ expands)	equipped/configured on disk
http	scan_target reachable over TCP (2s), else path	endpoint answers

tool check always exits 0: a missing extension is a fact to report, not a CLI failure. A cli/binary is present when runnable. An mcp/skill/http present means equipped (config/file resolves), not live this session — the agent still confirms live usability at call time, since only the agent runtime can see whether its MCP server is actually connected. With no scan_target, the status is unknown and the agent must confirm.

Inbound Registry: Look Up By Capability

A workflow step asks "what is present for this purpose?" rather than naming a tool:

scripts/bin/harness-cli query tools --capability impact-analysis
scripts/bin/harness-cli query tools --capability impact-analysis --status present

The result is the set of providers. Multiple tools may provide one capability (gitnexus and c3 both serve impact-analysis and are complementary), so a step reads the set and degrades on how much of it is present.

Degrade Ladder

The CLI reports facts (status); the agent applies policy. The generic rule, keyed on the present-provider count for a capability:

Providers present	Posture	Agent behavior
none registered	Inactive	clean skip; note capability X: inactive in the trace. Not drift.
registered but none/some present	Degraded	run with what resolves; set the Weak proof flag; note the gap.
all present	Full	normal operation.

A registered tool that scans as missing is a failed validity gate, not a skip. A capability with no registered providers is simply inactive and is skipped without penalty — this is what keeps the core seamless on a fresh install.

Recommended Capability Vocabulary

Capability is open (no code change to add one), but a step and its providers must agree on the exact string. Reuse these where they fit before coining a new one; coin new ones in kebab-case:

impact-analysis · deploy-verification · coverage · security-scan
performance-benchmark · documentation-lookup

Inspecting The Registry

scripts/bin/harness-cli query tools --summary
scripts/bin/harness-cli query tools --json
scripts/bin/harness-cli query tools --responsibility Verification

JSON records carry kind, capability, scan_target, status, and checked_at alongside the existing fields, so any agent can read the registry without parsing the human table.

Compiled Harness Commands (Outbound Manifest)

Command	Responsibility	Purpose	Arguments
init	Task state	Create the harness database.	none
migrate	Task state	Apply pending schema migrations.	none
import brownfield	Project memory	Seed durable records from markdown state.	none
intake	Task specification	Record a feature intake classification.	--type, --summary, --lane
story add	Task state	Create a durable story record.	--id, --title, --lane, optional --verify
story update	Task state	Update story status, proof flags, evidence, or verification command.	--id, optional proof/status fields
story verify	Verification	Run one story verify_command and record pass/fail.	story id
story verify-all	Verification	Run all configured story verification commands and skip stories without one.	none
decision add	Project memory	Create a durable decision record.	--id, --title, optional --doc, --verify
decision verify	Verification	Run one decision verification command.	decision id
backlog add	Entropy auditing	Record a harness improvement proposal.	--title, optional pain/suggestion/risk/predicted fields
backlog close	Entropy auditing	Close a backlog item with outcome evidence.	--id, optional --status, --outcome
tool register	Tool access	Register an external project tool.	--name, --command, --description, --responsibility, optional --kind, --capability, --scan, --args, --force
tool check	Tool access	Scan registered tools and persist present/missing/unknown status.	optional --name, --json
tool remove	Tool access	Remove a registered external tool.	--name
intervention add	Intervention recording	Record a human, reviewer, CI, or agent intervention.	--type, --description, --source, optional --trace, --story, --impact
trace	Observability	Record an agent execution trace and print trace quality.	--summary, optional trace fields
score-trace	Observability	Score trace detail against lane requirements.	optional --id
score-context	Context selection	Score trace reads against compiled context rules.	trace id
audit	Entropy auditing	Run drift checks and compute entropy score.	none
propose	Entropy auditing	Generate improvement proposals from friction, interventions, and audit findings.	optional --commit
query matrix	Task state	Show durable story proof matrix.	optional --numeric
query backlog	Entropy auditing	Show harness improvement backlog.	optional --open, --closed
query decisions	Project memory	Show durable decision records.	none
query intakes	Task specification	Show recent intake records.	none
query traces	Observability	Show recent trace records.	none
query friction	Failure attribution	Show traces with harness friction.	none
query tools	Tool access	Show compiled and registered tool entries.	optional --json, --summary, --responsibility, --capability, --status
query interventions	Intervention recording	Show intervention records.	optional --trace, --story, --type
query stats	Task state	Show durable record counts.	none
query sql	Tool access	Run arbitrary SQL against harness.db.	SQL text
db changeset apply	Task state	Apply one semantic changeset idempotently.	changeset path
db rebuild	Task state	Rebuild a fresh harness.db from semantic changesets.	--from changeset directory

Validation Rules

• Tool names must be unique among registered tools.
• Descriptions must be 10-200 characters.
• Responsibilities must match the Runtime Substrate responsibility list.
• --kind must be one of cli, binary, mcp, skill, http.
• --capability must be kebab-case (lowercase letters, digits, single hyphens); spaces and underscores are normalized to hyphens.
• --args entries must use name:type:required or name:type:required:help, with required or optional as the third field.
• For cli/binary, the command must exist as a path or on PATH, unless --force is supplied. mcp/skill/http skip this check.