agent-harness
Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for authoring Claude Code Workflow-tool .js scripts (workflow-builder), N-agent tournaments on one task (agenthub), single-file metric optimization (autoresearch-agent), or discovering published loop recipes (loop-library).
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- agent-harness
- description
- Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for authoring Claude Code Workflow-tool .js scripts (workflow-builder), N-agent tournaments on one task (agenthub), single-file metric optimization (autoresearch-agent), or discovering published loop recipes (loop-library).
02 资源文件 25
- 资产文件assets/harness_manifest.schema.json3.1 KB
- 资产文件assets/harnesses/business-growth.json9.1 KB
- 资产文件assets/harnesses/business-operations.json18.8 KB
- 资产文件assets/harnesses/c-level-advisor.json81.6 KB
- 资产文件assets/harnesses/commercial.json20.9 KB
- 资产文件assets/harnesses/compliance-os.json7.8 KB
- 资产文件assets/harnesses/engineering-team.json77.8 KB
- 资产文件assets/harnesses/engineering.json128.7 KB
- 资产文件assets/harnesses/finance.json6.1 KB
- 资产文件assets/harnesses/loop-library.json1.3 KB
- 资产文件assets/harnesses/markdown-html.json14.0 KB
- 资产文件assets/harnesses/marketing-skill.json68.0 KB
- 资产文件assets/harnesses/marketing.json3.1 KB
- 资产文件assets/harnesses/product-team.json24.5 KB
- 资产文件assets/harnesses/productivity.json31.7 KB
- 资产文件assets/harnesses/project-management.json15.7 KB
- 资产文件assets/harnesses/ra-qm-team.json34.8 KB
- 资产文件assets/harnesses/research-ops.json18.8 KB
- 资产文件assets/harnesses/research.json22.4 KB
- 参考文档references/agentic_loop_canon.md6.1 KB
- 参考文档references/domain_harness_design.md6.5 KB
- 参考文档references/verification_discipline.md6.2 KB
- 脚本scripts/goal_compiler.py.txt8.1 KB
- 脚本scripts/harness_manifest_builder.py.txt9.2 KB
- 脚本scripts/loop_controller.py.txt16.0 KB
03 SKILL.md 正文
Agent Harness
You are a harness operator, not a hero. The loop — not your optimism — decides when work is done. Your job: compile the goal into tasks with checks, execute one task at a time, let the controller adjudicate verification, and stop when the state machine says stop.
The contract
GOAL → goal_compiler → PLAN → loop_controller: [execute → verify]* → CLOSE
↑______retry (≤ max_attempts, changed approach)
└── ESCALATE on exhausted budgets — never fake success
Three layers, all JSON: a committed per-domain manifest (what skills/tools/checks exist), a per-goal plan (which tasks, which verifications, what "done" means), and a per-run state file (the single source of truth; a fresh session resumes from it alone).
Quick start
# 0. Pick the domain manifest (18 committed under assets/harnesses/, e.g. engineering-team.json)
ls assets/harnesses/
# 1. Compile the goal (refuses vague goals with exit 3 + forcing questions)
python3 scripts/goal_compiler.py \
--goal "audit the payments service and design an SLO with an error budget" \
--manifest assets/harnesses/engineering.json --out plan.json
# 2. Initialize the loop state
python3 scripts/loop_controller.py init --plan plan.json --state .agent-harness/state.json
# 3. Drive the loop — repeat until directive is "close" or "escalate"
python3 scripts/loop_controller.py next --state .agent-harness/state.json
# → {"action": "execute", "task": "T1", ...}: open the task's skill (SKILL.md at
# skill_path), do the work with its tools, then:
python3 scripts/loop_controller.py record --state .agent-harness/state.json \
--task T1 --phase execute --exit-code 0
# → the controller runs the task's checks ITSELF (subprocess, timeout, evidence log):
python3 scripts/loop_controller.py verify --state .agent-harness/state.json --task T1 --cwd <repo-root>
# 4. Close — refused (exit 4) while any task is unverified and unwaived
python3 scripts/loop_controller.py close --state .agent-harness/state.json
Regenerate a manifest after skills change (diff-stable, CI-checkable):
python3 scripts/harness_manifest_builder.py --domain engineering-team \
--repo-root <repo-root> --out-dir assets/harnesses --no-timestamp
Hard rules
- Never adjudicate your own verification.
verifyruns the checks via subprocess; a passingrecord --phase verifywithout--evidenceis rejected (exit 6). You do not get to declare a task verified. - Never modify a gate you are judged by. Check commands come from the manifest/plan. Editing a check to make it pass is the reward-hacking failure mode (see references/verification_discipline.md) — same invariant as autoresearch-agent's locked evaluator.
- One task at a time, writes serialized. Parallelize reading and judging, never two tasks writing the same artifact (references/agentic_loop_canon.md).
- Retry means a changed approach. Same command + same input = same failure. The retry directive says so; honor it.
- Budgets are terminal states, not suggestions.
max_attempts_per_task→ escalated (exit 2);max_loop_iterations→ escalate (exit 5). Exhausted budgets are never reported as success — a human waives (close --waive T3 --reason "..."), you don't. - Fresh context beats long context. Every
nextdirective is executable by a new session reading only the plan + state files. Long-running goals: run each iteration as its own session against the durable state. - State lives in
.agent-harness/— never in.agenthub/,.autoresearch/, ordocs/TC/(those belong to sibling skills). - Plan and state files are a trust boundary.
verifyshell-executes each task's check command; only run the harness on plan/state files you orgoal_compiler.pyproduced, never on files from untrusted input (see references/verification_discipline.md).
Forcing questions (ask before compiling; one per turn, with a recommended answer)
| # | Question | Recommended answer | Why (canon) |
|---|---|---|---|
| 1 | What single observable outcome means DONE? | A named artifact + a command that exits 0 against it | Verifier's law: invest in verifiability first |
| 2 | Which domain harness applies? | The domain whose skills name the deliverable; if two, run two sequential loops | Orchestrator-workers: scoped objectives beat mega-goals |
| 3 | What must NOT change? | List no-touch paths; put them in the goal text so the compiler's plan inherits them | Boundaries are part of a subagent spec |
| 4 | Who reviews escalations, and how fast? | A named human; escalations block the loop by design | Approval-required is a terminal state, not a nuisance |
| 5 | What is the iteration budget? | Default 12 loop iterations / 3 attempts per task; raise only with a reason | Caps are runtime errors, not advice (OpenAI SDK max_turns) |
Exit codes (branch on these mechanically)
| Code | Tool | Meaning |
|---|---|---|
| 0 | all | OK / directive emitted |
| 2 | loop_controller | Escalation required — a human must review the evidence log |
| 3 | goal_compiler | Goal too vague — answer the forcing questions, recompile |
| 4 | goal_compiler / loop_controller | No skill matched / close refused (unverified tasks) |
| 5 | loop_controller | Global iteration cap reached |
| 6 | loop_controller | Invalid transition (recording on verified task, evidence missing, unknown task) |
Verifiable success
python3 scripts/harness_manifest_builder.py --sample,scripts/goal_compiler.py --sample, andscripts/loop_controller.py --sampleall exit 0.- A vague goal (
--goal "make it better") exits 3 and prints forcing questions. loop_controller.py closeon a state with an unverified task exits 4.- The demo loop in
loop_controller.py --sampleshows a verify failure consuming an attempt and the loop still closing only after a passing verify with evidence.
Related skills
- workflow-builder: authoring deterministic
.jsscripts for Claude Code's Workflow tool. NOT for goal-to-close loop state (this skill). - agenthub: N parallel agents competing on ONE task in git worktrees. Use it inside a harness task that wants competing attempts.
- autoresearch-agent: metric optimization of a single file against a locked evaluator. Use it when a task's done_when is "metric improves".
- tc-tracker: per-code-change lifecycle records. Use for change bookkeeping; the harness state file is per-goal, not per-change.
- loop-library: discover/audit published loop recipes conversationally. This skill is the executable enforcement of that vocabulary.
- ship-gate / self-eval / spec-driven-workflow: plug in as close-time checks inside a
task's
verification[].
See references/domain_harness_design.md for the three-layer architecture, the reuse map, and how to raise a domain's harness quality.
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
youtube-downloader
Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
template-skill
Replace with description of the skill and when Claude should use it.
tailored-resume-generator
Analyzes job descriptions and generates tailored resumes that highlight relevant experience, skills, and achievements to maximize interview chances
slack-gif-creator
Toolkit for creating animated GIFs optimized for Slack, with validators for size constraints and composable animation primitives. This skill applies when users request animated GIFs or emoji animations for Slack from descriptions like "make me a GIF for Slack of X doing Y".