herder
Runs coding work as a durable, verified Herder run - an approved goal with checks, agent steps in isolated git worktrees, serial integration, runtime verification, and delivery after user confirmation. Use after /herder or /herder resume, or when a Herder run is active and you need to plan, orchestrate, verify, or deliver it.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- herder
- description
- Runs coding work as a durable, verified Herder run - an approved goal with checks, agent steps in isolated git worktrees, serial integration, runtime verification, and delivery after user confirmation. Use after /herder or /herder resume, or when a Herder run is active and you need to plan, orchestrate, verify, or deliver it.
- disable-model-invocation
- true
03 SKILL.md 正文
Herder
Herder runs a coding goal to delivery. Work happens in agent steps, each in a disposable git worktree; writing steps become commits that are integrated one task at a time on a hidden integration line. Every result is journaled, so a run survives crashes, stops, and new sessions without repeating finished work. Nothing touches the user's checkout or branches until the user confirms delivery.
Success is computed by the runtime from real check results and its own verification. Agent summaries, plan checkboxes, and commit messages are claims, not evidence. Never report a task as done because an agent said so; report what the checks and the runtime's verdict say.
Run lifecycle
- Start. The user runs
/herder <goal>, or you callherder_run { action: "start", goal }when the user asked for a run (as the audits do); the tool result then carries these instructions. Herder creates the run and a draftgoal.md; the command message or tool result gives you its path. Run files live in the run directory under the repository's git directory, never in the working tree. A run started from a/herder-improveor/herder-simplifyaudit implements the findings the user picked: one acceptance criterion and one task per finding, the unpicked findings out of scope. The audit already did the clarifying. - Clarify. Read the relevant code first, then ask at most 5 questions, only ones whose answers change the work. For a run you started with
herder_run, ask only what is still open: the conversation or audit that led to it usually answered them. Give each a recommended answer so the user can reply "yes". Skip questions you can answer from the code. - Write
goal.mdin the format below. Prefer acceptance criteria that a check can decide. - Approve. Call
herder_run { action: "approve_goal" }. Herder validates the file and asks the user to confirm. If validation fails, fix the file and call it again. After approval the goal is frozen; to change it, tell the user (a new goal requires aborting the run withherder_run { action: "abort" }after the user confirms, then starting a new run). - Write
plan.mdnext togoal.md: tasks with IDs mapped to criteria. - Orchestrate (see the decision table):
- Simple runs:
herder_step(oneagent()step with the same options) thenherder_integratewith its commit (refused for agate_failedstep). Inspect each result before the next call. - Larger runs: write a script, check it with
herder_workflow { mode: "validate", script | scriptPath }, then launch it withherder_workflow { mode: "run", script | scriptPath, args }. It runs in the background and returns a launch number; a follow-up message reports the script's return value and how many steps were reused, changed, or new. Do not poll; continue when the follow-up arrives.herder_workflow { mode: "stop" }stops it.
- Simple runs:
- Check and verify.
herder_checkruns checks at the integration head (or a given commit).herder_verifyruns every check, runs the fresh-context verifier when the run is non-trivial, and computes the verdict (met,not_met, orblocked). Onnot_met, read the gaps it appended toplan.md(a## Convergence Nsection), plan a fix, and launch again. Onblocked, take the quoted criterion to the user. - Deliver.
herder_deliverrequires ametverdict at the current head and the user's confirmation; under a standing authorization, leave the run parked instead (see Standing approval). Modes:series(default): the run's commits, one per integrated task, fast-forwarded onto the user's branch (the checkout must be clean and on that branch).branch: a newherder/<runId>branch; the checkout is untouched.squash: one commit on the user's branch, titled from the goal.uncommitted: the changes applied to the clean working tree, unstaged.curate: truefirst asks a curator to regroup the series into logical commits; it is kept only if the final tree is identical.
herder_run { action: "status" } shows the run at any time, and herder_run { action: "abort" } stops and abandons the run after the user confirms (use it only when the user asks to abandon the run or replace a frozen goal; to stop a running launch without abandoning the run, use herder_workflow { mode: "stop" }). The user also has /herder status, /herder deliver, /herder abort, and /herder clean.
Resuming
After a crash, a stop, or in a new session, the user runs /herder resume, which re-primes you with the goal, plan, progress, and last results. Then:
- Relaunch the interrupted script with
herder_workflow { mode: "run", scriptPath, args, resume: <n> }, where<n>is the interrupted launch and its script isscripts/<n>.jsin the run directory. Use the sameargs. You may edit a copy of the script first; steps whose id, prompt, options, and base are unchanged return their recorded results instantly, and their integrations are reused instead of applied twice. - Steps that failed or were interrupted run again. Changed steps run live.
fresh: trueon anagent()call deliberately resamples a step that would otherwise be reused.- Without
resume, a launch starts from the current integration head (use this for follow-up work, such as fixes after verification).
Standing approval
When a tool result or Herder message says a standing authorization is in effect (self-driving mode), the user is away and approved the work in advance. Do not ask the user anything:
- Skip the Clarify questions. Write the assumptions you made into
goal.md(Constraints or Out of scope), or record each withherder_run { action: "record_decision", question, answer }, the answer marked as your assumption. approve_goalandherder_pick_findingsanswer without dialogs, andabortneeds no confirmation for a run whose goal it approved or that started after it was granted. Nothing waits for the user:abortrefuses any other run, andherder_deliverrefuses.- Never call
herder_deliver. Onceherder_verifyreportsmet, leave the run parked and report it: the user delivers it later with/herder deliver <runId>, and a new run may start meanwhile. - On
blocked, or when a decision only the user can make comes up, do not wait for them: report the question, leave the run, and move on.
Choosing orchestration
Start with the cheapest shape that fits; escalate only when it fails or the work clearly needs more.
| Situation | Shape | How |
|---|---|---|
| Trivial change (a few lines, one file) | One writing step + checks | herder_step with gate, then herder_integrate |
| Normal task | One writer + gates, optional probe (a tester adds tests from the contract), capped fix loop | sequential.js |
| Several independent tasks with disjoint files | Partitioned fan-out with explicit file ownership, serial integration, resolver on conflict | disjoint.js |
| Several tasks that touch the same files | Sequential tasks, each integrated before the next starts | sequential.js per task, or a script that loops over tasks |
| Uncertain approach, worth trying several | Generate and filter, then a tournament judge, in separate worktrees | explore.js |
| Research before planning | One read-only explorer step |
herder_step { role: "explorer" } |
Never run parallel writers on overlapping files. If ownership is unclear, run the tasks sequentially.
goal.md
# Goal: <one line>
## Intent
<≤5 lines: why and for whom>
## Acceptance criteria
- AC-1: WHEN <trigger> THE SYSTEM SHALL <observable outcome>. verify: check:unit-tests
- AC-2: <criterion>. verify: judge — rubric: "<binary statement the verifier can confirm>"
## Checks
| id | command | timeout | integrate |
| --- | --- | --- | --- |
| unit-tests | npm ci && npm test | 10m | yes |
| typecheck | npm ci && npm run typecheck | 5m | yes |
## Constraints
- <must not change …>
## Out of scope
- <…>
## Budget
max_agents: 40
max_fix_attempts: 3
Headings: the # Goal: title and the section names above are the only headings; any other heading, at any level and outside code fences and HTML comments, fails validation, so structure a section with lists or plain text.
Acceptance criteria
- Number them
AC-1,AC-2, …. Write each as one observable outcome in EARS style:WHEN <trigger> THE SYSTEM SHALL <outcome>,WHILE <state> …,IF <condition> THEN …, or a plainTHE SYSTEM SHALL …. - Map every criterion to evidence:
verify: check:<id>(one or more check ids, comma separated) orverify: judge — rubric: "<statement>". Prefer checks: they are deterministic and cheap. Add a test to the plan when no existing check covers a criterion, then map the criterion to the check that runs it. - A judge rubric is the last resort: first try to make the criterion decidable by a command (a focused test, a type-level test, a
! git grep -q <pattern>check). A rubric is a binary statement a fresh verifier can confirm by reading code, such as"Every public function in src/api.ts validates its input before use". Avoid "good", "clean", "robust". The rubric text must not itself containverify:. - Keep criteria about outcomes, not implementation steps. At least one criterion is required.
Checks
id: lowercase letters, digits, and hyphens (/^[a-z0-9][a-z0-9-]*$/), unique. Everycheck:<id>in the criteria must exist here.command: a shell command; exit code 0 means pass. Checks and agents run in fresh worktrees of a commit, without ignored files such as node_modules: the command runs at the top level of a fresh checkout of the commit being checked, with no installed dependencies, virtualenvs, build output, or local config. Make each check self-contained, e.g.npm ci && npm testoruv run pytest. Keep it non-interactive and deterministic, and prefer fast, scoped commands when the full suite is slow.timeout:30s,10m,1h.integrate:yesruns the check before each integration advances the head (default integration checks); keep these fast.noruns it only for gates you name and at verification.- Every check runs at verification, whatever its
integratevalue.
Budget: max_agents caps live step agent starts for the run (agent() calls and herder_step; the verifier and curator do not count, so a spent budget never blocks verification or delivery); max_fix_attempts is the fix-loop cap your scripts should honor (default 3).
plan.md
Free-form Markdown that you own; rewrite it as you learn. Task lines must match exactly:
- [ ] T1 (AC-1) Add the parser for the new config section
- [ ] T2 (AC-2, AC-3) Wire the parser into startup and report errors
Give each task its file ownership and dependencies in prose under it when you plan a fan-out. Task status comes from the journal and is rendered in progress.md; do not tick checkboxes as progress, and never edit progress.md or the journal. The runtime appends ## Convergence N sections after verification; leave them in place.
Scripts
A script is the body of an async function: top-level await and return work. There is no import, export, or require, and no file system, network, timers, eval, or Function. Date.now(), Math.random(), and new Date() without arguments throw, because replay must be deterministic. Binary buffers (ArrayBuffer, typed arrays, DataView, Atomics, WebAssembly), Intl, and Temporal are not available either: they hold memory outside the script's heap limit. Pass inputs through args; the return value must be JSON-serializable and should be a compact summary.
Globals:
agent(prompt, opts)runs one step and resolves to a result. Options (unknown keys throw):id— stable step id. Always set it, derived from the task and the attempt number (impl-T1,fix-T1-2,probe-T1), so a relaunch reuses unchanged steps. Never give one id to calls with different prompts or options in the same launch; that throws.task— the plan task id ("T1"), for progress per task.role—worker(default, writes),tester(writes tests only),verifier,explorer(read-only),resolver,curator(write).write— override the role's default.base— commit to start from (default: the launch's integration head). Use a previous step'scommitto build on it.gate— check id or ids fromgoal.md, run in the step's worktree afterwards.schema— a JSON Schema; the agent must return matching data inresult.data.label,phase— display only.fresh: true— resample instead of reusing.timeoutMs,stallMs— per-step limits.effort— thinking level for this step:off,minimal,low,medium,high,xhigh, ormax.
integrate(source, { message, task?, checks? })merges a step result (or a commit SHA) onto the integration head as one commit withmessage, runs the integration checks (default: those markedintegrate: yes), and advances the head only if they pass. It throws for agate_failedstep, given as a result or as its commit; integrate theokfix step built on that commit instead.parallel([() => …, …])runs thunks concurrently and waits for all; a thunk whose own code throws yieldsnull.pipeline(items, stage1, stage2, …)runs each item through the stages; a stage receives(previous, item, index)and the first stage'spreviousis the item. Items do not wait for each other between stages. A stage whose own code throws makes that itemnull.phase(title)andlog(message)report progress.argsholds the launch arguments.
Results are values. Invalid options (including a reused id), cap breaches, and host or runtime rejections throw, and they propagate out of parallel and pipeline; only ordinary errors thrown by your own thunk or stage code become null.
- Step result:
{ status, key, text, data, commit, checks, error, reused }, withstatusone of:ok— finished; for writers,commitholds the change and any gates passed.no_changes— a writer changed nothing.gate_failed— gates failed;commitstill holds the change, andchecksholds each check's{ id, passed, exitCode, timedOut, tail }.failed— the agent failed after the runtime's own retries;erroris{ class, message }.classusage_limitmeans stop and tell the user.stopped— the launch was stopped.
- Integration result:
{ status, head, conflicts, checks }withstatusone ofintegrated(the newhead),conflict(the conflicting paths; the head did not move), orchecks_failed(the head did not move).
The runtime caps concurrency, agents per launch and per run, items per call, and step wall-clock and stall time; caps are enforced, not advisory.
Templates
Three templates live in this extension at ../../templates/<name>.js relative to this skill's directory. Read the one you need, copy it into your script (or pass its path as scriptPath when it fits unchanged), and adapt it to the plan. Each documents its args in a header comment.
sequential.js— one task: implement, gate, optional probe, fix loop capped atmaxAttempts(default 3) that stops when the same gate fails with the same output twice (ignoring durations, times, and hashes), then integrate. The probe (probe: true, needsgate) runs once the gates pass: atesterwrites tests from the contract on top of the change, the gate runs them, failing ones go to the fix loop as check output, and the tests are integrated with the change. A probe step that fails or stops returnsprobe_failedorstoppedwithout integrating. Args:{ task, prompt, gate?, probe?, maxAttempts?, message, checks? }.disjoint.js— independent tasks in apipeline, each prompt stating the paths it may edit; refuses duplicate task ids,..inowns, and overlappingownsbefore any step runs (a glob counts as owning its whole directory); integrates serially in task order; on a conflict runs aresolverfrom the current head that applies the task's whole change (implementation plus fixes,git diff --binary <first>^ <last> | git apply --3way), resolves the conflicts, and is integrated in its place; a resolver that cannot keep both sides changes nothing (no_changes) and the task is reported as a conflict; reports tasks that still fail. Args:{ tasks: [{ id, prompt, owns, gate?, message, checks? }], maxAttempts? }.explore.js— N variants of one task (variants, default 3, optionalapproaches), keeps those whose gates pass, lets one read-only judge step pick a winner with structured output, and integrates exactly one (none if none passes). Args:{ task, prompt, variants?, approaches?, gate?, criteria?, judge?, message, checks? }.
Always run herder_workflow { mode: "validate" } before run.
Writing step prompts
A step sees only its prompt and its worktree, not this conversation. Make every prompt self-contained:
- the task and the acceptance criteria it serves, quoted from
goal.md; - the relevant constraints and out-of-scope items;
- the files and interfaces to start from, and for fan-out the exact paths the step may edit;
- which checks matter and how to run them, including installing dependencies first (the worktree has none);
- for fixes, the failing check output or the review findings verbatim.
For risky changes, spend extra agents on evidence, not opinions; see Evidence over opinion below.
Rules
- Evidence over opinion. Read-only review of a diff mostly yields nitpicks and speculative findings; a failing test, a type error, or a counterexample from a tool needs no debate. Make a risky change prove more: a regression test that fails without the change, property-based or table-driven tests over the contract's inputs, and the type checker, static analyzers, and formal tools (model checkers, proof checkers) the repository already uses, run as checks. Use
probe: trueto have a tester write such tests. Do not add read-only steps that hunt for faults in a diff;explore.js's judge only picks among variants that already passed their gates. - Results are values. Check
statusafter everyagent()andintegrate()call, and after every tool call. Never assume success, never integrate a step that is notok, and never treattextas proof. The runtime refuses agate_failedstep inintegrate()andherder_integrate, whether named by result, step key, or commit. - Cap fix loops. At most
max_fix_attempts(default 3) fix attempts per task. Stop early when the same gate fails with the same output twice; report it instead of retrying. - Partition writers. Parallel writers only with explicit, disjoint file ownership stated in each prompt; integration is always serial. When in doubt, go sequential.
- Integrate in a fixed order. Call
integrate()from the script's top level, one task after another in a fixed order (asdisjoint.jsdoes after itspipeline), never insideparallelorpipelinebranches. Concurrent branches can integrate in a different order on a resumed launch, which changes later steps' bases, so they rerun instead of being reused. - Stable ids. Give every step an explicit
idthat includes its task and attempt number (fix-T1-2). Never reuse one id for a different prompt or options in the same launch; it throws. - No human waits in scripts. Scripts cannot ask the user anything. When a decision is needed, let the script return, ask the user, record the answer with
herder_run { action: "record_decision", question, answer }, and launch again. - Failures surface. Report
failed,conflict,checks_failed, andnot_methonestly with the check output. Do not weaken checks or criteria to get a pass; changing the goal needs the user. - Hands off the user's checkout. Steps run in their own worktrees. Do not edit the repository yourself during a run; all changes go through steps and reach the user only via
herder_deliver. - Verify before delivery. Deliver only after
herder_verifyreportsmetat the current head, and tell the user what the checks and verifier found.
04 同仓库更多 Skills
ui-sdk
Builds interfaces with ui-sdk in React, Vue, Svelte, Solid or web components. Covers choosing and composing its components, building a component or behavior it doesn't ship from @ui-sdk/core (like a stepper, splitter, transfer list or emoji picker), making the interface usable by agents through createAgent, agent tools and WebMCP, and testing keyboard, focus, ARIA, server rendering and right to left, including writing tests for an existing component. Use whenever a project has @ui-sdk/* installed or the user mentions ui-sdk.
pika-relay
Talk to Pi agents and other Codex threads through pika relay, and stand by for their requests. Use when a [relay] message arrives, when the user asks to message, list, or coordinate with other agents or Pi sessions, or when asked to stand by on pika relay.
impeccable
Use when the user wants to design, redesign, shape, critique, audit, polish, simplify, harden, animate, or otherwise improve a frontend interface: websites, landing pages, dashboards, product UI, components, forms, settings, onboarding, empty states, and native iOS or Android screens. Handles UX review, hierarchy, layout, typography, color, motion, UX copy, accessibility, responsive behavior, edge cases, and capturing or documenting design systems (DESIGN.md, tokens). Also for making bland UI bolder, loud UI quieter, or ambitious visual effects. Not for backend-only or non-UI tasks.
herder-simplify
Survey a codebase, read-only, for evidence-backed opportunities to delete or consolidate code, retire obsolete paths and abstractions, reduce state and control-flow complexity, and lower maintenance burden without changing required behavior; then let the user pick findings and start a Herder run for them. Use after /herder-simplify or when asked for a smaller, clearer, easier-to-maintain codebase with the work run by Herder.
herder-improve
Survey a codebase as a senior advisor, read-only, and present prioritized, verified findings - bugs, security, performance, tests, architecture, dependencies, tooling, docs, and evidence-backed direction - then let the user pick findings and start a Herder run for them. Use after /herder-improve or when asked to audit code or find improvement opportunities to hand to Herder.
agent-browser
Browser automation and web testing for AI agents using agent-browser (Chrome/Chromium CDP, accessibility-tree snapshots with @eN element refs, inline screenshots, and isolated sessions). Use when the user wants to open a website, test a web app, inspect UI, click buttons, fill forms, take screenshots, scrape data, or run exploratory QA.