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.md) / [CHANGELOG_CN.md](CHANGELOG_CN.md). ## Install | Host | Command | |------|---------| | dsh (DeepSeek Harness) | `npx @mstar-harness/cli init --target dsh`
(one CLI command that runs two **independent** `dsh plugin --profile web add` installs:
`@mstar-harness/dsh` + `dsh-llm-fallbacks`; `--no-fallbacks` skips the latter)
or `dsh plugin --profile web add @mstar-harness/dsh`
+ `dsh plugin --profile web add dsh-llm-fallbacks` | | 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) ```bash 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 `. 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`](INSTALL.md). CLI flags: [`docs/cli.md`](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 | Command | When | |---------|------| | `/iteration-start [direction] [pause]` | Start a new iteration: Phase 1 (interactive grill-me), then auto-continue Phase 2→5.
`direction` — optional hint (still interactive).
`pause` — stop after Phase 1; resume with `/iteration-drive`. | | `/iteration-drive` | Resume Phase 2→5 on an already-locked iteration. | | `/iteration-loop [direction] [scale]` | Full Phase 1→5 autonomous (no grill-me).
`direction` — optional free text.
`scale` — `S` / `M` / `L` / `XL` (default `M`). | ### Codebase audit | Command | When | |---------|------| | `/codebase-audit [keywords]` | Read-only survey → prioritized, self-contained plans in `{PLAN_DIR}/audit-/`.
Never edits source. Output feeds `/iteration-start` Research or normal Prepare → Execute.
Effort: `quick` / `deep` (default `standard`).
Scope: category focus (`security`, `perf`, `tests`, …); `branch` (current-branch changes only); `next` / `roadmap` (direction candidates only); `simplify` (DEBT-focused deep pass).
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//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 ```mermaid 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`](AGENTS.md). ## License MIT. See [LICENSE](./LICENSE).