Preface¶

When writing code with agents, the most common problems often stem not from “whether you can modify files”, but from the workflow itself being unstable. Things like starting to code halfway through a plan, verbal QC approval, status.json not matching the real branch, and recursive subagents getting stuck—these issues can only be reminded via prompts, and the model can always bypass them.

DeepSeek Harness (dsh) turns models, tools, skills, sessions, and workflows into replaceable plugins. The official repository’s original wording is everything is a plugin. The community directory DeepSeek Harness Plugin Repository is an independent site not affiliated with DeepSeek / Fangxin, used to discover such plugins. The directory lists mstar-harness under “Development & Runtime”, maintained by btspoony.

This article is organized after cross-checking the plugin directory page, GitHub repository README / README_CN.md, plugin.json, packages/dsh documentation, CHANGELOG, and the official deepseek-ai/deepseek-harness: what it is, how the gatekeeping works, how to install it on dsh, and how to use its three entry points.

What It Is¶

The product name of mstar-harness in the repository is Morning Star. It is an Agent Plugin for harness engineering workflows: the TypeScript engine @mstar-harness/engine enforces deterministic gatekeeping, and mstar-* skills handle roles, gatekeeping judgments, and workflow orchestration. The directory page’s introduction describes it as “a skill-driven intelligent agent plugin for Harness/Loop engineering workflows”.

The repository belongs to GitHub user btspoony, the author in the root manifest plugin.json is Bohao Tang, and the plugin package name is morning-star-harness. The license is MIT, and the primary language is TypeScript. The GitHub repository has the dsh-plugin topic. As of the verification on 2026-08-17, the repository has 46 stars, and the latest release tag is v2.3.0 (2026-08-16); the root manifest, CLI, engine, and @mstar-harness/dsh are all aligned to this version.

The problem it aims to solve can be summed up in one sentence: turn “looking like a workflow” into “the engine actually blocks invalid operations”. Gatekeeping runs in TypeScript, not just written in prompts. The judgment rules still take mstar-* skills as the single source of truth (SSOT). The same set of engines and skills can also be connected to omp, OpenCode, Cursor, Kimi Code, ZCode, and Codex; the recommended host order given in the README is dsh = omp ≥ OpenCode ≥ Cursor > Kimi = ZCode > Codex. This article only elaborates on the dsh integration.

Core Features¶

The current repository delivers four components:

Engine Enforces Rules, Judgments Stay in Skills¶

The README clearly defines the boundary: deterministic gatekeeping is executed by the engine; how roles are divided, when to pass the gate, and how to close iterations are still subject to the skill text. The dsh-specific package @mstar-harness/dsh is a cordis function plugin that mounts the engine into the current process, implements HostAdapter (host: 'dsh'), does not modify dsh’s built-in tools themselves, and only uses the rejection/consultation channel on the seam.

After mounting, the capabilities listed in the packages/dsh documentation include:
- Status Gatekeeping: Validates writes to {HARNESS_DIR}/status.json.
- Dispatch Gatekeeping: Validates Assignment text (fields, anti-recursion, default branch) before executing subagent / subagent_fork, plus dsh-side lease and worktree checks.
- Skill and Artifact Linting: Performs engine-level checks on writes to SKILL.md under the mounted skill root, as well as DESIGN.md, audit plans, knowledge documents, etc.
- Bundled Commands: Registers /iteration-start, /iteration-drive, /iteration-loop, /codebase-audit to ctx.commands.
- Catalog Line: Appends an mstar-engine-status entry to each combined agent step, with version, harness directory, enforcement, and summaries of plan / residual / branch / lease, etc.
- Web Workflow Panel: The CHANGELOG states that the web client will mount a “MStar Workflow” panel, which uses catalog evidence to draw phase loops and plan state machines.

The default mode is warn-only: violations will generate logs and advisories, and actions will continue. To enable true blocking, you need to set enforcement to hard in the iterative compass, Assignment header, or plugin configuration. The documentation also notes that status / skill linting will allow repair writes for “already invalid files” in hard mode, to avoid getting stuck on file repairs due to gatekeeping.

Three Workflow Entry Points¶

The README summarizes usage into three modes, which share the same per-plan gatekeeping when not running iterations:
1. No Iteration: Enter PM, then advance a single plan or hotfix through Prepare → Execute → QC → QA gate → Done.
2. Run Iteration: Phase 1–5, from direction locking, compass, integration branch, to execution, closure, PR opening, and merge-ready status.
3. Codebase Audit: Read-only scan that produces a prioritized improvement plan without modifying source code.

The consumer’s plan defaults to landing in .mstar/. Process artifacts (plans/, iterations/, status.json, sdd/, etc.) are gitignored by convention; what is tracked in the repository are {HARNESS_DIR}/AGENTS.md, knowledge/, specs/.

Roles and Skills¶

First load mstar-harness-core, then load specialized skills on demand via mstar-roles. The roles include: project-manager (routing, dispatching, phase advancement), product-manager, architect, fullstack-dev / fullstack-dev-2, frontend-dev, qa-engineer, code-reviewer, three reviewers for qc-specialist, ops-engineer, writing-specialist, prompt-engineer.

Skills directly related to the workflow also include: mstar-phase-gates, mstar-iteration, mstar-dispatch-gates, mstar-sdd, mstar-branch-worktree, mstar-plan-artifacts, mstar-review-qc, mstar-audit, mstar-host, and the PM entry skill pm on dsh.

Installation and Activation¶

