mstar-use-cli

Files (5)

• SKILL.md
• checks-and-lints.md · references/
• plan-and-workflow.md · references/
• preconditions.md · references/
• status-and-registers.md · references/

SKILL.md (first lines)

# CLI contract (`mstar-use-cli`)

The CLI is the harness's machine surface: gates, coordination writes and validators sit behind it. This skill is the index that says **which family answers a task, what must be true before running it, in what order a sequence goes, and how to read the answer**.

It is deliberately silent in one direction. Command help is generated from the same source that parses the arguments, so it is the only non-drifting owner of flags, option wording and argument shapes. Help cannot express cross-command choice, preconditions, sequence order or refusal meaning — those are what this skill owns.

## Load Order

1. `mstar-harness-core` — lifecycle, gates, authorization and conflict authority; first read whenever it is loaded.
2. The **owning topical skill** for the family about to run (named in the task index below) — it holds the semantics, role boundaries and surrounding workflow.
3. This skill — the CLI transport contract for that family.

Conditional scope: this applies when a CLI binary is on PATH. Where the CLI is absent, the engine-import / prose path declared by each topical skill stays authoritative; do not read the command text here as a load-order dependency, and never use this skill as a substitute for the owning skill's rules.

Add `mstar-host` when the host's tool shapes decide how a command is launched.

## Scope

Load when:

- a CLI command must be run, or output from one must be interpreted;
- a topical skill's engine-check callout pointed here;
- an exit 1 / 2 came back and its meaning is unclear, or a command refused for a reason that looks like a missing precondition;
- a decision is needed between families (read a row, close a lifecycle, register a document, land a report, check a worktree);
- a coordinated action must be written under its current actor/state and numeric revision or execution-token contract.

Do not load for:

- installation, host bootstrap, per-host config — `INSTALL.md` plus `mstar-host`;
- flags, option wording, per-command argument shapes — the CLI help owns them;
- field schemas (`mstar-artifacts`), iteration phase semantics (`mstar-iteration`), checkout rules (`mstar-branch-worktree`), role preset decisions (`mstar-roles`);
- slash commands (`/codebase-audit`, `/iteration-drive`, …). They ship with the host plugin, not the CLI binary; their owning skills (`mstar-audit`, `mstar-iteration`, …) hold their contracts.

## Workflow

### 1. Task → command family


Start with the intended ordinary action, not a universal preflight chain. The acquired primary coordinator's own reference/current scope token/operation id may be derived where unambiguous; explicit constraints validate. Address row actions with --plan and select workflow when needed. Genuine missing configuration/source facts use revisable prepare; defaults do not require a ceremonial record.
Find the task, run the family, then read its owning skill for the rules around it.

