Introduction

In the DeepSeek Harness (DSH) ecosystem, when multiple agents collaborate to handle complex tasks, common challenges include role drift, unverifiable handoffs, and deadlocks. dsh-swarm is a DSH plugin designed to transform this collaboration into a rigorous, evidence-verified delivery pipeline. It converts a requirement into a strictly ordered chain of stages, executed by six dedicated roles, and provides real-time status and delivery evidence through a visual kanban.

Installation and Prerequisites

This plugin is maintained by joekytc and is released under the MIT License. Before installing, ensure that your environment meets the following requirements:

  • DSH runtime: @deepseek-ai/* series
  • Node.js version: ≥ 22.19
  • npm package manager

The installation command is:

dsh plugin --profile web add @joekytc/dsh-swarm

If installing from source, run the build first:

npm install
npm run build
dsh plugin --profile web add .

Core Features

dsh-swarm provides a complete set of process control mechanisms. The core features include:

  • Swarm Mode (Recommended): Converts the main session into a read-only “Team Lead,” which receives requirements, clarifies, plans, and drives execution through natural language.
  • Automatic Intent Recognition: Determines intent from natural language input (development request, retrospective, group notification, or chit-chat), without requiring specific command prefixes to be memorized.
  • Confirmation Gating: Before the pipeline starts, the system saves a checklist. Execution begins only after the user replies with an explicit confirmation phrase (such as “confirm,” “start,” or “go”), preventing accidental triggering.
  • Visual Kanban: Displays pipeline status in real time via the Conversation -> Trajectory -> Kanban path with streaming updates.
  • Machine-Verified Evidence: Each stage handoff must include structured evidence, and completed deliveries are machine-verified.
  • Permission Isolation: The orchestrator (Lead) is read-only and cannot directly modify repository source code or execute git changes; code writing is performed by the executor (D) in an isolated workspace.

Roles and Process

The system defines six single-responsibility roles. Permission matrices and tool surface restrictions ensure clear responsibility boundaries. The pipeline flow is: p -> (pt?) -> w2 -> d -> dt -> w3 -> summary.

Role Responsibility Prohibited Actions
V (Orchestrator) Creates stage cards, drives the pipeline, and handles blockers Execution
P (Planner) Reads specifications and repository facts, and writes the implementation plan Writing code
PT (Plan Reviewer) Performs a read-only review of P’s plan only Modifying the plan
W (Knowledge Officer) Syncs the knowledge base during planning and completion phases Touching code/Git
D (Executor) The only role that writes code; implements, verifies, and commits the feature branch Merging into the target branch
DT (Implementation Reviewer) Verifies D’s delivery using tests, build, type checking, or Diff Read-only repository access

Usage

When using Swarm Mode, the interaction flow is:

  1. State the requirement: Describe the requirement directly in natural language, for example: “Add a role management page to the admin backend, including CRUD and permission checkboxes.”
  2. Confirm execution: The orchestrator will clarify details (such as field definitions, permission sources, etc.) and present a checklist. After the user replies “confirm” or “start,” the pipeline starts.
  3. Real-time query: At any time, ask “What is the progress?” The orchestrator will query the actual status from the kanban and respond, rather than fabricating an answer.
  4. Delivery notification: After completion, you can use the /sms intent to deliver (for example, “Send the current progress to the group”). The system will generate the report based on kanban facts.

Notes

  • Permission restrictions: The main session (Lead) role is designed to be read-only; it cannot modify repository source code or perform git mutations (such as push/commit). The D role handles code commits.
  • Completion threshold: Pipeline completion requires audit confirmation. For the D chain, the system automatically merges the feature branch, but it executes the final cleanup only after ownership is confirmed in the GUI; audit warnings block final packaging.
  • Environment dependencies: Ensure that the DSH runtime, Node.js, and npm versions meet the requirements.

References