Dsh Playbook

When the user asks how to dispatch work to DSH workers — tier choice, writing a brief, parallelism, verifying results, guardrails — answer from the playbook below. Point to the relevant section rather than reciting it whole.

DSH Crew — Dispatch Playbook

How to delegate work to DSH workers well. The tool descriptions carry the mechanics; this playbook is the decision layer.

1. Choosing a worker

flash — mechanical, well-scoped work:

• Rename a symbol in one or two files and update the obvious call sites.
• Read a config file and report the values of a few keys.
• Add a unit test for an existing function, following the file's existing style.

pro — multi-file work, debugging, design judgment:

• Refactor a module that is used across the repo and update every caller.
• Diagnose a flaky test or a race condition by reading logs and tracing the code.
• Design a new API or file layout with tradeoffs to weigh, then implement it.

When in doubt, start with flash: escalate_on_failure retries a failed blocking flash run once on pro, so evidence, not guesswork, decides.

worker="agy" / worker="grok" is explicit opt-in. Set it only when the user explicitly asks for that CLI, never as a default. Two caveats to tell the user: grok refuses to start repo-local MCP servers in untrusted folders (global installs are unaffected; change directory or pass --trust), and agy runs with full approval because it has no workspace-scoped permission mode.

2. Writing the brief

The worker has zero conversation context. Every task string must be self-contained:

• Absolute paths for every file and directory involved.
• Exact acceptance criteria: what must be true when done, and how to verify it.
• What NOT to touch (generated files, unrelated modules, lockfiles).
• Never commit, push, or publish unless the user explicitly authorized it — write that into the brief.

Bad: "fix the auth bug". Good: "In /abs/path/repo/src/auth.ts the token refresh throws on 401 when the session expires; make it retry once and fail loudly, add a test in /abs/path/repo/test/auth.test.ts, and run npm test. Touch only auth.ts and its test. Do not commit."

3. Parallelism

• Default: one worker per repo/workspace. The cwd advisory lock enforces this — a second dispatch into a held workspace is refused with the holder's job id, not queued.
• Parallel workers in one repo are only safe with explicitly disjoint file territories AND a named owner for every seam where the two halves meet. Unowned seams are where integration gaps happen; write the seam owner's name into each brief.
• allow_concurrent_cwd: true is only for read-only tasks. It is never a license for two writers.