AGENT SKILL

finhub-harness

Designs a harness for a project or domain: the specialist agents, the skills each one uses and a surface-aware orchestrator for Claude Code, Claude chat or Claude Cowork. Use when the user asks to 'build a harness', 'set up a harness', 'design a harness', 'create an agent team', 'build an agent team for X', 'make a finhub harness', or to rework, extend, migrate or enrich a harness ('add an agent', 'upgrade the harness to v2', 'borrow the judge-panel pattern from repo Y'), and to operate one ('audit the harness', 'check harness status', 'sync agents and skills'). Do NOT use for a light, quick, small or cheap harness (use finhub-harness-light), for running a harness that already exists (call its orchestrator skill) or for folding run feedback back in (use finhub-harness-evolve).

License 许可
Apache-2.0
最近更新
2026-11-12
Stars
★ 1
Forks
0

01 前言 Front Matter

name
finhub-harness
description
Designs a harness for a project or domain: the specialist agents, the skills each one uses and a surface-aware orchestrator for Claude Code, Claude chat or Claude Cowork. Use when the user asks to 'build a harness', 'set up a harness', 'design a harness', 'create an agent team', 'build an agent team for X', 'make a finhub harness', or to rework, extend, migrate or enrich a harness ('add an agent', 'upgrade the harness to v2', 'borrow the judge-panel pattern from repo Y'), and to operate one ('audit the harness', 'check harness status', 'sync agents and skills'). Do NOT use for a light, quick, small or cheap harness (use finhub-harness-light), for running a harness that already exists (call its orchestrator skill) or for folding run feedback back in (use finhub-harness-evolve).

02 资源文件 29

03 SKILL.md 正文

FinHub Harness — agent teams, their skills and a surface-aware orchestrator

Ported from revfactory/harness v2.1.0 (Apache-2.0), translated to English and extended for FinHub. Original: https://github.com/revfactory/harness. FinHub additions: surface adaptation (Code / chat / Cowork), the Authority List with a fresh-context adversarial audit, mutation-tested boundary QA, and licence-tiered enrichment from other harness repos.

Design a harness that fits the project. Define each agent's role, write the skill each agent follows when it works, and write one orchestrator that says who collaborates, in what order, on which surface.

Light option. If the user asks for a light, quick, small or cheap build, or the job is one small task, use finhub-harness-light instead: it is under a quarter of this file's size. A harness built here can still run light: see the Run mode bullet in Step 5.

Core principles

  1. Agent definitions live in project/.claude/agents/, skills in project/.claude/skills/. An agent definition says who works; a skill says how the work is done. Keep them apart.
  2. Choose the execution mode from the shape of the work. If the item list, the verification rule and the repeat condition can be written as code, orchestrate with a Workflow. If the same expert must trade feedback across turns, use persistent named agents. If you only need a result once, delegate to a sub-agent. Step 2-1 gives the rule; the full decision tree is references/execution-modes.md §4.
  3. Choose the model per agent from the task's complexity, duration, autonomy and latency need: fable for long-horizon autonomous planning, opus for bounded deep reasoning (design, code generation, cross-checking), sonnet for routine work. The criteria are in references/model-selection-guide.md. Never set every agent to the top model because "it matters".
  4. Record only the trigger conditions and a change history in CLAUDE.md, so a new session can find the orchestrator. Everything else lives in the orchestrator and the agent/skill files.
  5. Feed what each run teaches back into the agents, skills and CLAUDE.md. The retrospective is finhub-harness-evolve's job.
  6. Write every generated artefact in the language the user writes in. Do not copy this skill's language or the templates' example wording; translate headings and examples. If the user extends an existing harness, follow the language of the existing files.
  7. Declare the target surface. Every orchestrator says whether it runs on Claude Code, Claude chat, Claude Cowork or several. Modes A/B/C exist only in Claude Code; chat and Cowork need a single-context fallback. references/surfaces.md says exactly how each primitive degrades.
  8. Borrowed patterns carry a citation. A design decision taken from a reference repo enters the harness through an Authority List row (claim → references/<repo>/<path>:<line>, licence tier noted). A decision with no source is labelled NET-NEW with a reason and a named test, never a fake citation. references/quality-gates.md has the schema; references/source-enrichment.md says what may be borrowed from where.

Procedure

Step 0: Check the current state

Read project/.claude/agents/, project/.claude/skills/, project/CLAUDE.md and, if present, project/.claude-plugin/plugin.json. Then pick exactly one path:

  • New build: no agents or skills, or empty directories → run Steps 1-6 in full.
  • Extend an existing harness: add an agent, a skill, or change the structure → run only the steps in the table below.
  • Operate / maintain: audit, repair or sync → go to Step 7.
Change Step 1 Step 2 Step 3 Step 4 Step 5 Step 6
Add an agent skip, reuse Step 0 findings decide only which mode, team and phase it joins required only if it needs a dedicated skill edit the orchestrator required
Add or change a skill skip skip skip required only if wiring changes required
Change structure or execution mode skip required affected agents only affected skills only required required

