Introduction¶

Agent Teams has a set of constraints not written in the official README but only known after encountering them: the roster only increases, not decreases, and slots cannot be reclaimed; interrupts do not release members; the write scope is merely a hint, not a lock; teammates default to fresh context and cannot see your history; without active teammates, wait_agent returns immediately instead of waiting. The commonality of these constraints is that when an error occurs, there is no error reporting, only abnormal behavior, and the cause cannot be found in the stack trace.

dsh-agent-team-playbook is an unofficial plugin maintained by elfgzp for classifying workflows. It does not modify the runtime but writes these constraints into six rules, registers them as an ordered system prompt section injected into each agent, allowing the agent taking over the Team to know which paths are blocked before starting work. Below are its capabilities, installation steps, and practical details.

What is it¶

One sentence: a pure prompt injection bundle that puts Agent Teams operational rules into the system prompt instead of adding new tools or changing runtime behavior. Verified against the upstream tag dsh-v0.2.1-rc.3 source code; unofficial, no affiliation with deepseek-ai.

The plugin itself is small; packaging contains only four runtime files: lib/index.js, cordis.patch.yml, locale/{zh,en}.json, icon.svg. docs/ and examples/ are distributed with the repo and do not participate in packaging.

What it does¶

The plugin registers an ordered system prompt section team-playbook:rules, order 650, injecting six rules into each agent:

The position of 650 is immediately after upstream TEAM_POLICY(600) and before PTC_ONLY(800), reading as a continuation of Team policy, not splitting subsequent tool sections.

What it does not do¶

Clearly define boundaries to avoid false expectations:

• Does not add any tools, pure prompt injection, does not change Team runtime behavior.
• Does not enforce any flow; soft status tags and write scope overlap are still just hints.
• Does not do UI, no client side, does not add panels or buttons.
• Does not modify upstream source code, relies on @deepseek-ai/dsh-experimental-agent-team working as-is.

Installation and Activation¶

Environment Requirements¶

DeepSeek Harness >=0.2.1-rc.3 <0.3.0, tested on 0.2.1-rc.3 and 0.2.1-rc.5. Version constraints are written in peerDependencies in package.json and validated by DSH installation. The interval syntax applies to both 0.2.1-rc.x and 0.2.x stable versions; pre-release versions like 0.2.2-alpha.x do not match by default per semver, and one must verify the API hasn’t changed before relaxing the constraint when encountered.

Installation from Local Directory¶

First clone to a persistent directory (do not use /tmp), then pnpm install --prod, then self-check, and finally install using plugin_manager’s install_bundle. Do not swap the order of these steps: placing self-check before install_bundle allows “dependencies not installed” to be exposed immediately; skipping self-check results in application: failed plus ERR_MODULE_NOT_FOUND, and does not hint at the real cause, easily leading to misdiagnosis as a code bug.

cd ~/Work
git clone https://github.com/elfgzp/dsh-agent-team-playbook.git
cd dsh-agent-team-playbook

pnpm install --prod

node --input-type=module -e "const m=await import('./lib/index.js'); \
  console.log('deps OK', Object.keys(m), m.inject)"

The above script clones the repo to a persistent directory, installs dependencies, and performs a self-check, expecting output deps OK [ 'Config', 'apply', 'inject' ] [ 'systemPrompt', 'agents' ]. This step does not depend on the DSH runtime, only confirming that the plugin’s own dependency resolution is normal.

{
  "action": "install_bundle",
  "target": "/absolute/path/to/dsh-agent-team-playbook"
}