First, you need to have DeepSeek Harness. The current startup method for the official repository is:

npx @deepseek-ai/dsh web

The official README notes that the project is still in developer preview, with breaking changes to be expected. The Web UI defaults to http://127.0.0.1:3080.

The installation command given on the community directory page is:

dsh plugin add github:btspoony/mstar-harness

For reproducible installations, the directory page recommends pinning the commit hash at the end (replace commit with the actual hash):

dsh plugin add github:btspoony/mstar-harness#commit

The repository’s own installation instructions differ slightly from the directory page, so we take the repository README as the primary source. dsh does not use npx @mstar-harness/cli init (this CLI has no dsh target, only covering omp / OpenCode / Cursor / Kimi / ZCode / Codex). On dsh, the README and @mstar-harness/dsh documentation recommend using the host’s built-in profile bundle:

dsh plugin --profile web add @mstar-harness/dsh

This is the npm release form, currently aligned with repository release 2.3.0, and no additional build is required during installation. For local plugin modifications, enter packages/dsh and run dsh plugin --profile web add ., and first execute bun run build.

Role-based subagent persona configuration is an optional feature, and the documentation requires installing it via a separate second command, not bundling it into the mstar bundle itself:

dsh plugin --profile web add dsh-llm-fallbacks

Without this package installed, the mstar plugin can still start; the persona will fall back to the harness-agents/ mirror inside the package or the plugin configuration.

The security prompt on the directory page should be read carefully: the plugin runs with the permissions of the current dsh process, and may execute code during installation. Check the source code repository and MIT license before installing.

Typical Usage¶

The PM does not load automatically on dsh. The README states that you use the pm skill via the mstar skill provider. Iteration commands are already included in harness-commands/: when selected in the web client, they will pre-fill the input box with /command name with parameter hints, and you press Enter to submit.

1. Single Plan / Hotfix: No Iteration¶

After entering PM, select an active plan from status.json, and walk through the process in order: Prepare → Execute → QC → QA → Done. QC defaults to three reviewers; when QA gate: mandatory, the qa-engineer will conduct acceptance testing, otherwise the PM can close the loop based on the acceptance checklist. If there are remaining findings, they must be registered in status.json or explicitly accepted, and cannot be marked as Done silently.

2. Multi-Plan Iteration¶

All three commands come from the repository README and commands/:

/iteration-start [direction] [pause]
/iteration-drive
/iteration-loop [direction] [scale]

• /iteration-start: Phase 1 conducts an interactive grill-me session, locks the compass and integration branch, then automatically enters Phase 2→5 by default. Adding pause will stop at Phase 1, and you can resume with /iteration-drive later.
• /iteration-drive: Resumes Phase 2→5 on a locked iteration.
• /iteration-loop: Fully automates Phase 1→5 without a grill-me session; optional direction and scale S|M|L|XL.

Phase 2 defaults to one worktree and lease per plan, with Findings cleanup: zero-residual. You can only override these two rules by explicitly writing Worktree mode: waived or Findings cleanup: allow-residual.

3. Read-Only Audit: Figure Out What to Do First¶

/codebase-audit [keywords]

The documentation emphasizes that this is a read-only advisor and does not modify source code. The output is written to {PLAN_DIR}/audit-.../, which can be fed into the Research phase of /iteration-start or go through the normal Prepare → Execute workflow.

Keywords follow the README:
- Depth: quick / deep (default standard)
- Category: security, perf, tests, etc.
- Scope: branch (only current branch changes), next / roadmap (only direction candidates), simplify (focus on technical debt: dead code, duplication, speculative, over-engineering)

Applicable Scenarios and Notes¶

It is most suitable for users who are already using the dsh web profile and want to turn multi-agent delivery into a inspectable state machine: those who require plan registration, branch / worktree management, QC triple review, QA gatekeeping, and hope to leave engine-level evidence when violations occur. The repository lists itself alongside omp as a recommended host, and the catalog line and workflow panel on dsh make the information more complete than pure skill text.

Before using, you should pay attention to these boundaries:
1. The plugin runs with the same permissions as the current dsh process, and can read/write the workspace and intercept tool calls. Do not install it if you do not trust the source code.
2. DeepSeek Harness is still in developer preview, and mstar’s @deepseek-ai/dsh-* peers are also aligned to the rc channel. After upgrading dsh, recheck compatibility based on the repository CHANGELOG and @mstar-harness/dsh documentation.
3. The default enforcement mode is alert only, not hard blocking. To truly block dispatches, you must explicitly enable hard mode.
4. {HARNESS_DIR} is detected from the session workspace root (.mstar/ → .agents/ → .plans/ → plans/), and will not traverse upward from the startup cwd to ~/.mstar. If the repository root does not use these names, set harnessDir in the plugin configuration.
5. The github:btspoony/mstar-harness from the directory page and @mstar-harness/dsh from the README are two different installation paths. On dsh, prioritize using the profile bundle per the current repository documentation; if using the directory page command, confirm that the actual installed package matches your expectation after installation.

Summary¶

mstar-harness is not just another set of “please follow these steps” prompt collections. It turns gatekeeping rules like path, status, lease, and dispatch into a TypeScript engine, leaves judgment logic in mstar-* skills, and provides PM entry, iteration commands, read-only audit, and a Web workflow panel on dsh. The current public release is 2.3.0, under the MIT license.

Directory page: https://deepseek-harness-plugin.com/en-US/plugins/mstar-harness/

GitHub: https://github.com/btspoony/mstar-harness