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

Installation

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".

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

Morning Star is an Agent Plugin for harness engineering workflows: a TypeScript Harness Workflow Engine (@mstar-harness/engine) enforces deterministic workflow gates, while mstar-* judgment skills drive multi-agent code delivery.

• Deterministic gates, enforced by a TS engine — path/status/lease/dispatch/sdd/iteration/lint gates run in @mstar-harness/engine, not as prompt suggestions
• Judgment stays in mstar-* skills — skills remain the single source of truth (SSOT) for roles, gates, and workflow judgment
• One engine across hosts — the same engine + skills power dsh (DeepSeek Harness), omp, OpenCode, Cursor, Kimi Code, ZCode, and Codex
• Agent Plugin packaging — one-command install; portable across any Agent Plugins v1.0.0 client
• Recommended host (best → usable): dsh = omp ≥ OpenCode ≥ Cursor > Kimi = ZCode > Codex

What ships

Release notes: CHANGELOG.md / CHANGELOG_CN.md.

Install

Engine gate checks (optional)

npm i -g @mstar-harness/cli

Puts the mstar-harness binary (short alias mstar) on PATH, so the engine-check commands the skills cite (mstar status validate, mstar dispatch validate, mstar iteration gate, …) actually run.

Without a global install the harness still works and those checks stay advisory. Set enforcement: hard in an iteration compass to make dispatch preflights fail-fast.

Caution: mstar is a short alias and a shared bin namespace — an unrelated third-party npm package named mstar claims the same command name. The alias exists only where @mstar-harness/cli is installed: bare npx mstar … without the package resolves via the registry to that other tool, and globally co-installing both packages silently overwrites the mstar shim (last install wins). The canonical invocation name stays mstar-harness — use the long name on any conflict.

Verify

npx @mstar-harness/cli doctor --target <opencode\|cursor\|codex\|zcode\|omp\|dsh>.

The repo ships a portable Agent Plugins v1.0.0 manifest (plugin.json) at its root; skills/ is the Agent Skills component — verify it with npx @mstar-harness/cli plugin validate.

Manual install / path layout: INSTALL.md. CLI flags: docs/cli.md.

Use

Three entry shapes: without iteration (single plan / hotfix), with iteration (multi-plan Phase 1–5), or codebase audit (discover what to do).

General (without iteration)

Enter PM, then run the per-plan cycle: Prepare → Execute → QC → QA gate → Done.

Iteration

Codebase audit

Command loading

Phase 2 defaults: per-plan worktree + lease, Findings cleanup: zero-residual. Override only with explicit Worktree mode: waived / Findings cleanup: allow-residual. SSOT → mstar-iteration, mstar-branch-worktree, mstar-plan-artifacts.

Project knowledge bootstrap: mstar-compound-refresh → references/project-knowledge-bootstrap.md.

Harness Workflow

flowchart TD
    A["PM: entry and intent clarification"] --> B{"PM: spec and context ready"}
    B -->|No| C["PM: clarify and refine requirements"]
    C --> B
    B -->|Yes| D["PM: initialize/load HARNESS_DIR and PLAN_DIR"]
    D --> E{"Iteration scope needed"}
    E -->|Deep / first iteration| F["iteration-start: grill-me → compass → review → lock"]
    E -->|Fast autonomous loop| F2["iteration-loop: Phase 1→5 continuous"]
    F --> G["PM: lock compass and create integration branch"]
    F2 --> G
    G --> H["Phase 2→5: execute → close → PR → merge-ready"]
    E -->|No| I["PM: select active plan from status.json"]
    H --> I
    I --> J{"Any plan not Done"}
    J -->|Yes| K["PM: dispatch one plan on a feature branch"]
    K --> L["Dev roles: implement and report"]
    L --> M["PM: update plan and status.json"]
    M --> N["QC trio: review gate"]
    N --> O{"QC decision"}
    O -->|Request Changes| K
    O -->|Approve| P{"QA gate"}
    P -->|mandatory| P1["qa-engineer: acceptance verification"]
    P -->|pm-acceptance| P2["PM: acceptance checklist"]
    P1 --> Q{"Residual findings remain"}
    P2 --> Q
    Q -->|Yes| R["PM/QA: register or accept residuals in status.json"]
    R --> S["PM: mark plan Done and merge to integration branch"]
    Q -->|No| S
    S --> T["PM: sync compass plan status"]
    T --> J
    J -->|No| U["iteration-close: close entry checklist"]
    U --> V["PM: compound round and knowledge index"]
    V --> W["PM: update roadmap and compass completed frontmatter"]
    W --> X["PM: close exit checklist and commit"]
    X --> Y["Phase 4: create PR"]
    Y --> Z["Phase 5: merge-ready loop until CI green and reviews resolved"]

Without iteration: same per-plan gates, no iteration-start / iteration-close wrapper.

Roles and skills

Load mstar-harness-core first, then topic skills on demand (mstar-roles).

Consumer plans default to .mstar/. Process artifacts (plans/, iterations/, status.json, sdd/, …) are gitignored; tracked results: {HARNESS_DIR}/AGENTS.md, knowledge/, specs/. Specs resolve .mstar/specs/ → docs/specs/ → repo-root specs/. Details → mstar-plan-conventions.

Maintainers: AGENTS.md.

License

MIT. See LICENSE.