crew

name

crew

description

Coordinate a fleet of worker agents in a pane-based multiplexer — 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 running inside a supported multiplexer (herdr, or cmux + tmux) and token-heavy work (specs, plans, builds, research) should be delegated to agents in visible panes. Coordinator doctrine only.

crew — coordinating agent fleets

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.

Substrate: this doctrine carries no multiplexer commands. Load the adapter for your multiplexer now and use it for every command referenced below:

• herdr → substrates/herdr.md
• cmux + tmux → substrates/cmux-tmux.md

Run the adapter's detection check first. If you are not inside a managed pane, 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

pi is the model-pinning agent CLI in the examples; the model tiers are yours to fill in.

Your role

You are the coordinator and the only face to the user. You own: strategy, briefs, the spec review-gate, dispatch, verification, merge, deploy, ops repair. Once the loop runs you never write feature code yourself — token-heavy generation goes to workers in visible panes.

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.

Surface topology — one workspace, yours

Every worker lives in YOUR workspace. A workspace is the project; the crew is one project. The coordinator never creates or moves work into another workspace, and never fragments the crew across containers.

• Workers are panes (splits, visible together) by default, and tabs (stacked, switchable) once panes get too small — past ~3 concurrent workers. Same workspace either way.
• To show the user a running worker, surface it in place (focus its pane/tab). Never relocate it to "present" it.
• The commands (create a pane, create a tab, focus, the forbidden move-to-another-workspace verbs) are in your substrate adapter.

Dispatch (hire pattern)

One pane per agent, tracked by job label (review-spec, attention-build, arrivals-research) — carry the label alongside the pane ref in your own context. The pattern, in substrate-neutral steps (commands in your adapter):

1. Open a labeled pane in your workspace.
2. Launch the agent CLI, pinned to provider/model; wait for its prompt.
3. Deliver the briefing. It is SELF-CONTAINED and ends with the report-back block. Some substrates truncate long inline sends — brief via a file pointer where the adapter says so.
4. Confirm the briefing actually submitted (agent went to work), else re-send the submit key.
5. Arm the dead-agent watchdog as a BACKGROUND task, never foreground.

Completion: push, not pull

Every briefing ENDS with the report-back block. <COORD> is your own pane id, injected by the substrate into every managed pane — never guess it or read it off the sidebar. The worker does BOTH:

1. Sends a human-readable line into the coordinator's pane (DONE <label>: … or BLOCKED <label>: …) — this lands as input and wakes you. Primary signal.
2. Fires the completion signal the background watchdog waits on.

The watchdog exists only to catch a worker that dies WITHOUT reporting. On substrates with semantic agent-status it releases on a real done; on substrates without it the watchdog is timeout-based, and a release means "look now," never "verifiably done." Either way: never poll in the foreground, and treat every DONE as a signal to verify, never a claim to accept. The exact commands and watchdog semantics are in your adapter.

Briefing templates

Briefings must be SELF-CONTAINED — workers have no conversation history — and always end with the report-back block (see your adapter for its exact commands).

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 pane. 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

• Read the worker's actual transcript (adapter command) — catches what tests can't (RAM errors mid-edit, silent improvisation).
• Course-correct with a surgical send to the worker's pane (adapter command).
• 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 self-triggers on the briefing's own DONE/BLOCKED echo	Use a semantic or token-based completion signal, never a text match on "DONE"/"BLOCKED" in the pane (see adapter)
Briefing sits unsubmitted; agent idle at 0% context	Long sends can land in the composer without submitting — confirm the agent went to work within ~15s, else re-send the submit key (see adapter)
Worker exiled to its own workspace / view fragmented	Workers stay in your workspace — panes while ≤3, tabs beyond. Surface in place; never relocate. The move-to-another-workspace verbs are forbidden for workers

Hygiene

• Close each worker's surface the moment its report is verified (adapter command). The workspace holds only you + currently-working agents.
• Teardown gates on VERIFIED SUCCESS, never on "I'm done looking." A BLOCKED or failed worker is the standing exception: keep it open until the user has seen it or says close — auto-closing it destroys the evidence they'd want.
• Final sweep before handing back: list panes in your workspace and close anything not actively working or deliberately kept (one line: "keeping : ").