Then:

  1. Detect v1 artefacts. If an orchestrator or agent mentions TeamCreate, TeamDelete, team_name, SendMessage({to: "all"}) or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, it was built for v1 and will silently degrade to a single agent on the current runtime. Propose the v2 migration in references/execution-modes.md §5 before anything else.
  2. Detect the surface mismatch. If the orchestrator assumes Agent/Workflow tools but the user wants to run it in Claude chat or Cowork, add the single-context fallback (references/surfaces.md) before extending it.
  3. Compare the real agent and skill list with the CLAUDE.md change history and list every mismatch.
  4. Report the findings and the plan to the user and get confirmation.

Step 1: Analyse the domain and the work

  1. Extract the domain and the goal from the request.
  2. Split the work by kind: generate, verify, edit, analyse.
  3. Characterise the flow so Step 2 can pick a mode:
    • Can the item list be enumerated up front (N files, M viewpoints)?
    • Is there a verify-then-fix loop?
    • Does the result improve when agents argue with each other?
    • Must the same expert stay in conversation within one session?
  4. Find overlaps or conflicts with the agents and skills found in Step 0.
  5. Skim the codebase: stack, data model, main modules, existing tests and gates (pytest, ruff, mypy or their equivalents) — the orchestrator's QA must run the real gates, not invent new ones.
  6. Match the explanation level to the user. Do not use "assertion" or "JSON Schema" without a gloss for a non-coder.
  7. Which surface(s)? Ask if it is not obvious. A harness for a mortgage-broking operator who works in Cowork with CRM connectors is a different artefact from one for a developer in Claude Code, even for the same domain.

Step 2: Choose the execution mode and the team pattern

2-0. Delegation gate (first; the default is one agent)

Before choosing a mode or a pattern, answer six questions in one line each: (1) which units of work are independent, or in what order they hand off, (2) what splitting buys: specialisation, parallel speed or a separate context, (3) which paths or resources each worker writes, (4) whether every worker's tools and permissions cover its task on the target surface, (5) who synthesises and accepts the result, (6) how a partial, blocked or conflicting result is reported. references/team-patterns.md §6-1 says when an answer counts as unclear.

  • If any answer is missing or unclear, the outcome is single agent: the main context does the work, there is at most one agent file, and no Mode A or B and no parallel workers are used. Having an Agent or Workflow tool is not a reason to delegate. For an extension, "at most one agent file" counts the new role only: the new role then becomes a step of the main context or of an existing agent, not a new file.
  • Only when all six answers are concrete is the outcome delegate; then 2-1 to 2-3 and the Step 5 scale rule size the team. When extending a harness, run the gate again for the new role alone.
  • A dependent chain (pipeline, producer-reviewer, Mode B, a fresh-context judge, design then judge then build then QA) is concrete when each hand-off artefact is named; it delegates in sequence, and independence only decides whether calls run in parallel.
  • Rigor is a separate axis. The six answers never select a level, and a level never overrides them for the producing roles. A unit that the Rigor table runs gated adds a judge and a QA agent as an exception to the single-agent cap above ("at most one agent file"), which counts the producing roles only; their hand-off artefacts (the verdict, the report) are the named artefacts of question 1. (adapted from references/openrig/packages/daemon/specs/agents/shared/skills/pods/review-team/SKILL.md:24-25 (Apache-2.0))
  • When the user explicitly asks for a team or names the roles, build what was asked: write each unclear answer under ## Delegation gate as a stated risk and tell the user. The single-agent default applies when the user has not chosen.
  • A coordinator layer between the root and its workers needs one sentence in the orchestrator that names why the root cannot hold that work; without it, workers report to the root. The two-level cap in 2-2 stays.
  • Write the answers and the outcome in the orchestrator under ## Delegation gate (Step 5).

(adapted from references/meta_harness/.agents/skills/harness/references/agent-design-patterns.md:221 (Apache-2.0); adapted from references/meta_harness/.agents/skills/harness/SKILL.md:166 (Apache-2.0))

2-1. Execution mode (Claude Code)

Mode Primitives Fits
A. Workflow orchestration Workflow script: agent(), pipeline(), parallel(), phase(), schema item list, verification rule and repeat count expressible as code; schema-validated results; dozens of agent calls
B. Persistent agent collaboration Agent(name:), SendMessage, TaskCreate/TaskUpdate named experts that keep context across feedback, negotiation and joint editing
C. Sub-agent delegation one Agent call per task, background by default; independent calls parallel in one message, dependent calls one after another with the prior artefact path in the prompt no agent-to-agent talk needed; a result once

Decide in this order: (1) if the list, rule and loop can be coded, use A — code-defined control flow is reproducible; (2) else if agents must converse or remember, use B; (3) else C — a short pipeline of one-shot agents is still Mode C, run sequentially; (4) mix modes per phase and write **Execution mode:** above each phase. Write only the mode(s) you chose; an orchestrator is not required to carry all three.

Workflow needs the user's explicit opt-in. Invoking an orchestrator skill that declares a Workflow counts as opt-in. Keep the default agent count small; scale up only on "thorough", "exhaustive" or a stated token budget (+500k).

