mstar-harness

Morning Star

Harness Workflow Engine · Agent Plugin

English / 中文

GitHub · Issues

Morning Star brings a delivery process to the AI coding tools you already use — dsh, omp, OpenCode, Cursor, Kimi Code, ZCode, and Codex. You describe what you want; a project-manager agent clarifies the request, keeps a plan, and carries the work from requirements through implementation, review, and acceptance to a pull request. Requirements, architecture, implementation, review, acceptance, and audits each go to a role that owns that part.

Why use it

• From request to pull request — describe the work once; the PM keeps the plan, brings in the right specialists, and drives everything to a pull request. If work stops partway, the plan records where it left off so the work can resume later.
• Specialists instead of one long prompt — a PM orchestrates; separate roles own requirements, architecture, implementation, QC, acceptance, audits, and ops, each with a narrow brief.
• A trail you can audit — plans, findings, review reports, and decisions are recorded under the harness directory in your repo, not just in the chat.
• Boundaries are explicit — the workflow opens pull requests and records a merge policy when an iteration starts. Under reviewed-auto only a settled, posted ship it review report at the current PR head authorizes the merge; under owner-gated it stops at merge-ready and waits for your written approval. A policy that was never recorded returns the run to Phase 1 rather than defaulting to either. Audits read and report, and anything that touches a real environment needs your explicit authorization.

Install

Every host installs two ways: this CLI's init flow, or the host's own plugin manager — the native command installs the plugin only. Options, path layout, and host notes: INSTALL.md.

• dsh (DeepSeek Harness) — needs the dsh CLI on PATH
• CLI: npx @mstar-harness/cli init --target dsh
• Native: dsh plugin --profile web add @mstar-harness/dsh
• omp — needs the omp CLI installed
• CLI: npx @mstar-harness/cli init --target omp
• Native: omp plugin install @mstar-harness/omp
• OpenCode
• CLI: npx @mstar-harness/cli init --target opencode
• Native: @mstar-harness/opencode for OpenCode 1.x, @mstar-harness/opencode-v2 for OpenCode 2.x — add it to the plugin list in opencode.json, then restart OpenCode
• Cursor — needs git
• CLI: npx @mstar-harness/cli init --target cursor
• Native: git clone https://github.com/btspoony/mstar-harness.git ~/.cursor/plugins/local/morning-star-harness, then Developer: Reload Window
• Kimi Code — no CLI target
• Native: /plugins install https://github.com/btspoony/mstar-harness, then /plugins reload
• ZCode
• CLI: npx @mstar-harness/cli init --target zcode
• Native: add https://github.com/btspoony/mstar-harness as a ZCode plugin marketplace, then install morning-star-harness
• Codex — needs the codex CLI
• CLI: npx @mstar-harness/cli init --target codex
• Native: codex plugin marketplace add btspoony/mstar-harness --ref main, then codex plugin add morning-star-harness@mstar-repo

Use

Enter the PM once per session, then describe the work in your own words; the PM runs the process in that session.

Host · Enter PM dsh · pm skill omp · /skill:pm OpenCode · Project Manager agent, or /pm Cursor · /pm Kimi Code · auto-loads in a session, or /skill:pm ZCode · /morning-star-harness:pm Codex · /pm

Single task (no iteration)

Give the PM a concrete request — for example, *"Add rate limiting to the public API and cover it with tests."* The PM clarifies the gaps, writes a plan, runs the work on a feature branch, and drives it through implement → independent QC review → acceptance → done. Confirmed problems that are not fixed in this round are captured as issues instead of being dropped. You review the result and merge.

Iteration

Command · When /iteration-start [direction] [pause] · Phase 1: an interactive direction lock (grill-me) that produces the iteration's compass and plans, then continues automatically through execution, close, pull request, and merge-ready. pause stops after Phase 1; continue with /iteration-drive. /iteration-drive · Resume or advance an already locked iteration. Takes no arguments. /iteration-loop [direction] [scale] · The same lifecycle end to end without the interactive phase. scale (S / M / L / XL) caps how many plans the iteration takes on.

An iteration ends only after its post-merge close: a closed phase, an open pull request, or a merged pull request is not completion by itself. Command spelling differs per host — some hosts require a plugin prefix, and Codex installs the command skills at project scope only; argument forms and per-host details are in docs/commands.md.

Audit, review & verification

Command · When /codebase-audit [keywords] · Read-only survey that produces prioritized, ready-to-execute improvement plans; narrow it with a category focus (bug, security, perf, tech-debt, …). /amazing-pr-review [pr\ · branch] [quick\ · default\ · deep] · Pre-merge review of a PR or branch at three strengths, ending in one verdict — ship it, needs fixes, or blocked from the finding tally on a settled run (completed without a stop, every required domain opened, the resolved diff basis readable and complete), or the single derived incomplete on exactly three conditions — the run stopped before synthesis, a required domain seat never opened, or the resolved diff basis could not be read. A wall-clock overrun is not one of them: a fully covered run past its budget publishes its tally-derived verdict and declares the overrun as a note. /amazing-test-audit [scope] [quick\ · deep] [campaign] · Read-only audit of the test surface → plans to delete, repair, consolidate, or relocate tests. /amazing-e2e-check [environment] [scenarios] · Runs browser, device, or installed-deployment scenarios you explicitly asked for, in a separate workflow.

The audit commands read and report; they do not edit your code. Two boundaries to know: /amazing-pr-review posts its findings to GitHub as a comment review when you give it a pull-request number — it never approves, requests changes, or merges — and /amazing-e2e-check runs only when you ask for it, with steps that touch a real environment requiring explicit authorization.

