# mstar-harness

> Add the Morning Star multi-agent collaboration framework to DeepSeek

## Metadata

- Author: [@btspoony](https://github.com/btspoony)
- Repo: <https://github.com/btspoony/mstar-harness.git>
- GitHub: [btspoony/mstar-harness](https://github.com/btspoony/mstar-harness)
- Stars: 52
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `cursor-plugin`, `dsh-plugin`, `harness-engineering`, `knowledge-management`, `omp-plugin`, `opencode-plugin`, `sdd`, `spec-driven`, `subagents`
- Forks: 3
- Open Issues: 0
- Last push: 2026-08-20T11:30:51.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:btspoony/mstar-harness
```

## Wiki

## At a Glance

This is the dsh (DeepSeek Harness) host plugin for Morning Star (启明星) multi-agent collaboration framework. It hooks a state-machine-based workflow engine into dsh: automatically validates at key nodes such as writing harness state files, dispatching sub-agents, and modifying skill documents, while rendering a visualized workflow panel on the right side of the dsh conversation window.

## Core Features

- **Guard harness state file writes**: Intercepts write requests to `{HARNESS_DIR}/status.json`, performs completeness validation and residual cleanup checks based on the current document, and returns decisions through dsh's rejection channel when violations are detected
- **Validate sub-agent dispatching**: Intercepts subagent / subagent_fork tool calls, determines if the dispatch is legal according to workflow constraints; in "hard constraint" mode, can reject non-compliant dispatches (including anti-self-recursion checks)
- **Auto-inject role personas**: Listens to dsh sub-agent startup events, injecting the corresponding role's description as a system prompt fragment into the sub-agent context
- **Mount skills directory**: Mounts mstar's `skills/` as an independent skill provider to dsh, enabling dsh to recognize and invoke mstar-* series skills
- **Output engine status directory**: Before each model inference, appends a line of `mstar-engine-status` summary to the conversation context (including iteration phase, current plan, remaining items, compliance policy, etc.)
- **Expose four workflow slash commands**: Registers `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/codebase-audit`, allowing multi-plan iteration start/resume without leaving dsh
- **Render "MStar Workflow" panel on the right side of conversation window**: Displays current iteration phase, plan kanban, and agent flow status in canvas form

## Technical Implementation

- **Language**: TypeScript
- **Key Dependencies**: @deepseek-ai/cordis (plugin container), @mstar-harness/engine (shared workflow engine), @deepseek-ai/dsh-skill-filesystem (skill mounting channel), schemastery (configuration validation)
- **Architecture Pattern**: dsh cordis extension plugin (named export + apply hooks), working through four dsh official extension surfaces: fs write interception, tool pre-execution interception, sub-agent startup events, and agent pre-inference directory injection, with zero dsh core modifications
- **Entry Point**: packages/dsh/src/index.ts (DSH sub-package); root package.json main points to packages/opencode/src/mstar.ts (OpenCode host entry, not involved in this plugin)

## Use Cases

Multi-agent projects using dsh (DeepSeek Harness), requiring multiple agents (PM, QC, QA, Developer roles) to collaborate according to a consistent state machine and phase gates. Current pain point: dsh's built-in dispatch tool only handles "dispatch an agent to work", with no guarantee that each dispatch conforms to the overall plan's workflow constraints; after installing this plugin, all dispatches and state writes are pre-audited by the engine, with current progress visualized.

## Prerequisites and Compatibility

| Dependency | Min Version | Description |
|---|---|---|
| DSH | 0.1.0-rc.7+ | Plugin strongly depends on dsh-agent / dsh-client-runtime / dsh-client-ui-conversation / dsh-client-ui-slots / dsh-client-locale / dsh-commands / dsh-fs / dsh-invariants / dsh-jobs / dsh-llm / dsh-skill / dsh-skill-filesystem / dsh-tools and other host packages, with dsh-base + dsh-web-app layer required in profile |
| @deepseek-ai/cordis | ^4.0.1 | dsh's plugin container, provided by the host |
| Bun (build time only) | >=1.2.17 | Used by plugin developers when building from source; users installing pre-built artifacts from npm do not need it |
| Runtime Node | Determined by dsh host | Plugin does not independently declare Node version |
| dsh-llm-fallbacks | Optional ^0.2.0 | Only needed when using mstar role seeding with fallbacks model routing linkage, install separately |
| Platform | Cross-platform | Server runs in dsh Node process; browser side loads via dsh web profile |

## Installation

```bash
dsh plugin --profile web add github:btspoony/mstar-harness
```

> Installation command format is defined by dsh official plugin specification; the above command adds `@mstar-harness/dsh` to web profile's bundle list and automatically rebuilds mounts. One-liner CLI installation also available: `npx @mstar-harness/cli init --target dsh`, which automatically installs `dsh-llm-fallbacks` as well.

## Configuration Options

All fields are optional; omitted fields work with "hardcoded defaults" or "runtime detection".

| Config | Type | Description | Default |
|---|---|---|---|
| `harnessDir` | string | Explicitly specify harness root directory. Not needed if your project uses auto-recognized directory names like `.mstar/`; must specify manually if using unconventional names (e.g., `.harness/`) | Runtime detection from session workspace (tries `.mstar/`, `.agents/`, `.plans/`, `plans/` in order) |
| `enforcement` | `hard` / `soft` | Global enforcement override. `hard` makes dispatch gate truly reject; `soft` forces warnings only (even if iteration guide declares hard constraints). Generally no need to change | Follows iteration compass metadata; all warnings if no compass |
| `dispatchTools` | string array | List of tool names to intercept at dispatch gate | `["subagent", "subagent_fork"]` |
| `dispatchBinding` | string | The mstar role corresponding to current dsh session (e.g., `fullstack-dev`), used for anti-self-recursion pre-check: prevents agent from dispatching "itself" | Skips self-recursion check if not configured |
| `skillRoots` | string array | Extra skill root directories, recognized as "project-level" by dsh skill filesystem | None (only mounts plugin's built-in skills) |
| `bundledSkillDir` | string | Custom "built-in" skill root directory. Absolute paths take priority; relative paths resolved from dsh startup directory | Plugin package's built-in `harness-skills/` mirror (relative path within package, not affected by startup directory) |
| `catalogTtlMs` | number | Refresh interval for engine status directory (milliseconds) | 60000 |
| `roleMap` | object | mstar role name → dsh-llm-fallbacks role name mapping table, currently only used for logging | None |
| `rolePersonas` | object | mstar role name → custom persona text. Injected as system prompt fragment when sub-agent starts. **Note: content must not contain paired `{{` and `}}`, otherwise validation fails at startup** | Uses plugin package's built-in `harness-agents/` defaults |
| `workflowGate` | `off` / `warn` / `ask` / `hard` | Workflow/ralph tool compliance gate mode. `warn` only warns; `ask` routes first-time new workflows through dsh approval; `hard` directly intercepts non-compliant calls | `warn` |
| `workflowNames` | string array | Allowlist of workflow names considered "known". Empty/unconfigured ⇒ all treated as unknown (defaults to not allow) | Unconfigured |
| `maxGoalRounds` | number | Maximum round limit for goal service (hard boundary for autonomous iteration phase) | 256 |

## FAQ

**Q: Did installation slow down dsh startup?**

A: Minimal impact. Engine status directory refreshes every 60 seconds by default; hot path only does timestamp comparison and Map lookup; harness files are only re-read on first access or cache expiration.

**Q: Will the dispatch gate "kill" my legitimate dispatches?**

A: Default is `warn` mode, only warns without blocking; real rejection only happens when you explicitly enable `Enforcement: hard` in the iteration compass, or write `enforcement: hard` in config. Interceptions in hard mode include specific reasons; just modify according to the feedback.

**Q: How do I configure anti-self-recursion pre-check to take effect?**

A: Add `dispatchBinding: '<mstar role name that initiates dispatch>'` to the plugin's `mstar` line in your dsh config, for example `dispatchBinding: fullstack-dev`. Skips pre-check if not configured, won't report false positives.

**Q: I see a new "MStar Workflow" tab in dsh, how do I turn it off?**

A: It comes from the plugin package's browser-side client bundle (`packages/dsh/src/client/`), auto-loaded by dsh web profile. If you don't need it, just remove `@mstar-harness/dsh` from the profile and restart dsh.

**Q: Can I modify the plugin's role personas or skills directory?**

A: Yes. Two ways: edit the cordis.patch.yml at dsh profile level, adding `rolePersonas` / `bundledSkillDir` overrides to the `mstar` line's `config`; or modify the `skills/` / `agents/` in the repository root and run `bun run bundle-assets` to repackage.

**Q: Error "persona contains {{...}}" - what do I do?**

A: dsh's system prompt renderer does strict variable interpolation on `{{` and `}}`; paired curly braces in your `rolePersonas` text will be rejected. Change double braces to single braces, or rewrite differently; isolated `{{` (without matching `}}`) is safe.

**Q: Conflicts with dsh upgrades?**

A: No. Plugin does not modify dsh core; after dsh upgrade, just `bun run build && dsh plugin --profile web add .` to remount (or re-`add` the remote version). If upgrading from dsh versions before 0.1.0-rc.7, may need to upgrade dsh first.

## Learning Curve

Advanced — Requires understanding of mstar's state machine concepts (`{HARNESS_DIR}/status.json`, iteration compass, QC/QA gate); most users can install and use immediately, but enabling "hard constraints" to actually work requires reading and understanding compass metadata.

## Known Issues and Limitations

- State file write interception is "content-blind": fs write events only carry target path and agent, not new content, so "writing a good document to bad" cannot be intercepted on that write; fix by manually reverting to correct format, or deleting status.json to let harness rebuild
- Anti-self-recursion pre-check depends on `dispatchBinding` config: skipped if unconfigured, multi-role dispatchers need separate config deployment for each role
- Built-in skills mirror is synced at build time: if installing from source without running `bun run bundle-assets`, no built-in skills or commands exist, but no error will be shown
- `{{` and `}}` content cannot be written in `rolePersonas`, otherwise plugin mount phase will be rejected by schemastery validation
- When gating `workflow/ralph` tool calls, unconfigured `workflowNames` is equivalent to "all unknown", so first run of new workflows will be flagged
- Content-blind skill lint has the same blind spot: fs write events don't carry content, so "first creation of non-compliant content" or "good document overwritten" cannot be intercepted
- `lintSkillWrite` hard-intercept error class is implemented but current dsh lacks "content-carrying" skill write hooks, so can only give warnings in "repair escape" form
- Role→model automatic routing feature not delivered: current plugin only injects personas, does not modify sub-agent model selection; that capability depends on upstream interfaces
- design-md name matching is global basename matching (any `DESIGN.md` in any directory triggers design system validation), which may produce noisy warnings for unrelated projects

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [mstar-harness](https://deepseek-plugin.org/plugins/btspoony/mstar-harness)
Wiki generated by AI (model: `MiniMax-M2.7`)