dsh-crew

dsh-crew

Run work in DeepSeek Harness (dsh) as a small crew of role agents.

Your own dsh session becomes the product manager (PM). The PM is the only one who talks to you. It writes down what "done" means, asks you to confirm it, then starts an architect to design the work, engineers to write the code, and reviewers to judge both. The roles never talk to each other — they share work through files on disk, and the PM passes messages.

Version 0.4.3. PM, researcher, architect, engineer, QA, code reviewer, security reviewer, doc reviewer — plus pushing with your permission, CI watching, and picking a job up after a crash.

Two planes

dsh keeps model-facing tools in an agent preset, not in your profile. dsh-crew follows that, and splits itself in two:

Piece	Where	Why there
PM rules	host plane (your profile)	They need no tools, so they work in every session, on any preset
Role tools	the crew agent preset	A role's allow/deny list is checked against the preset when a child starts, so the names must be defined in the same place

Installing the plugin writes the preset into $DSH_HOME/.agent-presets/crew. Start a session on the crew preset to get the roles. In a session on another preset the PM still behaves like a PM, notices it has no role tools, and offers to either move to the crew preset or do the job itself.

The crew preset is dsh's own standard preset with one change: subagent, subagent_fork, workflow, ralph and the product subagents are gone, and the crew roles are there instead. So inside it, a crew role is the only way to start an agent.

Why the crew is flat

dsh has three hard rules about agents, and the design follows them:

dsh rule	What it means here
A message can only go to a direct child	Every role is a direct child of the PM, so the PM can reach all of them
A child answers only its direct parent (report)	Every answer comes back to the PM
Two children cannot talk to each other at all	Roles share work through files, not chat

If the architect started the engineers, the PM could not reach the engineers at all. So only the PM starts agents. Two independent guards enforce that: every role is denied the delegation tools, and each role tool has maxDepth: 1, so a crew child cannot start another crew child.

What a role really is

A role is not a prompt the PM pastes in. It is a real delegation tool built from @deepseek-ai/dsh-tool-subagent:

Role	Tool	Persona	Tools
Researcher	crew_researcher	roles/researcher.md	only read, glob, grep, write, web_search — no shell
Architect	crew_architect	roles/architect.md	everything except the crew tools
Engineer	crew_engineer	roles/engineer.md	everything except the crew tools
QA	crew_qa	roles/qa.md	everything except the crew tools — it must run the software
Code reviewer	crew_code_reviewer	roles/code-reviewer.md	only read, glob, grep
Security reviewer	crew_security_reviewer	roles/security-reviewer.md	only read, glob, grep
Doc reviewer	crew_doc_reviewer	roles/doc-reviewer.md	only read, glob, grep

So a code reviewer cannot change a file, even if it decides it wants to. The persona is locked in as that child's own system prompt.

The reviewer uses an allow list, and two live tests are the reason:

1. With write and edit denied, it created a file anyway with echo hello > file. A shell is a file-writing tool.
2. With the shell denied too, its own tool report still listed workflow, ralph and a set of desktop-control MCP tools — every one of them a way out.

A deny list cannot name what a deployment has not installed yet. An allow list does not have to. The PM pastes the diff into the review task and runs any command the reviewer asks for.

Two more guards sit under the filters:

• maxDepth: 1 on every role tool — only the root PM can start a role, and it names no tool at all, so no preset change can weaken it.
• The crew preset itself removes every other way to start an agent, so a role cannot route around the filter through workflow, ralph or a bare subagent.

Editing the roles