| Task | Family | Owning skill |
|---|---|---|
| Read selected row state/configuration/evidence and token | `mstar plan show` | `mstar-artifacts` |
| Bootstrap/resume the workflow coordinator only | `mstar plan bind` | `mstar-iteration` |
| Revise row source metadata and QA/cleanup configuration (the Prepare view and its amendments) | `mstar plan prepare` | `mstar-artifacts`, `mstar-iteration` |
| Update progress; capture findings on this plan as linked issues; close one with its disposition | `mstar plan progress`, `mstar plan issue-add`, `mstar plan issue-close` | `mstar-sdd`, `mstar-project-governance` (capture contract) |
| Record Done directly from QC/QA and declared-route proof | `mstar plan complete` | `mstar-artifacts`, `mstar-branch-worktree`, `mstar-iteration` |
| Register a standalone plan workflow; record delivery evidence | `mstar workflow register`, `mstar workflow evidence` | `mstar-artifacts` |
| Register an iteration workflow | `mstar iteration register` | `mstar-artifacts` (lifecycle semantics) |
| Close one finished lifecycle (terminal workflow state + root unregister in the current authority) | `mstar status workflow-close` | `mstar-iteration` (Phase 6) |
| Return a `failed`/`stopped` lifecycle to `running` on the same id under explicit operator authorization (`completed` is never reopened) | `mstar workflow reopen` | `mstar-artifacts` (lifecycle semantics), `mstar-iteration` |
| Validate a coordination document before trusting or replacing it | `mstar status validate` | `mstar-artifacts` |
| Read the open-issue rollup; enforce a plan's findings-cleanup mode over the issues linked to it | `mstar status tech-debt`, `mstar status findings-cleanup` | `mstar-project-governance`, `mstar-artifacts` |
| Initialize a fresh issue/catalog store; upgrade/import recognizable execution state and activate authority; or run staged migration, backup, activation and retirement | the `store` group (`init` / `upgrade` / `migrate` / `backup` / `activate` / `retire`) | `mstar-conventions` (store authority and bootstrap paths); help owns inputs; `activate` is not a routine step after `init` / `upgrade` |
| Preview/apply execution recovery from a store backup; export current execution state | `mstar store execution restore-preview`, `mstar store execution restore`, `mstar store execution export` | `mstar-artifacts`; current help owns authorization and recovery inputs |
| Read/write/list/delete retained persisted documents (`review` / unrelated `json`); the `residuals` kind refuses and the root/snapshot kinds are outside this surface | `mstar persist get`, `mstar persist write`, `mstar persist list`, `mstar persist delete` | `mstar-artifacts`; `residuals` kind is retired on every route |
| Launch argv under a fresh local execution identity; recover a stopped coordinator or explicitly named plan owner (never resume) | `mstar session run`, `mstar session recover` | `mstar-iteration`, `mstar-artifacts` |
| Land or check a QC seat report | `mstar qc validate-report` | `mstar-review-qc` |
| Validate an Assignment before dispatch | `mstar dispatch validate` | `mstar-dispatch-gates` |
| Map an execution mode to its QC seat count; assert tri identity | `mstar review seats` | `mstar-review-qc` |
| Check workflow-entry facts (branch anchors, main residency, integration checkout cleanliness, integration merge lease) or the L1 / L2 pre-dispatch worktree topology | `mstar worktree check` (L1 per-plan gains the lease fact; `--entry` is the workflow-level form) | `mstar-branch-worktree`, `mstar-dispatch-gates` |
| Assert QC / QA checkout alignment across seat files | `mstar worktree qc-alignment` | `mstar-branch-worktree` |
| Post-merge worktree and branch cleanup (dry-run first) | `mstar worktree cleanup` | `mstar-iteration` |
| SDD helpers: workspace, brief, branch diff package, bound launch, evidence capture | `mstar sdd workspace`, `mstar sdd task-brief`, `mstar sdd review-package`, `mstar sdd check-context`, `mstar sdd exec`, `mstar sdd evidence` | `mstar-sdd` |
| Evaluate a phase-transition gate; probe push cadence | `mstar iteration gate`, `mstar iteration push-cadence` | `mstar-iteration`, `mstar-phase-gates` |
| Resolve the harness / plan / SDD / workflow / project dirs | `mstar path resolve` | `mstar-conventions` |
| Read/export or mutate issues in `{HARNESS_DIR}/store.db` (`add` / `list` / `show` / `occurrence` / `triage` / `close` / `move` / `waive` / `duplicate` / `supersede` / `link` / `export`) | `mstar issue …` | `mstar-project-governance` (capture/disposition), `mstar-conventions` (store path); help owns actor, operation, payload and issue-CAS inputs |
| Serve the read-only local dashboard (issues, execution/roadmap views, issue-flow chart) on `127.0.0.1` | `mstar dashboard` | None — read-only surface; loopback binding is fixed and command help owns the flags |
| Discover, import, register, update, link, list, show, export, reconcile or purge a verified producer registration in the harness catalog | `mstar catalog …` | `mstar-conventions` (catalog vs execution DB domains; Markdown index rows retired); group help owns verbs and flags |
| Read a project's roadmap authority, preview/apply reviewed Markdown import, revision-guarded content replacement, or export the composed milestone roadmap (reporting transport) | `mstar roadmap show`, `mstar roadmap import`, `mstar roadmap replace`, `mstar roadmap export` | `mstar-project-governance` (single authoring/read/write rule home); group and verb help own flags and payloads |
| Create, update, or assign project milestones (structured roadmap goals); read milestone rollups | the `milestone` group (`add` / `update` / `assign` / `list` / `status`) | `mstar-project-governance` (milestone rules); group help owns verbs and flags |
| Detect the active host; resolve a loaded skill root | `mstar host detect`, `mstar host skill-root` | `mstar-host` |
| Lint harness artifacts by content type | `mstar lint` | `mstar-skill-authoring`, `mstar-coding-behavior`, `mstar-strategy` |
| Lint a skill's frontmatter and five-question body | `mstar skill lint` | `mstar-skill-authoring` |
| Validate the role mapping and load-order corpus | `mstar roles validate` | `mstar-roles` |
| Validate a knowledge doc's frontmatter and scope; the knowledge index-row assert is retired (refuses `compound.index.retired` → catalog completeness) | `mstar compound validate` | `mstar-compound` |
| Validate DESIGN.md tokens and parity | `mstar design-md validate` | `mstar-design-md` |
| Scaffold the audit review report; run static security checks | `mstar audit scaffold`, `mstar audit secret-scan`, `mstar audit supply-chain` | `mstar-audit` |
| PR-review arithmetic, report path (`--reviews-dir`, default the resolved `{REVIEW_DIR}`), saved-report validation, worktree setup | `mstar pr-review tally`, `mstar pr-review report-path`, `mstar pr-review validate-report`, `mstar pr-review worktree-setup` | `mstar-audit` (pr variant) |
| Bootstrap a harness directory | `mstar harness scaffold` | `mstar-conventions` |
| Recover a workspace holding recognized v1/v2 execution sources; standalone file-staging `migrate` is retired | `mstar store upgrade` | `mstar-artifacts`, `mstar-conventions`; original source bytes remain untouched |
| Discover one command or payload contract | `mstar schema` | `mstar-use-cli`; bounded schema/help is the input-shape authority |
| Draft an offline redacted issue report | `mstar report` | `mstar-use-cli`; no automatic external submission |