Details, concurrency caps, schemas, budgets and resume: references/execution-modes.md. Chat and Cowork fallbacks: references/surfaces.md.

2-2. Team pattern

Split the work by expertise, then pick from references/team-patterns.md: pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor, hierarchical delegation (two levels at most; one level of Workflow nesting).

When correctness matters, add verification patterns: adversarial verification (N adversarial checkers per finding; only majority-confirmed passes; refuted/uncertain never count as passes), judge panel, loop-until-dry, multi-axis search, omission reviewer. For harnesses that design before they build, add the FinHub pattern: an Authority List audited by a fresh-context judge (references/quality-gates.md §1-2), which is adversarial verification applied to the design itself.

2-3. Splitting agents

Split on expertise, parallelism, context load and reuse (references/team-patterns.md §6). Before creating any agent, check .claude/agents/ for one that already covers the role and extend it instead (§7).

Step 3: Write the agent definitions

Reusable experts are custom types in project/.claude/agents/{name}.md, invoked with subagent_type: "{name}" (Agent) or agentType: "{name}" (Workflow). One-off tasks that fit general-purpose, Explore or Plan get no file.

  • Frontmatter: name and description required; tools to restrict (drop Edit and Write for read-only reviewers; give Edit and Write to anything that fixes artefacts); model with the reason as a comment.
  • Body: role, working principles with their reasons, input/output rules, error handling, collaboration. Persistent agents (Mode B) add ## Communication rules; Workflow-only agents (Mode A) add ## Structured output; one-shot agents (Mode C) need neither — their ## Input and output rules name the artefact paths they read and write. Skills are wired in the body ("call /skill-name with the Skill tool"); there is no skills: frontmatter field.
  • Connectors: an agent that cannot do its job without an MCP server or connector gets a ## Required connectors section in its body, one server per line, written as the segment between mcp__ and the next __ in its tool names (mcp__crm__search → crm). Leave the section out when the agent needs none. In a harness that can send, write a record, publish or pay, only the sending worker lists the send, write or publish tools (mcp__<server>__*) in its tools: allowlist; every other worker gets a tools: allowlist without any mcp__ tool, because a worker with no tools: line inherits connector tools too and the Ask-first yes stops only the orchestrator (lint_harness.py warns connector-tools-unscoped). Step 5 copies these lines into the orchestrator's preflight table, so a missing connector stops the run before anyone is spawned instead of failing on the agent's first call. (adapted from references/openharness/src/openharness/coordinator/agent_definitions.py:956 (MIT))
  • QA agents get a type with all tools except mcp__ connector tools unless the agent is the sender (Explore cannot run scripts), compare shapes across boundaries rather than check existence, and run after every module, not once at the end (references/qa-agent-guide.md). Add the mutation spot-check from references/quality-gates.md §3 whenever the QA agent judges tests, count a mutant as killed only when scripts/mutant_gate.py prints STATE: CAUGHT for it (§3-4), and have it write a CANDIDATE: line under RESULT: so the verdict names the tree it judged (§3-7). Its definition file also says four things, because a QA agent follows only what its own file says: write cause: context-gap or cause: judgment-gap at the end of every defect row, under a heading written exactly ## Defects (rows are - defect: file:line ... or 1. file:line ..., observations are - observation: bullets, and no other line starts with the word Defect or Defects); copy the brief's Base line into a BASE: line; write one drift: row in its Gate table; and run scripts/finding_tags.py check on its report last (§3-8, qa-agent-guide.md §6 and §7-10; adapted from references/openrig/docs/reference/wave-sdlc.md:54-62 (Apache-2.0)).
  • A QA or judge agent file also says to copy the Rigor: line of its brief into a RIGOR: line (line 5 of a QA report after BASE:, line 4 of a verdict after CARRIED:), to choose and change no level or class, and to add no check because an earlier one found something (references/quality-gates.md section 3-10). The check that reads those lines is scripts/rigor_check.py. In a standard unit the judge runs one round and QA runs once per unit without mutation spot-checks unless the brief says the owner asked (§3-10 RS2-RS4). (adapted from references/openrig/docs/reference/product-journey-sdlc.md:177-178 (Apache-2.0))
  • A design-writing agent's file also tells it to give every refusal, prompt or required step its design adds a cost statement (the scenario, who causes it, what it costs everyone else, or one line saying the design adds none), and a judge agent's file carries the fixed cost statement row: UPHELD only when each addition the judge finds has all three, REJECTED with a cause tag when one is missing or generic, N/A when none (references/quality-gates.md section 3-11). The row adds no round, gate or level. (adapted from references/openrig/CONTRIBUTING.md:29-31 (Apache-2.0))
  • An agent that makes an outside effect (a send, a record write, a publication or a payment; references/state-ledger.md section 3a) says in its file, on a line of its own that starts Sending worker: (the marker lint_harness.py reads), that it makes only the calls on the approved list its brief names, each once and with exactly the listed arguments, that it never asks the user for approval or decides it, and that with no list, or before a call that is not on it, it makes no call and reports STATUS: blocked (Ask-first block, references/orchestrator-template.md).
  • Library skills: before writing an agent's own skill (Step 4), look for an existing skill that already does its job and assign it. The library is every skill the host lists (the available-skills list; ListSkills or SearchSkills where the session has them) plus .claude/skills/. For each agent: match its role and task against the skill descriptions, take the narrowest domain match, assign at most three, and wire each in the agent's body ("call /skill-name with the Skill tool"). Add Skill to its tools: allowlist if it has one, because an allowlist that omits it hides every skill. Use only a name the listing shows, never one from memory. Never give a skill that sends, writes a record, publishes or pays to a worker that is not the sending worker. Record the result as a table, agent | assigned skill | why, in the Step 5 report; an agent with no good match is marked none found and Step 4 writes its skill. A chosen library skill is reused, not copied. Where no skill listing is readable, say so in the report and write the skills instead of guessing.
  • Model per agent from references/model-selection-guide.md: fable only for the layer that plans and runs long; opus for design, generation, judging; sonnet by default.

