btspoony / mstar-harness

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

Component	What it is
Harness Workflow Engine	@mstar-harness/engine — TS enforcement of deterministic workflow gates
mstar CLI	@mstar-harness/cli — installer bootstrap + mstar workflow verbs
mstar-* skills	Role, gate, and workflow judgment (single source of truth)
Host adapters	dsh, omp, OpenCode, Cursor, Kimi Code, ZCode, Codex

Release notes: CHANGELOG.md / CHANGELOG_CN.md.

Install

Host	Command
dsh (DeepSeek Harness)	dsh plugin --profile web add @mstar-harness/dsh (the dsh plugin manager — not the CLI)
omp	npx @mstar-harness/cli init --target omp (links ~/.mstar/harness) or omp plugin install github:btspoony/mstar-harness
OpenCode	npx @mstar-harness/cli init --target opencode
Cursor	npx @mstar-harness/cli init --target cursor
Kimi	Kimi TUI: /plugins install https://github.com/btspoony/mstar-harness → /plugins reload
ZCode	npx @mstar-harness/cli init --target zcode then install morning-star-harness in ZCode → Settings → Plugin Management
Codex	npx @mstar-harness/cli init --target codex then codex plugin add morning-star-harness --marketplace personal
Generic (Agent Plugins v1)	point any Agent Plugins v1.0.0 conformant client at this repo root (plugin.json + skills/ are the portable package)

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

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.

Host	Enter PM
dsh (DeepSeek Harness)	pm skill (via the mstar skill provider; no auto-load)
omp	/skill:pm each session (no auto-load)
OpenCode	agent.project-manager (agents/project-manager.md)
Cursor	/pm
Kimi	session auto-loads pm; or /skill:pm
ZCode	/morning-star-harness:pm each session (no auto-load)
Codex	/pm

Iteration

Path	When
/iteration-start	Phase 1 (interactive grill-me) then auto-continues Phase 2→5; pause to stop after Phase 1
/iteration-drive	Resume Phase 2→5 on an already-locked iteration
/iteration-loop	Full Phase 1→5 autonomous (no grill-me; optional direction, scale S|M|L|XL)

Codebase audit

Path	When
/codebase-audit	Survey a repo read-only → prioritized, self-contained improvement plans in {PLAN_DIR}/audit-<date>/

Usage: /codebase-audit [keywords] — read-only advisory, never edits source. Output feeds iteration-start Research or normal Prepare → Execute. Keywords: effort level quick / deep (default standard); scope variant — category focus (security, perf, tests, …), branch (current-branch changes only), next / roadmap (direction candidates only), or simplify (DEBT-focused deep pass over dead / duplicated / speculative / over-built surfaces, with prove-or-reject consumer classification). SSOT → mstar-audit.

Command loading

Host	How commands load
dsh (DeepSeek Harness)	/iteration-start · /iteration-drive · /iteration-loop · /codebase-audit (bundled harness-commands/ via ctx.commands)
omp	/iteration-start · /iteration-drive · /iteration-loop · /codebase-audit (filename commands from plugin commands/)
OpenCode / Cursor	Bundled from commands/ (OpenCode: plugin harness-commands/)
Kimi / ZCode	/morning-star-harness:iteration-start · :codebase-audit (etc.) via plugin manifest
Codex project	.agents/skills/<name>/SKILL.md (CLI symlinks from commands/)
Codex global	Project-scoped commands not installed — use --scope project

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

Agent ID	Responsibility
project-manager	Routing, assignment, phase progression
product-manager	Requirements, product planning, research
architect	Architecture and technical contracts
fullstack-dev / fullstack-dev-2	Backend-led implement / second parallel track
frontend-dev	UI, interaction, frontend performance
qa-engineer	Acceptance when QA gate: mandatory
code-reviewer	SDD per-task review; codebase audit (audit category)
qc-specialist / -2 / -3	QC trio
ops-engineer	Deploy, monitoring, infrastructure
writing-specialist	Docs, fiction, copy, scripts
prompt-engineer	Prompt / skill / rule work

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

Skill	Purpose
mstar-harness-core	Entry, state machine, Task category, skill index
mstar-phase-gates	Prepare/Execute, clarify, hotfix
mstar-iteration	Phase 1–5 iteration lifecycle
mstar-dispatch-gates	Dispatch, Delegation, anti-recursion
mstar-sdd	Subagent-driven development
mstar-branch-worktree	Branches, worktrees, QC/QA checkout
mstar-plan-conventions	{HARNESS_DIR} discovery / init
mstar-plan-artifacts	Plans, status.json, residuals, Findings cleanup
mstar-design-md	DESIGN.md gate for UI plans
mstar-review-qc	PM QC tri orchestration
mstar-coding-behavior	RCA, test-first, review feedback, evidence
mstar-compound / mstar-compound-refresh	Knowledge crystallize / maintain
mstar-strategy	STRATEGY.md alignment
mstar-skill-authoring	General skill authoring (SkillsBench gate)
mstar-audit	Read-only codebase audit → prioritized improvement plans
mstar-roles	Role prompts + load lists
mstar-host	Host adapters (dsh / omp / OpenCode / Cursor / Kimi / ZCode / Codex)
pm	/pm / /skill:pm / host PM entry

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.