This section uses plugin_manager to install from a local directory. After installation, you should see the title “Agent Teams 操作守则” (Agent Teams Operational Rules) and the corresponding description (from locale/*.json) in the plugin details; agents in existing sessions take effect immediately, and newly created teammates automatically receive this section. Uninstall using remove_bundle, or disable within set_bundle. Replacing an installed package requires a restart because it needs to load a new generation of JS modules.

Three Common Pitfalls¶

The pnpm-workspace.yaml in the parent directory. If ~ or ~/Work contains this file, pnpm treats that directory as the workspace root. When executing install in a subdirectory, it outputs “No projects found”, installs nothing, and exits with code 0, so && chains and CI will not report errors. One solution is pnpm install --prod --ignore-workspace. Note that --ignore-workspace-root-check is not the option for this scenario; pnpm will directly report “Unknown option”.

The source directory cannot be deleted. The link: protocol only registers a link pointing to that directory, it does not copy files. Deleting or moving the checkout will cause the plugin to fail on the next start, the error is application: failed, and it will not prompt “source directory has disappeared”.

Do not skip pnpm install. When installing from a local directory via link:, dependencies are resolved from the plugin’s own directory and peerDependencies are not automatically installed; you must rely on pnpm install --prod for lib/index.js to find them.

Verification of Effectiveness¶

Prompt injection plugins have no buttons to click, so verification must be done by reverse-checking the prompt content:

1. Check registered sections: Call Config’s listConfigs, fill input.name with dsh-agent-team-playbook.
2. Check the application field of the plugin row: applied means it is truly activated; overridden means it is covered by a higher priority layer; restart-required means it has not taken effect yet.
3. End-to-end confirmation in a session: After opening a new session, ask the agent to recite “Agent Teams has how many operational rules”, and it should list the six rules in the table above.

Limitations to note: registering a section does not mean the user will definitely see the expected text; rendering effects depend on prompt assembly, and this repository does not contain automated assertions.

Practical Details: When to Use a Team¶

Agent Teams has fixed costs (slots cannot be reclaimed, message overhead, risk of write conflicts with shared cwd), it is not free parallelization, so first make a judgment, then summon people.

Can the task be split into 2+ independent, parallelizable sub-problems? If so, check if sub-problems need shared decision-making or mid-way alignment: if not, let them run independently to completion and then summarize; a Team is a good choice. If continuous high-frequency alignment is needed, the message overhead exceeds parallelization benefits, switch to a single agent serial execution. If alignment is only at key nodes, a Team is feasible; use a shared task board to express dependencies instead of a bombardment of messages.

Additional veto conditions, if any are hit, do not use a Team: subtasks will write to the same batch of files; subtasks need to run the same build or test and interfere with each other; the total task volume is so small that coordination costs dominate; all slots are used up and there are no reusable idle members.

Slots and Roles, this is the easiest pitfall to fall into. The default upper limit is 16 teammates, current profile is configured to 8; leads do not count towards this limit; state.members array only contains teammates; the roster has no deletion mechanism, slots cannot be reclaimed; names are unique for the entire session. So plan the roster first, then summon people.

Write scope is a hint, not a lock. Overlap only reports a warning, does not block writing, there is no file lock, concurrency must be split by directory; multiple agents modifying the same file will definitely cause conflicts.

Assigning work and order. Teammates default to fresh context, so assigning work must carry complete context. blocked_by is the only mandatory order mechanism; text status tags cannot be forced or filtered.

Status interpretation and reporting. inactive does not equal completed; send_message success does not equal processing by the other party; only report verified results, do not assume success just because the teammate says so.

Configuration¶

Suitable Scenarios and Considerations¶

Suitable: Multi-angle research culminating in a document, large-scale mechanical modification split by directory, researching and implementing simultaneously with phase dependencies expressed via a task board, adversarial verification.

Not suitable: Single bug diagnosis and fix, design work requiring frequent alignment, multiple agents modifying the same file, database migrations requiring precise order.

The plugin runs with the permissions of the current DSH process and does not add new tools or change runtime behavior. Before installation, check the repository source code and license: package.json marks license as MIT, version 0.1.0, packageManager as pnpm@10.32.1.

Conclusion¶

The value of this plugin lies not in adding new capabilities, but in front-loading the cost of stepping on pits: clearly stating constraints like “slots cannot be reclaimed”, “write scope is a hint not a lock”, and “teammates are fresh context” before the agent starts working. There are only six rules, but they constrain the places where Agent Teams is most prone to problems.

• Directory page: https://www.skillhub.cn/plugins/elfgzp/dsh-agent-team-playbook
• GitHub: https://github.com/elfgzp/dsh-agent-team-playbook