dsh-subagents

Readme

# dsh-subagents

**Focused child-agent delegation and multi-agent workflows for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).**

> A faithful port of [`pi-subagents`](https://github.com/nicobailon/pi-subagents), rebuilt on DSH's **native** `subagent` / `subagent_fork` / `workflow` tools — so you get the curated personas and workflows without giving up DSH's built-in delegation.

- 🇨🇳 [中文文档](README.zh.md)

## Why this exists

DSH already ships delegation (`subagent`, `subagent_fork`, `workflow`, `agent_teams`) and an on-demand skill system. What it does **not** ship is a ready-made set of *who* to delegate to and *how* to chain them.

`dsh-subagents` fills that gap with:

| Need | You get |
| --- | --- |
| A second pair of eyes before you edit | `reviewer` persona with P0/P1/P2 findings + a merge verdict |
| A sanity check on a risky decision | `oracle` persona that challenges assumptions without editing |
| Fast recon of unfamiliar code | `scout` persona for entry points, data flow, and risks |
| Grounded external facts | `researcher` persona producing a sourced brief |
| A careful implementer | `worker` persona that edits minimally and escalates instead of guessing |
| Orchestrated review/impl loops | `parallel-review`, `review-loop`, `council`, `parallel-research`, `parallel-cleanup`, `gather-context` workflows |

**Problems solved:** no hand-rolled prompts, no remembering role tool-allowlists, no reinventing review loops. One install and you can say *"use reviewer to review this diff"* and get a disciplined review.

**What makes it different:** it's not a new agent runtime — it's a thin, dependency-light skill layer (pure ESM, zero runtime deps) that teaches the model how to use DSH's own tools, so it composes with everything else in your profile (AgentTeams, MCP servers, skills, themes).

## Install

```bash
dsh plugin --profile web add dsh-subagents
# or from a local checkout:
dsh plugin --profile web add /path/to/dsh-subagents
```

Restart the dsh process, and you're done — no config, no slash commands.

## Try this first

- "Use reviewer to review this diff."
- "Ask oracle for a second opinion on my current plan."
- "Use scout to understand this code."
- "Run parallel reviewers: one for correctness, one for tests, one for simplicity."

The model loads the matching `subagents-*` skill and delegates with the native tools. You don't create agents, write config, or learn commands.

## Builtin roles

| Role | Use when you want… |
| --- | --- |
| `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks. |
| `researcher` | Web/docs research with sources and a concise brief. |
| `worker` | Implementation: edits files, validates, escalates unapproved decisions. |
| `reviewer` | Code/plan review with P0/P1/P2 findings and a merge verdict. |
| `oracle` | A second opinion before acting; challenges assumptions without editing. |
| `delegate` | A lightweight general handoff close to the parent session. |

## Workflows

| Want | Skill |
| --- | --- |
| Debate a material decision | `subagents-council` — bounded parent-mediated advisor council |
| Review a diff adversarially | `subagents-parallel-review` — several fresh reviewers, distinct angles |
| Implement → review → fix until clean | `subagents-review-loop` — capped at 3 rounds |
| Build a grounded multi-angle answer | `subagents-parallel-research` — researcher + scout |
| Clean up AI-slop / verbosity | `subagents-parallel-cleanup` — deslop + verbosity passes |
| Gather context, then clarify | `subagents-gather-context` — scout/researcher, then clarifying questions |

## How it maps to DSH

| pi-subagents | dsh-subagents / DSH |
| --- | --- |
| `subagent` tool | `subagent` (fresh) / `subagent_fork` (context-aware) |
| `workflowScript` | `workflow` |
| multi-agent teams | `agent_teams` (native) |
| builtin agents (`.md` frontmatter) | skills `subagents-scout`, `subagents-reviewer`, … |
| prompt shortcuts | skills `subagents-council`, `subagents-parallel-review`, … |
| `context: fresh` / `fork` | `subagent` / `subagent_fork` |
| async / background | `run_in_background: true` + `job_output` / `job_kill` |
| `subagent({action:"list"})` | `list_agents` (children) + the skills catalog |

> **Note on roles:** DSH's `subagent` tool fixes persona/tool-filter at config level, not per call. So role switching here is prompt-driven: each role is a skill whose persona text you paste into the child's `prompt`. Hard per-role tool isolation would require a DSH agent-preset composition layer — see [Limitations](#limitations).

## Layout

```
lib/index.js        host plugin — registers skills + a usage section
skills/*.md         the persona and workflow bodies
cordis.patch.yml    mounts the plugin into a profile's host composition
```

## Requirements

- Node ≥ 20 (ESM).
- A DSH profile whose base bundle mounts `skills` and `systemPrompt` (standard profiles do).

## Limitations

- Role personas are **soft** guidance: a child inherits DSH's toolset and self-limits by the persona's tool guidance. There is no per-call tool-allowlist enforcement.
- `council` cross-exams use a fresh re-launch rather than resuming the same child, because DSH one-shot subagents are not resumable (use `subagent_fork` + `send_message` for a resumable child when you need it).

## Contributing

Bug reports and PRs are welcome. Please open an [issue](https://github.com/geekyfoxlab/dsh-subagents/issues) before starting non-trivial work. There is no build step — the plugin is plain ESM, so `node --check lib/index.js` and a mock `apply()` run are the smoke tests.

## License

[MIT](LICENSE). A port of [pi-subagents](https://github.com/nicobailon/pi-subagents) (MIT, © Nico Bailon).