Role personas are plain markdown in roles/. Copy one into ~/.dsh/crew/roles/ under the same name and it replaces the shipped version. One limit: prompt text may not contain {{ — dsh would read it as a variable, and the plugin fails at startup naming the file.

Role tool filters and per-role models are configured where the roles live: the dsh-crew-roles row in ~/.dsh/.agent-presets/crew/agent.cordis.yml.

That file sits inside the installed preset, and a new version of dsh-crew replaces the whole folder. Your edited files are kept beside the new ones as agent.cordis.yml.bak, and the boot log names them — but the settings do not come back by themselves. After an upgrade, copy your changes into the new file.

How a job runs

1. The PM sorts your ask into a lane: ask (answer only), quick (do it), or team (the full flow). If the size is unclear, it asks you.
2. It asks which language to use. It never guesses.
3. It grills you — one question per turn, each with a recommended answer. It waits for your answer before it asks the next one, and never sends you a list of questions. It looks up every fact it can in the repository first. For anything bigger than a quick look it starts a crew_researcher, which writes findings with a source for every answer, so you are only asked what the files cannot answer.
4. It picks the document and writes it: a DoD (docs/crew/dod.md) for small work, a PRD (docs/crew/prd.md) for a real product. It says which it picked, and one word switches it. You confirm before any work starts.
5. For PRD work it starts crew_architect, which writes the high level design, the decision records and the task breakdown — then crew_doc_reviewer must pass those before a single line of code is written.
6. It creates a crew/<job> branch and runs one crew_engineer per task. Two engineers run together only when their file lists do not overlap. Every engineer works test first: it writes one unit test, runs it, checks that it fails for the right reason, then writes the smallest code that makes it pass. Its report has to show you the failing run and then the passing run. An engineer that believes a test cannot come first must ask the PM before it writes any code.
7. Each finished task is checked in order: code review (correctness, then the tests that drove the change, then reuse, simpler code, readability and this repository's own style — the reviewer may hold up a task on those, but only if it shows the exact replacement it wants; otherwise the finding is optional) → security review, only when the change touches the network, login, secrets, files outside the project, the shell, user input, customer data or a new dependency → QA, which writes its test plan from the document before reading the code, then runs it. Round two of any review only re-checks the blocking findings; after the round limit the PM brings the disagreement to you.
8. The PM commits — engineers never touch git. It stages only the files that task owns, never git add -A.
9. The PM updates the repository README to match what was built. README.md is always English. If you chose another language for the job, it keeps a second file beside it — README-zh.md, README-ja.md — saying the same thing. If nothing a reader would notice changed, it leaves the README alone and tells you so.
10. A last crew_doc_reviewer pass over every document the job produced, the README included. It checks that the documents can be worked from, that they stay consistent (one name per idea, one shape, and the language files saying the same thing), and that they read easily for someone about 14 years old whose first language is not English — by counting things like sentence length, idioms and unexplained terms, not by taste. It may hold up the job on wording, but only if it writes the replacement sentence itself.
11. Push and CI, if you allow it. The PM checks there is a remote, a workflow and a working gh first. Then it asks you — before every push, including a re-push after a fix. It pushes only the crew/* branch, watches the run, and sends a red CI's real error text back to the engineer that owns those files. main, tags and force pushes stay blocked whatever anyone says.

Documents live in the repository (docs/crew/). The job state lives outside it, in ~/.dsh/crew/jobs/<job>/state.json, so your git status stays clean.

After a crash

The state file alone is not enough — the next session has to know about it. So dsh-crew reads the job folder on every turn and, when something is unfinished, puts a short note in front of the PM:

Unfinished crew work: 1 job left in /home/you/.dsh/crew/jobs.

- "add-sso-login" in /home/you/project (branch crew/add-sso-login):
  5 of 9 tasks done, 2 blocked. Last change 2026-08-18 09:12.

The PM must tell you before it does anything else, and ask one question: carry on or start clean. It never does either without your answer. A job belonging to a different folder is ignored, and a state file it cannot read is reported rather than counted as finished. Turn the whole thing off with resumeNotice: false.

The git guard

host/git-guard.js inspects every shell command, from every agent including the PM, and refuses:

• git push of main, master, trunk, develop, HEAD, or with no branch named;
• any tag push, remote delete, --mirror, --all, or force push;
• npm/pnpm/yarn/bun publish, npm dist-tag, gh release create;
• a push into a repository whose CI runs on push and looks like it publishes;
• any command that touches the approval file, so an agent cannot approve itself.

Any other branch push needs a one-shot approval that you create:

mkdir -p ~/.dsh/crew && touch ~/.dsh/crew/push-ok

The guard deletes that file as soon as one push uses it. One approval, one push.

This reads command text, so it is a strong seat belt, not a locked door: a command hidden inside a script file could still slip past. Your dsh approval prompts stay the real gate.

Install

dsh plugin --profile tui add dsh-crew     # or --profile web

Then restart dsh. Starting it writes the crew preset into $DSH_HOME/.agent-presets/crew (a crew folder somebody else wrote is left alone). Pick the Crew preset for a session to get the roles.

To check the plugin without dsh:

npm test        # replays the guard rules and the mount, no dsh needed

Configuration

Everything is optional. Settings live in the plane they belong to.

PM and guard — the dsh-crew-core and dsh-crew-git-guard rows in your profile's cordis.patch.yml:

Setting	Default	What it does
rolesDir	~/.dsh/crew/roles	Your own role markdown files replace the shipped ones, by file name
limits.liveAgents	4	Crew agents awake at the same time
limits.agentsPerJob	20	Crew agents one job may use
limits.reviewRounds	3	Review rounds before the PM asks you to decide
installPreset	true	Write the crew preset into $DSH_HOME/.agent-presets
jobsDir	~/.dsh/crew/jobs	Where job state lives, and what the crash notice reads
resumeNotice	true	Put unfinished jobs in front of the PM at session start
enabled (guard)	true	Turn the git guard off — not recommended
approvalFile	~/.dsh/crew/push-ok	One-shot push approval file

Roles — the dsh-crew-roles row in ~/.dsh/.agent-presets/crew/agent.cordis.yml:

Setting	Default	What it does
rolesDir	~/.dsh/crew/roles	Same override folder, for the role personas
roleAllow	reviewers: read, glob, grep	Only these tools for that role; everything else is closed
roleDeny	makers: the crew tools	Everything except these for that role
roleModels	session model	Per-role provider and model

License

MIT