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
• Pluggable JSON persistence — coordination docs (status.json, workflow snapshots, project residuals, review envelopes) persist through an ArtifactStore; the default FsStore keeps the existing .mstar/ paths, and integrations mount their own store via MSTAR_STORE_MODULE / --store / in-process setArtifactStore
• Recommended host (best → usable): dsh = omp ≥ ZCode = OpenCode = Cursor > Kimi > Codex

What ships

Release notes: CHANGELOG.md / CHANGELOG_CN.md.

Install

Engine gate checks (Recommended)

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.

init now auto-installs the matching-version CLI globally after a successful run — pass --no-global-cli to opt out.

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 .

Codex agent-link repair and named-role verification: Codex installation.

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: the mstar-use-cli skill.

Use

Three entry shapes: without iteration (single plan / hotfix), with iteration (multi-plan Phase 1–5), or audit, review & verification (discover work, assess changes, or run requested E2E checks).

Full command reference: docs/commands.md.

General (without iteration)

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

Iteration

Scoped plan session

The same command takes a scope, to drive one prepared plan from an independent terminal instead of the whole iteration:

The scoped session binds exactly one plan, drives its tasks through the normal per-plan gates, and stops at a durable handoff: the row keeps InReview, and the coordinator alone records Done — after a verified merge on the iteration route, or straight from the accepted handoff on the standalone development route. A second fresh entry for the same plan is rejected as a duplicate holder — only explicit --resume of the original session continues. Any other nonempty argument shape fails closed; no arguments keep the whole-iteration route above.

The second terminal is transport, not a dependency: any terminal works, and a multiplexer such as Herdr or tmux is optional — nothing reads pane state, TTL or terminal labels for ownership.

The coordinator’s half — prepare, then accept, and from there the iteration route (integration-start → pinned merge → integration-accept → complete) or the standalone development route (complete straight from the accepted handoff), with reconcile as the crash path — runs the mstar plan verbs; flags, JSON envelopes and exit codes: mstar-use-cli → references/plan-and-workflow.md.

Recipe: docs/commands.md.

Audit, review & verification

The audit and review commands are read-only and advisory; findings can become plans for Prepare → Execute. SSOT → mstar-audit (variants: codebase-audit, pr).

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 workflow snapshot"]
    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 workflow snapshot"]
    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 project register"]
    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, workflows/, projects/, sdd/, …) are gitignored; tracked results: {HARNESS_DIR}/AGENTS.md, knowledge/, specs/. Specs resolve .mstar/specs/ → docs/specs/ → repo-root specs/. Repos with a non-default layout can declare every harness directory symbol in a gitignored .mstarc ([config] keys harness_dir / plan_dir / sdd_dir / iteration_dir / knowledge_dir / specs_dir / workflow_dir / project_dir — honored above probing). Details → mstar-conventions.

Maintainers: AGENTS.md.

License

MIT. See LICENSE.