Per-family detail — refusal codes, JSON envelopes, sequence walkthroughs — is in the references listed at the end. Validator and lint families are indexed in `references/checks-and-lints.md`.
Retired, never live alternatives: `status archive-residuals` / `backlog-register` / `backlog-close` → `status.verb-retired`; removed plan verbs (including `plan residual-add` / `residual-close`) → exit `2`, `command.invalid-input`; `persist … residuals` → `persist.kind-retired`. Capture and disposition use issue verbs, not aliases.


### 2. Conflict diagnostics (not a preflight chain)

Use `references/preconditions.md` when the intended verb refuses for a required fact. The refusal's grouped facts identify the one genuinely missing or conflicting input — ambiguous root/target, foreign live holder, unavailable authorization; supply a real competing choice or the owner's authorization evidence only for those. On plan mutations the derived session binding and token need no separate read, while the caller's independently acquired identity and the caller-owned operation id stay required on every active write; workflow-level active writes and a fresh active bind state the scope's full execution token themselves. A stale explicit token requires a fresh read; recorded byte versions impose no replacement constraint. Do not make `persist` or rebind a routine prerequisite for an ordinary lifecycle action. A refusal's commit state is action-local: read the receipt to learn what committed — the engine's coordinated plan-route refusals are transactional (no row, receipt or counter change), and an action-local partial receipt records its applied components — then replay only the documented remaining action.

### 3. Lifecycle shape

The primary coordinator's ordinary prepare/progress/complete operations replace ownership-transfer completion. Iteration complete verifies the already-performed serial merge; standalone development verifies registered source without integration inputs; report-only consumes matching fulfilment recorded before Done without fabricated Git. All retain QC/QA and their distinct outer delivery/close obligations. No per-row execution lease or bind exists.