Step 4: Write the skills

Each agent's method goes in project/.claude/skills/{name}/SKILL.md (references/skill-writing-guide.md).

  1. Check .claude/skills/ for an existing skill that covers it; link or extend rather than duplicate (§9).
  2. Layout: SKILL.md (required, under 500 lines) + optional scripts/, references/, assets/.
  3. description states what the skill does and the concrete situations that must trigger it. Follow-up phrasings ("re-run", "update", "redo only the X part") are required on the orchestrator and on any skill users will invoke directly; a leaf skill only ever called by an agent needs none. Name near-miss cases it must not take.
  4. Body: explain the reason behind each rule, generalise to principles, imperative register, move detail to references/ and say when to read each file.
  5. Wire skills to agents: Skill-tool call for shared workflows, inline for short agent-private procedures, Read of a reference file for long conditional material.
  6. A skill that holds rules which change (lender policy, tax rates and thresholds, regulator guidance) opts in to provenance: set last_verified, verified_source and review_days in its frontmatter (references/skill-writing-guide.md section 10); lender-policy and rate claims rest on tier T1 sources. A skill about method alone leaves them out. Top-level provenance keys are expected to be ignored by Claude Code and plugin loaders, not checked here; which frontmatter keys a chat or Cowork upload accepts is UNVERIFIED, so test an upload before relying on it. (adapted from references/openrig/packages/daemon/src/domain/skill-audit.ts:98-111 (Apache-2.0))

Step 5: Integrate and order the run

The orchestrator is itself a skill. Use the matching template in references/orchestrator-template.md (A, B, C or mixed) and the scripts in references/workflow-recipes.md. When extending, edit the existing orchestrator; never create a second one for the same domain.

