Ultimate Harness Documentation
Ultimate Harness is a runtime-agnostic development harness for planning, launching, observing, verifying, and promoting agentic software-development work across multiple coding agents.
The core design goal is portable discipline: a project should be able to use multiple coding-agent runtimes without losing its specifications, skills, workflow state, audit trail, sandbox boundaries, or human approval checkpoints.
For the active roadmap (epics, in-flight slices, recently shipped), see ROADMAP.md.
Start here
Section titled “Start here”- Quickstart — install, initialize, run, verify, and inspect a mission.
- Operator handbook — the operating loop: dispatch, guard, supervise, watch and stop, settle, verify, review, integrate, prove.
- Known issues — open defects, gaps and unproven claims.
- Orchestrator guide — mission lifecycle, team execution, observability, human decisions and CLI reference.
- Configuration — project state, env vars, and runtime overrides.
- Runtime targets — supported runtimes and adapter boundaries.
- Vision — what UH is, who it’s for, and what we won’t accept.
- Glossary — shared terms used across the project.
- Product requirements — what the harness is for and who it serves.
- Architecture overview — major components and boundaries.
- Runtime adapter contract — what every adapter implements.
- Mission packet schema — the portable work-request format.
- Native runtime events — adapter event contracts, supervision and accounting boundaries.
- Tool guard — path-only policy, enforcement seams, denial reasons, and artifacts.
- Verification and promotion — how sandbox work becomes canonical work.
- BMAD agent map — how BMAD-style roles map into Ultimate Harness.
Adapters
Section titled “Adapters”| Adapter | Status | Doc / Runbook |
|---|---|---|
hermes |
active | Runtime adapter contract defines the shape; src/adapters/hermes.ts is the reference implementation. |
codex |
active | Codex adapter design, Codex E2E smoke |
hermes-proxy |
active | Hermes proxy adapter, setup, E2E smoke |
openrouter |
active | OpenRouter setup |
anthropic |
experimental | Anthropic setup — native pay-per-token Messages API (UH-136). |
pi |
active | Pi setup |
oh-my-pi |
active | Anthropic via oh-my-pi — covers the OMP routing path and its ToS posture. |
command-code |
active | Tool guard, Acceptance runbook |
claude-code |
integration incomplete | Runtime targets — native CLI execution and current limitations. |
- Acceptance status — generated view of the registry and locally available evidence; a clean checkout contains no execution history.
- Acceptance runbook — register, run, inspect, and regenerate acceptance evidence. For issue-level state and upcoming epics, see ROADMAP.md.
Documentation map
Section titled “Documentation map”Research
Section titled “Research”- Inspiration systems
- research/landscape-register.md: dated, primary-source register of what existing systems do for each 1.0 build item, with per-row verification status and re-check triggers.
- Comparison matrix
- Adopt / reject / defer decisions
Product
Section titled “Product”- Quickstart
- Configuration
- Runtime targets
- Optional telemetry
- Troubleshooting
- PRD
- MVP scope
- Non-goals
- Personas
Architecture
Section titled “Architecture”- Overview
- Entities
- Runtime adapter contract
- Delegation and containment
- Codex adapter design
- Hermes proxy adapter design
- TUI architecture
- Plugin development
- Mission packet schema
- .harness artifacts
- Skill format
- Sandboxing
- AgentFS sandbox backend (design)
- Verification and promotion
- SDD + TDD + cross-runtime QA
- Progressive decisions — implemented semantic evaluation and proposed policy flows.
- Telar planning/governance and UH Run Control boundary
Runbooks
Section titled “Runbooks”- Codex E2E smoke
- Anthropic via oh-my-pi
- Hermes proxy setup
- Hermes proxy E2E smoke
- Hermes dashboard plugin
- Using
uh tui - Honcho persistent memory
- Publishing
- Resource-wave smoke
- Worker-contract smoke
- Tool-guard smoke
- Supervisor-loop smoke
- MCP server
- Run control
- Independent review
- Acceptance
- ACP setup
- Container sandbox
Operator handbook
Section titled “Operator handbook”- Handbook index
- Run control
- Slices and teams
- Review round trip
- Closing the loop — post-checks,
uh queue,uh land - Acceptance
- Fleet
- Packet rules
- Notifications
- Intervention ledger
Workflows
Section titled “Workflows”- Workflow overview
- Research to spec
- Spec to plan
- Plan to mission
- Mission to sandbox
- Verify, review, promote
- BMAD agent map