Workflow

flowchart TD
    A["You describe the work"] --> B["PM clarifies it and writes the plan"]
    B --> C["Implement on a feature branch"]
    C --> D["Independent review"]
    D -->|changes requested| C
    D --> E["Acceptance by QA or the PM, with its own evidence"]
    E -->|not accepted| C
    E --> F{"Iteration with plans still to run?"}
    F -->|yes: next plan| C
    F -->|no| G["Wrap up: record results and issues, keep reusable lessons"]
    G --> H["Open the pull request"]
    H --> I["CI checks and review feedback"]
    I --> J{"All green and reviews resolved?"}
    J -->|no: fix, verify, push| I
    J -->|yes| K["Merge-ready"]
    K -->|per its merge policy §5.3, or your approval| L["Merge"]
    L --> M["Verify the merge, then close the delivery"]

The main path shows a development delivery. Every plan gets a plan-level QC review — three independent seats by default — and a multi-task plan adds a per-task review during implementation. A hotfix — or a plan explicitly set to run inline — takes a lighter route with fewer review seats. Acceptance is a separate pass with its own evidence — QA or the PM — not a re-read of the implementer's summary, and confirmed problems that this round does not fix become tracked issues instead of being dropped.

Scope notes. An iteration locks its direction with you first, then runs the per-plan cycle for every plan it takes on and closes out once before its pull request; without an iteration, the cycle runs for a single plan. A verification or report-only deliverable — an audit, for example — ends at its agreed completion, with no pull request or merge. On the development path, a plan is complete only with its evidence: plan completion, merge-ready, and merged are three different facts, and only a verified merge, followed by the post-merge close, ends the delivery. Merging is a separate authorization with one recorded source: under owner-gated you approve it or merge yourself, and under reviewed-auto the recorded policy supplies it only through a settled, posted ship it report at the current PR head — not the mere existence of a review. An iteration that never recorded a policy returns to Phase 1 instead of falling back to either. Branch cleanup stays a separate, explicit step.

The engine checks the mechanically checkable parts of this process — workflow state transitions, branch and worktree alignment, dispatch preconditions, plan and issue bookkeeping. These checks are advisory by default: they report problems, and a project or iteration can opt into blocking enforcement with enforcement: hard; whether a violation can actually block depends on the host. Process state (plans, workflow records, findings, review reports) lives in the harness directory, .mstar/ by default, which the scaffold's canonical .gitignore snippet ignores — the installer does not touch .gitignore.

Dashboard

A read-only page on 127.0.0.1, for this machine only, that brings project progress, open issues, and the roadmap into one view for the repository you start it from. It has Issues, Workflows, Iterations, and Roadmap; on Issues you can search and filter, open an issue's recorded history, and read the issue flow — a cumulative trend of issues captured versus retired. Nothing on the page writes; changes go through the CLI.

mstar-harness dashboard

The command prints a one-line JSON result. Open data.url (http://127.0.0.1: plus the port it actually bound) and press Ctrl-C to stop. --port and --project are optional; omit --port and the OS chooses. The page does not push live updates.

Details: docs/runtime-reference.md.

MCP

From a coding tool that supports MCP, look up issues, the roadmap, and workflows, and run the matching CLI operations and checks, without writing a shell command. mstar-harness mcp is the stdio server in this package. It follows the same rules as the CLI — not a new permission — and there is no separate MCP package.

After install, a host usually already has its launch configuration; see INSTALL.md. Static JSON configs use the shape below (npx runs the bin on the Node on PATH, as in Prerequisites). Do not paste it over a file the host already wrote. OpenCode does not read a static file — its plugin injects the server from the config hook. dsh is the exception: the shipped row stays inert until the profile includes @deepseek-ai/dsh-mcp-client (dsh plugin --profile web add @deepseek-ai/dsh-mcp-client).

{
  "mcpServers": {
    "morning-star": {
      "command": "npx",
      "args": ["@mstar-harness/cli", "mcp"]
    }
  }
}

Further detail: docs/runtime-reference.md.

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

A project-manager runs your session and dispatches the work: requirements and architecture, backend and frontend implementation, QC review, acceptance, codebase and PR audits, operations, and writing each go to a dedicated role. Every role follows the mstar-* skills.

Command line

The mstar-harness CLI covers what you do outside a session: issues, roadmap, workflow state, checks, the dashboard, and MCP.

• Ask the command itself. --help shows the input a command expects; for issue write verbs it lists each payload field with its type and whether it is required or only required for a particular disposition. A usage refusal tells you what it found wrong, the help route to read, and how to recover.

mstar-harness --help                        # command families
mstar-harness issue close --help            # options and payload fields for one verb
mstar-harness schema --command issue.close  # the same contract as machine-readable JSON

• mstar-harness report drafts an offline, redacted GitHub issue report for you to review before posting.

Host wiring, the issue and roadmap command families, and the details behind these surfaces are in docs/runtime-reference.md.

Documentation

• docs/runtime-reference.md — components, storage layout, roles and skills, CLI and MCP reference.
• INSTALL.md — install and verification per host, plus the report command in detail.
• docs/commands.md — the seven slash commands: arguments, when to use, owning skill.
• CONCEPTS.md — the vocabulary the harness uses across skills and docs.
• Release notes: CHANGELOG.md / CHANGELOG_CN.md. CLI flags: the `mstar-use-cli` skill.
• Maintainers: AGENTS.md.

License

MIT. See LICENSE.