dsh-team-superflow

Readme

# dsh-team-superflow

**A fixed five-member development team · driven by the spec-superflow state machine · live progress in the Web GUI**

Spin up the same fixed dev team every time you use AgentTeams in DeepSeek Harness: a captain (the current session) plus five members, with the team's work flowing through spec-superflow's eight workflow states, visualized as a stepper in the activity panel.

Refactored from [NanmiCoder/dsh-agent-teams](https://github.com/NanmiCoder/dsh-agent-teams), integrating the state-machine model of [MageByte-Zero/spec-superflow](https://github.com/MageByte-Zero/spec-superflow).

## Demo

<p align="center">
  <img src="./assets/demo1.png" alt="Demo 1" width="100%">
</p>

<p align="center">
  <img src="./assets/demo2.png" alt="Demo 2" style="max-width: 420px; width: 100%;">
  <img src="./assets/demo3.png" alt="Demo 3" style="max-width: 420px; width: 100%;">
</p>

## Fixed roster

Every `agent_teams_create` registers the same five members (subagents spawn lazily on their first phase-eligible dispatch):

| member | role | active phases |
| --- | --- | --- |
| spec-writer | spec writer | exploring · specifying · bridging |
| architect | designer / architect | specifying · bridging |
| engineer | engineer | executing · debugging |
| reviewer | reviewer | executing · debugging |
| docs | release / docs | executing · closing |

## State machine

The team record persists the spec-superflow eight-state workflow:

```text
exploring → specifying → bridging → approved-for-build → executing ⇄ debugging → closing
                                    │
                                    └─ build gate: HUMAN approval before executing
(any non-terminal state) ─────────→ abandoned (terminal)
```

- **Auto-advance**: when every task of the current phase completes, the team moves to the next phase (`phaseAutoAdvance`, default on).
- **Build gate (human review)**: implementation freezes at `approved-for-build` until a human reviews the execution-contract artifacts and clicks 「批准构建」 in the Web panel. The model cannot confirm the gate itself.
- **Rewind**: the captain may move back to `specifying` (scope change) or `bridging` (contract drift); a bug moves `executing → debugging` and returns automatically after fixes.
- **Phase-tagged tasks**: `agent_teams_create_task` tags each task with a phase (default: current); the scheduler only dispatches tasks matching the current phase and the member's role scope.

The activity panel adds a **state-machine stepper** (eight phase pills, overall percent, per-phase task counts, build-gate badge) refreshed from the durable host state.

## Install

> Requires [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

### Method A: install straight from a git repo (recommended; GitHub or Gitee)

```sh
dsh plugin --profile web add https://gitee.com/quella01/dsh-team-superflow.git
# dsh plugin --profile web add https://github.com/fengbin01/dsh-team-superflow.git
```

### Method B: clone and link locally (edit code, changes apply as you rebuild)

```sh
git clone https://gitee.com/quella01/dsh-team-superflow.git ~/dsh-team-superflow
dsh plugin --profile web add link:~/dsh-team-superflow
```

### Method C: npm package (after publishing; not published yet)

```sh
dsh plugin --profile web add dsh-team-superflow
```

## Usage

Natural language:

> Use AgentTeams to add a dark mode to this repo, following spec → contract → implement → review.

Or the slash command:

```
/agent-teams refactor the auth boundary and produce the full execution contract and tests
```

## Tools

| Tool | Capability |
| --- | --- |
| `agent_teams_create` | Create a team: registers the fixed five-member roster, starts in exploring, and materializes the spec-superflow artifact directory |
| `agent_teams_add_member` | Add an extra member beyond the fixed roster (optionally scoped to workflow phases) |
| `agent_teams_remove_member` | Safely remove a member: revoke its open tasks, interrupt its turn, mark it removed |
| `agent_teams_create_task` | Create a phase-tagged task with dependencies (defaults to the current phase; blocked until deps complete) |
| `agent_teams_reassign_task` | Atomically retry/reassign/take over a task, revoking the old attempt so late results cannot overwrite |
| `agent_teams_claim_task` | Claim one ready task and receive the `attempt_id` capability |
| `agent_teams_update_task` | Advance task status/output; when every current-phase task completes, the team auto-advances |
| `agent_teams_send_message` | Direct captain/member messaging through durable mailboxes |
| `agent_teams_status` | Read the current phase, per-phase progress, member activity, tasks, artifacts, and build-gate state |
| `agent_teams_advance_phase` | Advance/rewind the state machine (debugging, re-bridge, re-specify, abandon); the build gate requires HUMAN approval in the panel |
| `agent_teams_delete` | End the team and archive it (tasks, mailboxes, artifacts, and phase history kept under `archive/`) |

## Configuration

```yaml
- id: agent-teams
  config:
    stateDir: .agent-teams
    memberProvider: spawn
    memberModel: deepseek-v4
    memberMaxDepth: 1
    maxMembers: 8
    fixedRoster: true          # false → original behavior (empty team)
    phaseAutoAdvance: true
    promptSectionOrder: 117
    slashCommand: true
```

## License

MIT