Every orchestrator contains:

  • Execution mode and target surface at the top (per phase if mixed). If chat or Cowork is a target, a ## Single-context fallback section (references/surfaces.md).
  • Step 0 context check: no _workspace/ → fresh run; _workspace/ + partial request → re-run only that agent/phase (pass prior output paths); _workspace/ + new input → move it to _workspace_{timestamp}/ and start fresh; Workflow mode → resumeFromRunId when run_meta.json has one, except for a once stage that did not return a result (references/state-ledger.md section 3a, rule O7). A run of two or more phases that pass files to each other also keeps a state ledger, so a request to continue after a context reset or in a new session starts at the first unfinished phase, not the first one; a named partial re-run still wins, and the script is copied into the harness when the plugin is not installed there (references/state-ledger.md, script scripts/state_ledger.py). A phase that sends, publishes, uploads or writes a record outside the workspace is marked once in the optional replay column of that table, so a resume stops and asks about a half-done one instead of running it again (references/state-ledger.md section 3a). (adapted from references/openharness/src/openharness/autopilot/service.py:405 (MIT); adapted from references/meta_harness/.agents/skills/harness/SKILL.md:158 (Apache-2.0); adapted from references/openrig/docs/reference/rig-spec.md:519 (Apache-2.0))
  • Connector preflight (only when an agent has ## Required connectors): Step 0 ends with the preflight item from Template A Step 0 in references/orchestrator-template.md, holding one agent → connector row per declared line. On Claude Code a missing connector stops the run before any spawn; on chat and Cowork the orchestrator warns and asks instead, because connector listings there are deferred and an absent name is not proof (references/surfaces.md §4).
  • Data hand-off: structured return (schema) in A; return message in C; SendMessage and shared tasks in B; files for anything large or auditable, as _workspace/{phase}_{agent}_{artifact}.{ext}. Freeze artefacts at phase boundaries in B (template B Step 4).
  • Delegation contract (only when the orchestrator spawns or messages a worker, so never in a single-context fallback): paste the Delegation block from references/orchestrator-template.md at the step that launches workers and fill one five-line brief per worker role. The block fixes what a brief must contain, the STATUS / EVIDENCE / BLOCKER report a worker ends with, and the check the orchestrator runs before it uses a report (re-ask once, then mark the result unverified; a once phase is never re-asked). It is prompt quality plus a check, not a guarantee.
  • Delegation gate (every orchestrator): a ## Delegation gate section with the six answers and the outcome from Step 2-0, written before anything is spawned; a single-agent outcome spawns nothing. Template C in references/orchestrator-template.md carries the block and an optional notes block for workers; an A or B orchestrator copies the same block.
  • Rigor (every orchestrator that has a Quality gates bullet below): a ## Rigor section with the table of references/quality-gates.md section 3-10 and the block in references/orchestrator-template.md. Ask the owner, per kind of unit, whether it is an audited decision (money, eligibility, compliance and client-facing text) or other, and write the answer: an agent never classifies a unit as other on its own. Audited decisions are gated, preselected; other units are light unless the owner assigns them standard or gated (software is other; offer standard for a normal expert build and write it only on the owner's answer). When it is unclear whether an output is an audited decision, treat it as one. A classification or a downgrade that lowers rigor needs the user's approval; an agent never decides it. Ask once who the owner is and write that name as the OWNERS line of the copied waiver_ledger.py, and copy rigor_check.py with it because it imports waiver_ledger.py. A role name, an idle seat and an earlier finding assign no gate. Show the table in the report of Step 6 item 7. A downgrade of one item, or a later lowering of a row, is a WAIVERS.md row with the owner's words and never a table edit alone; a harness that never downgrades passes - for the ledger. (adapted from references/openrig/packages/daemon/specs/agents/shared/skills/pods/orchestration-team/SKILL.md:17-19 and :149-152 (Apache-2.0))
  • Error policy: one retry then proceed and record the gap, except that a once phase is never retried automatically: it stops and asks (references/state-ledger.md section 3a, rule O7); a verdict whose candidate_id.py check exits 3 gets its own row in the error table (treated as not given, the judging phase re-run on the current tree when the user agrees); never retry quota, auth or permission failures — open the partial artefacts, record what is missing, report; the orchestrator fills a gap only with facts it verified itself, never with a guessed judgement; in Mode A, .filter(Boolean) after every parallel()/pipeline() and log() the dropped count.
  • Ask before an outside effect (every orchestrator of a harness that can send, write a record, publish or pay, a single agent included): paste the Ask-first block of references/orchestrator-template.md before the first phase that does it, and into any ## Single-context fallback. Before each phase that makes an outside call, the orchestrator shows that phase's calls with their exact arguments and stops; it makes them only after the user's explicit yes to that list, each once, and treats no answer, a no, a change and a run with nobody to answer as not sent. One list and one yes per sending phase; a list that names calls of two phases approves neither. Within a phase the batch is shown in full and approved once. A host permission prompt and a passed audit are not the yes. (adapted from references/paperclip/skills/paperclip/SKILL.md:474-479 (MIT, Paperclip AI), idea only; adapted from references/openrig/docs/reference/getting-started.md:663-667 (Apache-2.0)) The skill that carries the block also sets disable-model-invocation: true in its frontmatter, so a model never starts it unasked; lint_harness.py warns send-implicit when the key is missing (adapted from references/repository_harness/tests/installer/assert-agent-authority-contract.sh:90 (MIT), holder Hoang Nguyen per references/repository_harness/LICENSE:1-3, idea only). On chat and Cowork the key may be ignored: unverified.
  • Run mode (every orchestrator): paste the Run mode block of references/orchestrator-template.md after the Delegation gate and mark the phases that only add checking [full-only], so the user can say "run it light", "standard" or "full" and the orchestrator skips them and starts its workers on cheap models. Light is a cost switch; standard and full raise one run; none of them lowers a unit the Rigor table runs gated. The cost fields it uses are model on the Agent call, which beats the agent file's model:, and maxTurns and effort in agent frontmatter (checked against the Claude Code docs, 2026-11-05).
  • Scale: 2-3 persistent agents for small jobs, 3-5 for medium, supervisor + 3-5 for large; Workflow calls from a handful to hundreds, capped by budget.remaining() when a budget is set.
  • Quality gates when the harness builds software or produces audited decisions — money, eligibility, compliance and client-facing text: credit or compliance assessments, client-facing advice and emails, legal or financial figures. A gap email is client-facing text and so is one; so is a servicing verdict. Which units run the chain below is the Rigor bullet's decision. Then: Authority List → fresh-context judge (max 3 rounds, one in a standard unit, then escalate with both positions) whose verdict also rules the fixed cost statement row (§3-11) → build one slice → boundary QA with RESULT: PASS|FAIL first line, the repo's real gates re-run, mutation spot-checks on a scratch copy, one builder retry → final report whose first line is Done / partly done / blocked (references/quality-gates.md). Each QA report and judge verdict names the candidate it judged, and the orchestrator checks that line before it commits or ships (scripts/candidate_id.py, §3-7; unverified where no shell runs).
  • CLAUDE.md pointer: record only the block below, between its two marker lines, with the change history after the end marker. Agent lists, directory trees and run rules stay out of it.
<!-- finhub-harness:begin {orchestrator-skill-name} -->
## Harness: {domain}

**Goal:** {one line}

**Trigger:** For {domain} work, use the `{orchestrator-skill-name}` skill. Simple questions may be answered directly.
<!-- finhub-harness:end {orchestrator-skill-name} -->

**Change history:**
| Date | Change | Target | Reason |
| --- | --- | --- | --- |
| {YYYY-MM-DD} | Initial build with finhub-harness | all | - |

On an initial build the Reason column stays -; later rows carry the feedback or defect that caused the change.

The block belongs to this skill; everything else in CLAUDE.md belongs to the user. Each marker stands alone on its line, and the name in it is the orchestrator skill's kebab-case name, never translated, so several harnesses can share one file. Before writing anything, list the marker lines from the file itself, with grep -n 'finhub-harness:' CLAUDE.md or the Read tool, never from the copy of CLAUDE.md loaded at session start, which may not show HTML comment lines. Count only a line that holds nothing but a marker; a byte-order mark at the very start of the file does not count as text. Then take the first case that fits this orchestrator's name:

  1. No CLAUDE.md: create it with the block and the history table.
  2. No marker line for this name: back up, then add a blank line, the block and the history table at the end of the file. If an unmarked ## Harness: {domain} section from an earlier build is already there, add no block: edit that section in place as before, put the history row in its table, and say in the report that the pointer has no markers, and that wrapping its heading, Goal and Trigger lines in the two markers, with the history kept below the end marker, lets a later run replace it in place.
  3. One begin line above one end line, with no other harness's marker between them: start the new block from the lines now between the markers and change only what this run changes, so an edit made there since the last build (by finhub-harness-evolve or by hand) is kept. If the result matches those lines, write nothing. Otherwise back up, replace only those lines, and put the history row in the table below the block. Every byte above the begin line and below the end line stays as it was.
  4. Anything else (a second begin or end line, an end line above its begin line, a marker without its partner, another harness's marker inside the block, or a CLAUDE.md you cannot read): write nothing to CLAUDE.md. Show the user the marker lines with their line numbers and ask them to fix the file by hand. Never guess which pair is meant.

A renamed orchestrator: when the file holds a valid pair whose name matches no orchestrator skill of this harness, that block may be the old one of a harness that was renamed. Leave it exactly as it is, name it in the report together with the new block, and ask the user whether to remove it; never delete or rewrite a block under another name unasked. The lint does not flag it. (adapted from references/openrig/packages/daemon/src/domain/managed-blocks.ts:8 and :36 (Apache-2.0), idea only)

Back up before the first write, as the backup gate of finhub-harness-evolve Phase 3 does: cp -p CLAUDE.md CLAUDE.md.bak && cmp CLAUDE.md CLAUDE.md.bak, using the first unused CLAUDE.md.bak.2, CLAUDE.md.bak.3 and so on when CLAUDE.md.bak exists, and writing nothing if the copy fails or cmp prints anything. Keep the block, both marker lines included, to 1600 bytes or fewer: it is read at the start of every session, and the lint warns (pointer-budget) when it is longer. The change history below the block is never counted, never trimmed and never moved into it. On chat and Cowork, whether CLAUDE.md can be read or edited in place and whether the lint can run are unverified: give the user the block and the history row to paste, and check the four cases by hand. (adapted from references/repository_harness/scripts/install-harness.sh:330-344 and :369 (MIT, Hoang Nguyen); size budget adapted from references/repository_harness/tests/installer/assert-agent-authority-contract.sh:35 (MIT, Hoang Nguyen))

  • Follow-up triggers in the orchestrator description: "re-run", "update", "fix", "redo only {part}", "improve the previous result", plus the domain's everyday verbs.

Step 6: Verify and test

Follow references/skill-testing-guide.md.

  1. Files and references: run python3 scripts/lint_harness.py project/.claude (path relative to this skill's directory) and fix every ERROR line; fix each WARN line or say in the report why it stays. The lint checks frontmatter, name grammar and that a skill's directory matches its name, non-empty descriptions, that every subagent_type/agentType names an agent file or a built-in type, that ## Required connectors lines and the preflight table agree, that no agent or skill file which calls Agent(, agent(, Task( or SendMessage, or names subagent_type or agentType, contains a lazy-delegation phrase (WARN lazy-delegation), and v1 artefacts, and that local markdown links, a skill's single-level references/<file>.<ext> mentions and agent and skill names (broken-link, bundled-ref, duplicate-name) are not dead or duplicated, and that a skill which sets any of last_verified, verified_source or review_days has a real calendar date that is not in the future, a source that is not the skill itself and holds a URL or a year, and a window the date has not outrun (WARN only, each with a fix: verified-date, verified-future, verified-bare, verified-window, verified-stale, verified-orphan; a skill that sets none of the three is not checked), and that the CLAUDE.md beside DIR (in DIR's parent when DIR is .claude) has, per orchestrator name, one begin marker line above one end marker line with no other harness's marker between them (pointer-marker, ERROR) and a block of at most 1600 bytes (pointer-budget, WARN; a CLAUDE.md with no marker line is not checked); for a mention of a file you mean to create later, write it with a path prefix (<skill>/references/x.md), inside a code fence or as an angle-bracket placeholder rather than waiving the ERROR; it exits 1 on any error. Where it cannot run (chat without code execution), check the same list by hand. The lint does not check that nothing was written to .claude/commands/ or that every Authority List citation opens to a line that supports the claim; check those yourself. Where the project pins references/ submodules, the cite check, run from the project root as python3 <this skill's directory>/scripts/cite_check.py <design or port map>, confirms that each references/<sub>/<path>:<line> cite exists at the pinned commit and is in range, not that it supports the claim; a generated judge agent file says to run it before the first claim and names where it is: this skill's scripts/ when the plugin is installed, or a copy in the harness's own scripts/ (references/quality-gates.md §1-4). (adapted from references/crewai/lib/crewai/src/crewai/skills/validation.py:43 (MIT)) (provenance rules adapted from references/openrig/packages/daemon/src/domain/skill-audit.ts:98-136 (Apache-2.0))
  2. Per mode: A — meta is a pure literal, no Date.now()/Math.random(), parallel() only where a barrier is needed, .filter(Boolean) present, phase() titles match meta.phases; B — message routes, task dependencies, agent count; C — inputs chain to outputs, parallel calls batched in one message; mixed — mode written per phase and hand-offs unbroken. Chat/Cowork targets — the single-context fallback covers every phase. Delegation, wherever workers are spawned or messaged — grep -l 'STATUS:' project/.claude/skills/*/SKILL.md lists the orchestrator. Where the lint cannot run, grep -nEi 'based on (your|the) (findings|research)|as (we )?discussed' project/.claude/skills/*/SKILL.md project/.claude/agents/*.md is a stricter manual fallback (no word boundaries, every file, blind to a phrase wrapped over two lines): judge each hit by hand, because a research-and-write skill may legitimately keep one.
  3. Skill runs: 2-3 realistic prompts per skill, with-skill vs baseline in parallel, qualitative plus assertion-based grading; fix by principle, not per example; repeat until gains flatten; move repeated helper code into scripts/.
  4. Trigger check: 10 should-trigger prompts in varied register and 10 near-miss should-not-trigger prompts; check for collisions with existing skills' descriptions.
  5. Dry run: phase order, hand-off paths, input/output fit, error branches executable.
  6. Record one happy-path and at least one error-path scenario under ## Test scenarios in the orchestrator. A harness with the Ask-first block also records its three cases (no answer, a no, a yes), run against a stub connector that records its calls.
  7. Rigor table: put the harness's ## Rigor table in the report you give the owner, with the class and the level of each scope and who assigned it. It is the owner's answer from build time and nothing compares it with anything (references/quality-gates.md section 3-10).

Step 7: Operate, maintain and improve

A harness is not a one-off artefact. Retrospectives and feedback belong to finhub-harness-evolve ("harness retrospective", "evolve the harness", "fold this feedback in"). This skill handles operation:

  1. Status check: diff .claude/agents/, .claude/skills/ and the orchestrator; list mismatches and report.
  2. Incremental change: one item at a time, verify immediately.
  3. Change history: date, change, target, reason in CLAUDE.md.
  4. Verify the change: structure always; trigger test if a description changed; run test and dry run if the change is large; final CLAUDE.md-vs-files check.
  5. Audit: when the user asks whether a harness's rules have real checks, follow references/audit-guide.md: one row per rule or check, one finding each (enforced, partially enforced, unenforced rule, check lacking authority, unknown), evidence classes never promoted, and the audit reads and reports without editing.

Suggest finhub-harness-evolve when the same feedback recurs, an agent fails twice for the same cause, a QA report or judge verdict rejects for the same reason twice, or the user keeps doing the orchestrator's job by hand.

Enriching from other harness repos

When the user wants a pattern from another harness ("borrow the judge panel from repo Y", "adopt how Z sandboxes code"), do not copy. Pin the repo as a reference submodule, run the port-map procedure, then adopt the pattern through an Authority List row with its licence tier. references/source-enrichment.md has the procedure, the pinned repos and their tiers.

Deliverable checklist

  • [ ] Every reusable custom type has a file in project/.claude/agents/; one-offs on built-in types have none.
  • [ ] Every needed SKILL.md and reference exists under project/.claude/skills/.
  • [ ] Every agent has an assigned library skill or a none found row in the agent | skill | why table; every assigned name appears in the host's skill listing and in the agent's body, and no sending skill sits on a non-sending worker.
  • [ ] One orchestrator skill with data hand-off, error policy, test scenarios and a declared target surface; a single-context fallback if chat or Cowork is a target.
  • [ ] Execution mode written (per phase if mixed); no v1 artefacts.
  • [ ] scripts/lint_harness.py exits 0 on project/.claude, and every WARN line is fixed or explained.
  • [ ] model: chosen per agent from the task, with the reason as a comment; no blanket top-model setting.
  • [ ] Workflow scripts: .filter(Boolean) present, meta literal, parallel() only for real barriers.
  • [ ] Nothing written to .claude/commands/.
  • [ ] Existing agents and skills checked for overlap before creating new ones; no name or role collision.
  • [ ] Artefacts written in the user's language (or the existing harness's language).
  • [ ] Every skill description names its trigger situations and follow-up phrasings.
  • [ ] Every SKILL.md under 500 lines; detail moved to references/.
  • [ ] Run with 2-3 realistic prompts; triggers validated with should and should-not cases.
  • [ ] CLAUDE.md holds only the trigger pointer, inside its one pair of finhub-harness marker lines (1600 bytes or fewer), and the change history below it; the user's own text outside the block is unchanged.
  • [ ] Orchestrator Step 0 distinguishes first run, follow-up and partial re-run (and resumeFromRunId for Workflow mode).
  • [ ] Every ## Required connectors line in an agent file has a row in the orchestrator's connector preflight table, and every row has a matching agent line.
  • [ ] Every worker brief has Goal, Inputs, Scope, Expected output and Report; every worker report ends in STATUS / EVIDENCE / BLOCKER form; the orchestrator re-asks once and then marks the result unverified (a once phase is never re-asked).
  • [ ] A harness that can send, write a record, publish or pay has the Ask-first block before its first such phase and in its single-context fallback, and its test scenarios hold the no-answer, no and yes cases.
  • [ ] Every section that launches writers in parallel has a ## Writers table with one ownership label per writer (references/write-safety.md); python3 scripts/check_writers.py --require on that orchestrator exits 0 (path relative to this skill's directory); a harness with one writer needs no table and is not run with --require.
  • [ ] Borrowed patterns cited in an Authority List with licence tier; net-new decisions labelled with reason and test.
  • [ ] If the harness builds software: QA runs the repo's real gates after every slice and reports RESULT: first, then CANDIDATE:; the orchestrator runs candidate_id.py check on that report before it commits. Each mutant it ran ends in STATE: CAUGHT or is redone.

References

  • Execution modes and v1→v2 migration: references/execution-modes.md
  • Surfaces (Code / chat / Cowork) and the single-context fallback: references/surfaces.md
  • Model selection: references/model-selection-guide.md
  • Team patterns and agent definitions: references/team-patterns.md
  • Worked team examples: references/team-examples.md
  • Workflow scripts and pitfalls: references/workflow-recipes.md
  • Orchestrator templates: references/orchestrator-template.md
  • State ledger, rebuild and resume across context resets: references/state-ledger.md
  • Run-once phases: a resume stops and asks about a half-done send, publish or record write (the ledger reads files only; an idempotency key accepted by the connector is the real fix): references/state-ledger.md section 3a
  • Asking before an outside effect (the exact calls shown, an explicit yes, each call once, no answer is no): references/orchestrator-template.md, Ask-first block
  • Bulk job with one phase repeated over N items: a per-row tracker so a re-run resumes at the item, not the phase (scripts/unit_tracker.py, rules U1-U8): references/unit-tracker.md
  • The same work over many items, pilot first, then fan out (rules P1-P6): references/team-patterns.md section 1-2a
  • Skill writing: references/skill-writing-guide.md
  • Skill testing: references/skill-testing-guide.md
  • A harness that tries changes and keeps the winners (the seven-item contract named before the first candidate, a read-only evaluation surface, a ledger, gates before the score, and a four-scenario A/B for team layouts): references/experiment-profile.md
  • QA agents: references/qa-agent-guide.md
  • Authority List, adversarial audit, mutation-tested QA, honest reporting: references/quality-gates.md
  • A mutant counts as caught only when the test written for it fails at the assertion written for it, between a passing run before and a passing run after: references/quality-gates.md §3-4 (rules M1-M8) and scripts/mutant_gate.py (adapted from references/openrig/packages/test-system/ci/result.mjs:33-34 (Apache-2.0))
  • Naming the tree a verdict judged, and refusing a stale verdict: references/quality-gates.md §3-7 and scripts/candidate_id.py (adapted from references/openrig/scripts/gate-lane-consume.mjs:23-25 (Apache-2.0))
  • Checking that each references/<sub>/<path>:<line> cite exists at the pinned commit and is in range: references/quality-gates.md §1-4 and scripts/cite_check.py (adapted from references/repository_harness (MIT); the source lines are named in §1-4)
  • Parallel writers, the ownership ladder and honest labels: references/write-safety.md (adapted from references/meta_harness/.agents/skills/harness/SKILL.md:133 (Apache-2.0))
  • Updating installed harness files from a new version without overwriting edits (plan against a stored baseline, stage conflicts, edit nothing; rules R1-R6): references/safe-update.md and scripts/safe_update.py (adapted from references/repository_harness/crates/harness/src/application/service.rs:516 (MIT, Hoang Nguyen), idea only)
  • Borrowing from other harness repos under licence rules: references/source-enrichment.md

04 同仓库更多 Skills