crew

name

crew

description

Coordinate a fleet of worker agents in herdr panes — one default pipeline (coordinator → flat-rate spec-writer → local builder) with exception surfacing, dispatch and briefing templates, push-based completion protocol, review gates, verification ladder. Use when HERDR_ENV=1 and token-heavy work (specs, plans, builds, research) should be delegated to agents in visible panes. Coordinator doctrine only.

crew — coordinating agent fleets in herdr

Worker gate: if you were dispatched into a pane to execute a task (you received a briefing that ends with a report-back line), STOP READING — this skill is coordinator doctrine and does not apply to you. Follow your briefing.

Check HERDR_ENV=1 first. If it is not set, you are not inside herdr: do not dispatch anything, tell the user.

Your stack

The doctrine routes across three model tiers. Fill these in for your setup:

Tier	What it is	Reference example (author's stack)
PREMIUM	The coordinator — your own scarce, metered subscription	Claude (Opus-class)
FLAT-RATE	Subscription-included pools, free at the margin	pi --model zai-coding-cn/glm-5.2 (routine specs), pi --model openai-codex/terra (hard specs), pi --model openai-codex/sol (research)
LOCAL	Self-hosted OpenAI-compatible server — free and the only private lane	pi --model omlx/Qwen3.6-35B-A3B-UD-MLX-4bit, health at localhost:8765/v1/models

The herdr commands are canonical — herdr's own bundled agent skill has the full CLI reference; this skill is the coordination doctrine on top. pi is the model-pinning agent CLI in the examples; the model tiers are yours to fill in.

Routing — one default pipeline; exceptions surface

Economics: PREMIUM (you) is the scarce tier — spend it on judgment, never volume. FLAT-RATE absorbs spec-writing; LOCAL builds for free and is the only private lane. There is no routing table to weigh per task: there is ONE default pipeline, and anything else is an exception that surfaces.

The default pipeline for every substantive delegated task:

1. You — strategy, brief, review gate, verification, merge/deploy. Never delegated.
2. Spec-writer, FLAT-RATE — routine specs on your routine model; hard specs/architecture on your strongest flat-rate reasoner. Which of the two is a silent call — both are flat-rate, stakes are low. The plan must be verbatim-executable: complete code blocks, exact verification commands, expected output.
3. Builder, LOCAL — verbatim transcription only. Confirm the server is up BEFORE routing — down is a deviation, not a silent fallback. Interpreting the check: ANY HTTP response (including an auth error — keyed endpoints reject bare curls) means the server is up; only connection-refused/timeout means down. Restart the local server before every big build — doctrine, not hygiene. Long-running local inference servers accumulate resident models and KV/cache state across sessions; when the real ceiling is a fixed OS/hardware memory cap (common on unified-memory hardware — no server-side setting moves it), that accumulated residency, not the new request's size, is what makes big builds abort mid-task. A fresh process starts near-empty with headroom to spare. The restart costs seconds; a mid-build abort costs a full re-brief.
4. You verify — the verification ladder, every time.

First fork — is there a verbatim plan? (coding vs knowledge work.) The LOCAL lane is transcription only. If the deliverable can be fully specified as a verbatim plan (most coding builds), the default pipeline applies. If it can't — analysis, synthesis, research, drafting, visual/browser-driven work (Playwright), anything agentic-tool-heavy — it is knowledge work: generation runs FLAT-RATE (research model for sweeps and drafts; routine spec model for structured documents), NEVER local. Local models transcribe plans well and do open generation and tool-driving badly. Knowledge work is a named lane, not a deviation — no blocking ask, just its own routing line: ROUTE: <task> → knowledge (flat-rate: <model>) — no verbatim plan possible The research model never writes implementation specs. Knowledge deliverables still get coordinator verification (ladder, adapted: no test suite, but claim/source spot-checks against real material).

Equipped archetypes — the knowledge lane's default shapes. A couple of knowledge roles recur often enough to be pre-equipped agents rather than briefed from scratch each time. Dispatch them by activity signal:

• research-scout — the task has a web / research component. A FLAT-RATE agent wired to your search tools, with your private/self-hosted search FIRST and public search as fallback; returns cited, dated findings with confidence + gaps.
• scribe — writing structured output into your knowledge base / notes at volume. A FLAT-RATE agent that discovers existing context first (so it links instead of duplicating), writes to your schema, and proposes rather than commits anything schema-strict — the coordinator gates that.

Equipping is the point: the tool wiring and house conventions live in the archetype once, not in every briefing. Keep each archetype's definition in ONE source and deploy it to every harness you dispatch from — different harnesses often need format-specific ports (different tool names, different web-access model), and a hand-maintained second copy is how they silently go stale.

Dispatch, don't absorb. If a task carries a research / knowledge-base / analysis component above the sub-minute-lookup threshold, that is a named lane — dispatch the archetype, don't quietly do the work in the PREMIUM session. A single high-stakes artifact or a two-line lookup stays in-session; volume leaves. Absorbing knowledge work into the coordinator is the silent, expensive default this rule exists to break.

Routing line — mandatory before every dispatch. One visible line to the user: ROUTE: <task> → default (spec: <flat-rate model> → build: <local model>) — <one-phrase reason> This is where the user vetoes cheaply — before tokens burn, not after.

Deviations ask first (blocking). Any departure from the default — direct flat-rate generation (design exploration where taste can't be spec'd; parallel fan-out a single-tenant local server can't serve), local server down, a plan too big for local context, a typist that BLOCKs twice — stops and asks the user: reason + recommended alternative, then wait for the call. Never silently promote a build to a cloud pool.

Self-written spec announces itself (visible, not blocking). When briefing a spec-writer would cost as much as writing the spec (tiny spec, or the judgment IS the spec), write it yourself and state SPEC: writing myself — <reason> in the routing line. The visibility is the control: if the pattern gets lazy, the user sees it.

Hard overrides (state, don't ask):

• Personal/private data (messages, mail, contacts) → every stage LOCAL, including the spec-writer (it reads the data too). No cloud pool, ever.
• Opportunistic bonus capacity (a friend's server, a spare box): only when verifiably up; never depend on it.
• Metered per-token APIs: never — that is real spend the flat-rate pools exist to avoid.

ALWAYS pin the model explicitly (--model provider/id), and pin the EXACT id from your provider's current model list — not a short alias remembered from an old log. Aliases get renamed; a stale one can stop resolving and fail with a misleading error (e.g. an auth or "model not supported" message that has nothing to do with the real cause). Your CLI's model-list command is the source of truth for ids, not your dispatch history. Agent-CLI defaults also drift; an unpinned dispatch silently burns the wrong pool.

Visibility rule: every delegated work session gets a visible, labeled pane. In-process subagents only for sub-minute read-only lookups.

Dispatch (hire pattern)

One tab per agent, labeled by job (review-spec, attention-build, arrivals-research):

COORD="$HERDR_PANE_ID"   # your own pane id — herdr injects it into every managed pane; never guess it
AGENT=$(herdr tab create --workspace "$HERDR_WORKSPACE_ID" --label <job-label> --no-focus \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["result"]["root_pane"]["pane_id"])')
herdr pane run "$AGENT" "pi --model <provider/id>"
herdr wait agent-status "$AGENT" --status idle --timeout 30000   # TUI booted, agent at its prompt
herdr pane run "$AGENT" "<briefing>"

Then confirm the briefing actually submitted, and arm the watchdog as a background task (never foreground):

herdr wait agent-status "$AGENT" --status working --timeout 15000 \
  || herdr pane send-keys "$AGENT" Enter   # long briefings can land in the composer unsubmitted
herdr wait agent-status "$AGENT" --status done --timeout 5400000

NEVER watch for DONE|BLOCKED text as the watchdog — the briefing itself contains those words, and its echo self-triggers the match. agent-status is semantic and echo-immune. The worker's pushed DONE/BLOCKED message stays the primary wake signal; the status watchdog only catches agents that die without reporting.

Completion: push, not pull

Every briefing ENDS with this report-back block — <COORD> is your own pane id ($HERDR_PANE_ID, injected by herdr into every managed pane; never guess it or read it off the sidebar):

FINAL STEP — mandatory. After your last action:
herdr pane run <COORD> "DONE <label>: <one-line status>"
If you cannot proceed:
herdr pane run <COORD> "BLOCKED <label>: <one-line reason>"

(pane run sends text and Enter together — herdr's canonical way to submit input to a pane.)

The message lands in your pane as user input and wakes you. Never poll in the foreground — the background watchdog exists only to catch hung/dead agents that can never report. Treat every DONE as a signal to verify, never a claim to accept.

Briefing templates

Briefings are typed into the worker's pane like a human prompt. They must be SELF-CONTAINED — workers have no conversation history — and always end with the report-back block.

Every briefing also carries this hard rule verbatim (agent CLIs may auto-write workspace state on exit; a generic "don't touch other files" does not stop it): Do NOT create or modify _session.md or any workspace state file — those are owned by the coordinator.

Spec-writer (strong flat-rate model for hard problems, routine model otherwise):

You are a spec-writer for <project>. Work only in <repo path>.
ASSIGNMENT: write a spec and an implementation plan for: <feature — product rationale + exact required behavior>.
READ FIRST, in order: <current source files touching the feature>; then <newest exemplar spec path> and <newest exemplar plan path> — imitate their structure exactly.
WRITE: <specs dir>/<date>-<slug>-design.md and <plans dir>/<date>-<slug>.md
HARD RULES for the plan:
- Every code change is a complete verbatim code block — the executor transcribes, never invents.
- Every task ends with exact verification commands and expected output.
- State the current suite baseline (<N> passing) and the expected count after each task.
- One commit per task with the exact commit message. Branch: <branch>. No new dependencies.
- Fixture data is invented, never real personal data. Time-dependent tests freeze the clock.
- If the executor fails a step twice, the plan tells it to STOP and report BLOCKED.
Do not touch any file outside <docs dir>/.
<report-back block, label: <slug>-spec>

Builder / typist (LOCAL model):

You are an executor. Work only in <repo path>, branch <branch>.
ASSIGNMENT: execute the plan at <plan path> by VERBATIM TRANSCRIPTION.
RULES:
- Read the whole plan first, then execute task by task, step by step.
- Transcribe code blocks exactly as written — do not improvise, reformat, or "improve".
- Run every verification command and compare against the plan's expected output.
- Commit after each task with the exact message from the plan.
- If a step fails twice, STOP immediately and report BLOCKED with the failing output.
<report-back block, label: <slug>-build>

Researcher (FLAT-RATE research model):

You are a researcher. ASSIGNMENT: <self-contained question with all needed context>.
DELIVERABLE: markdown at <output path> — summary first, findings with source links, open questions last.
Do not edit any other file.
<report-back block, label: <slug>-research>

Review gate (before dispatching any plan to a builder)

This is where the coordinator earns its keep:

• Read the whole plan end to end.
• Verify every edit anchor (quoted "current code") against the CURRENT files — anchors go stale when you ship hotfixes while the writer works.
• Recompute the test-count arithmetic (baseline + per-task additions).
• Trace each new test's assertions against the planned implementation — do they pin behavior, or just status codes?
• Check fixtures for real personal data.
• Small issues: fix inline. Structural issues: back to the writer. Then commit the docs before dispatch.

Concurrency

• Builders run strictly one at a time — shared working tree, and a local server is single-tenant in practice.
• Spec writers may overlap builders (they only create new doc files). Exception: when a hard override forces the spec stage onto the same single-tenant LOCAL server as the build, the stages run sequentially.
• Never touch panes in workspaces that aren't yours.

Verification ladder (run after every DONE)

1. git log matches the plan's commit list; tree clean. Non-git workspaces: verify no file outside the assignment changed — especially workspace state files like _session.md, which some agent CLIs auto-write on exit and which are NOT recoverable without git.
2. Run the test suite yourself — never trust the worker's claim.
3. Behavioral check against real data.
4. UI change → screenshot (tests check content; only screenshots check layout; headless Chrome won't go below ~500px width — real phones are the only honest mobile test).
5. Merge fast-forward, deploy, verify live, close the tab. Branches live hours, then die.

Gather vs judge — you may delegate the capture, never the verdict. Producing the evidence (driving a browser to screenshot the change at desktop and mobile widths, running the suite, assembling the diff and log) is mechanical and token-heavy — it can go to a verifier agent, and offloading it keeps the noisy intermediate output out of your context. But the verifier returns artifacts, not conclusions: file paths to the screenshots, raw test output, the diff. You then look at the actual artifacts and decide pass/fail, merge, deploy, and what to tell the user. That preserves "DONE is a signal to verify, never a claim to accept" — you trust your own eyes on the artifact, not the agent's summary of it. The decision and the message to the user always stay with the coordinator.

Steering mid-flight

• herdr pane read <pane> --source recent-unwrapped --lines 40 shows the worker's actual transcript (recent-unwrapped joins soft wraps — herdr's preferred source for logs/transcripts) — catches what tests can't (RAM errors mid-edit, silent improvisation).
• Course-correct with a surgical herdr pane run <pane> "<instruction>".
• Scope extension to a writer mid-write: "SCOPE EXTENSION to your current assignment — same files, integrate, do not write separate docs."

Failure playbook

Symptom	Fix
Typist improvises despite "verbatim" — tests pass, behavior/layout wrong	Re-instruct "transcribe from the plan file"; add behavior-pinning assertions; screenshot verification
Local-server RAM ceiling (~60% context on a ~35B model) — agent dies mid-edit	Fresh agent session, then a SELF-CONTAINED re-brief (fresh sessions remember nothing)
Builder aborts on the local server's own memory guard ("memory limit exceeded") mid-task	Accumulated server residency, not request size — restart the local server before big builds, then fresh session + re-brief. Don't chase server-side memory-guard settings if the real ceiling is a fixed OS/hardware cap
Stale plan anchors after a coordinator hotfix	Review gate re-verifies anchors immediately before dispatch
Ghost server on a shared port serving old code	pkill before re-serving; check what the port actually serves
Weak assertions (HTTP 200 ≠ feature exists)	Assert the feature's visible artifacts: markup, counts, scope lines
Worker overwrote _session.md / workspace state despite the brief	Outside git this is not cleanly recoverable — restore from your own context if possible; tighten the brief; file-tree check after every DONE
Typist BLOCKs twice on a plan step	Deviation event: stop, ask the user with a recommended alternative — never silently promote the build to a cloud pool
Watchdog fires instantly at dispatch	wait output matched the briefing's own echo (it contains "DONE"/"BLOCKED") — watchdog on wait agent-status --status done instead
Briefing sits unsubmitted; agent idle at 0% context	pane run with long text can swallow the submit — confirm working within ~15s, else send-keys Enter

Hygiene

Close each worker's tab after its report is verified (herdr tab close <tab>). The workspace holds only you + currently-working agents.