Complete writes Done/evidence/ownership atomically and releases applicable integration exclusion; exact replay preserves timestamps. Retry the same intended action with current facts rather than introducing another protocol. Parameters/recovery → references/plan-and-workflow.md.

## Decision Rules

- **Canonical binary is `mstar-harness`.** `mstar` is a short alias that shares its bin namespace with an unrelated third-party npm package of the same name: outside an environment where the harness package is installed, invoking the short alias through a package runner resolves via the registry to that other tool, and co-installing both packages globally silently overwrites the `mstar` shim — last install wins. Prefer the canonical name in scripts, CI and anything a reader might copy out of context.
- **Exit codes: `0` ok, `1` engine refusal, `2` usage.** `0` includes idempotent no-ops and read-only reads. `1` carries a stable machine code; a refused call's commit state is action-local and stated by its receipt. `2` is a usage error — unknown flag, missing required argument or option, malformed or relative path where an absolute one is required, unreadable payload.
- **Flags come from the CLI help, never from this skill.** Run the group help, or the verb help, before guessing an option; the group help is also the authority for which verbs exist at all.
- **Refusal semantics are action-local.** A refusal's commit state belongs to that one action: read the receipt instead of assuming. The engine's coordinated plan-route writes refuse transactionally — a refused operation there writes no row, receipt or counter change, so its recovery is a read of current state, never an undo. Where a verb documents action-local partial application, components already committed stay committed — the receipt names them, and the documented remaining action is replayed as its own operation, not the whole sequence. A stale explicit token is recovered by re-reading the addressed scope and retrying with the fresh token. There is no force, no replace and no takeover flag to escalate to.
- Evidence digests record provenance, not immutable report bytes. Explanatory report edits need no hash repair or resealing; current semantic QC/QA, source proof and evidence-path requirements still apply. No ownership-transfer repair action remains.
- **Streams are per command and per mode — observe them, never infer from the family.** A verb's machine surface (the `--json` form, or a verb whose output is a machine object such as `persist get`) writes that object to **stdout**, failure and refusal objects included, so neither the exit code nor the family tells you which stream carried the bytes. On the human surface a success is usually one short line on **stdout** (`<path>: OK`, `host: <id>`), though some verbs leave stdout empty and put the readable summary on **stderr**; usage errors and most refusal diagnostics go to **stderr**, and one command can split inside itself — machine rows on stdout, the human headline on stderr. No split holds for every command and no enumeration is reliable, so never assume a command's failure text is on stderr: where a pipe depends on it, read the actual output or that command's help. The exit code is the verdict; an empty stdout is not by itself a failure signal.
- **The CLI you run may not be the code you read.** The globally installed binary runs the *published* engine build, and even a workspace entry point resolves the engine's **built output**, which can lag its source until that package is rebuilt — so a fix present in the engine source can be absent from the very command you are testing. Install health, and a healthy setup check, prove neither. When a result contradicts source you just read, rebuild or re-resolve before concluding the source is wrong, and follow the version-alignment path in `mstar-harness-core`. The same caution covers a repository's own generated bundles: a checkout can be mid-flight between source and artifact.
- **Never write a lifecycle state or a lease by editing a document.** Done and lease release go through the completion verb; the protected coordination documents refuse direct writes by design.
- **Never hand coordinator context to a leaf:** session references/envelopes, CAS tokens and operation IDs stay with the primary PM; leaf tasks carry only owned scope/paths/evidence.
- **Never substitute recovery for resume or resume for recovery.** A resume is read-only; a stopped owner is replaced only by the recovery verb that owns the current authority.
- **A validator's `OK` is a statement about its own contract only.** Exit 0 means no violations of that check — not that the content is correct, complete or current.

## Evidence

A CLI claim is proven when:

- the command was actually run, or the result is a machine object a command produced this round — not a recollection of documentation;
- the exit code matches the family contract, and a `1` is reported with its stable code and message;

From btspoony/mstar-harness, MIT.

More from btspoony/mstar-harness