# Morning Star Harness Maintenance Guide This repository is maintained as a **harness/configuration project**, not an application repo. Use this document as the primary maintenance contract for contributors and agents. ## Scope - Default intent in this workspace: maintain Morning Star harness behavior, docs, and host adapters. - Repository layout uses a monorepo-style split: `packages/opencode` for the publishable OpenCode plugin (`@mstar-harness/opencode`), `packages/cli` (`@mstar-harness/cli`) for the standalone CLI. - Do not treat this repo like a product feature/codebase task unless explicitly requested. - Runtime execution rules for users/agents live in `mstar-*` skills; this file defines **maintenance behavior**. ## Maintenance Goals - Keep one coherent harness behavior across hosts. - Keep prompts/rules minimal, explicit, and non-duplicated. - Prefer stable defaults and small, reviewable changes. - Preserve user safety boundaries for global config and secrets. ## Core Rules - **Single source by topic**: keep each rule in one authoritative place; avoid copy-paste rule drift. - **Execution vs maintenance split**: - Skills/role prompts describe runtime behavior. - `AGENTS.md` describes repository maintenance policy. - **Surgical edits**: only change what the task requires; avoid opportunistic refactors. - **Read before edit**: inspect current content before patching; verify after patching. - **README = developer consumer docs** (`README.md` / `README_CN.md`): - Audience is developers who install and run the harness — not a concept tutorial. - Prefer commands, tables, and links. Do **not** write chatty “How to use” prose. - A short curated value-prop bullet list at the top is allowed; keep it to a few selling points, not a marketing essay. - Keep the shortest executable path: Install → Use (**without iteration** vs **with iteration**) → Workflow diagram → Roles/skills tables. - Put narrative, deep install, and host quirks in `INSTALL.md`, `docs/`, or `mstar-*` skills — not in the README body. - Edit both language files together when README content changes. - **Bilingual minimal updates**: for paired docs (README.md/README_CN.md, packages/dsh README triplets), apply the minimal counterpart edit — never re-translate a document to apply an update — and re-record pairing hashes (`git hash-object`) in the same change set. ## Cursor + OpenCode + Codex + Kimi + ZCode + omp Sync Policy When a change affects shared harness behavior, treat OpenCode, Cursor, Codex, Kimi, ZCode, and omp as host surfaces of one system. - Update shared semantics first (core harness contract), then host-specific adapters. - Keep host wording consistent on: - load order expectations - dispatch/delegation boundaries - gate/evidence language - If behavior must diverge by host, document the reason explicitly and keep the divergence minimal. - For plugin-facing changes, ensure all hosts remain installable and understandable from current docs. - Do not maintain long host-specific checklists in many files; keep intent centralized and examples lightweight. ## What To Do - Do align changes with the current harness invariants before editing downstream docs/prompts. - Do update bilingual docs together when user-facing behavior changes. - Do keep `README.md` / `README_CN.md` developer-short (Install + Use scenarios + Workflow + tables); reject verbose onboarding rewrites into README. - Do keep CLI implementation changes inside `packages/cli` and OpenCode plugin packaging inside `packages/opencode`. - Do keep role shells thin and maintain richer role behavior in role-skill references. - Do keep commit scope coherent (one concern per commit when possible). - Do verify any changed command/config snippets are still runnable. ## What Not To Do - Do not edit user secrets or local credential files. - Do not silently change security-sensitive defaults. - Do not introduce parallel “maintenance manuals” inside skill bodies. - Do not turn `README.md` / `README_CN.md` into tutorials or long “How to use” essays — keep executable paths; detail belongs in `INSTALL.md` / `docs/` / skills. - Do not scatter the same rule text across multiple files just for discoverability. - Do not require manual file-by-file index maintenance when explore/search can discover structure. ## Change Workflow (Lightweight) 1. Clarify the maintenance intent and affected behavior surface. 2. Apply minimal edits in the right canonical layer. 3. Sync host adapters/docs only where behavior or onboarding changed. 4. Run lightweight validation (lint/typecheck/doc link sanity as relevant). 5. Summarize what changed, why, and any intentional host-specific divergence. ## Release Process Releases are PR-driven and mostly automated. Every release ships one version across all 12 version surfaces (root + 4 npm packages + 7 plugin manifests [6 host + portable Agent Plugins]); also bump the INSTALL.md marketplace example. ### 1. During development — add a changelog fragment Per logical change, add `.changes/unreleased/.md` (committed with the change). Format and defaults: [`.changes/README.md`](.changes/README.md). During development, **do not** hand-edit `CHANGELOG.md` / `CHANGELOG_CN.md` / `packages/*/CHANGELOG.md` (including under `## [Unreleased]`); those files are assembled later by `release:prepare`. ```markdown --- category: Harness # optional; default per package packages: root # optional; comma list of root | cli | opencode | engine --- - English bullet. - 中文要点。 ``` Need both root + OpenCode notes? Prefer one fragment with `packages: root, opencode` (omit `category` so each package keeps its default section header), or split fragments if the bullets must differ. A release always auto-appends the **Version alignment** block — do not write one. ### 2. Cut a release — assemble + open the release PR Either: - **GitHub Actions**: Actions → *Release prep* → Run workflow (optionally pass an explicit `X.Y.Z`; empty = auto patch bump), **or** - **Local**: `bun run release:prepare -- 1.8.7` (or `-- --patch` / `-- --minor`), then open a PR titled `release v1.8.7`. `scripts/prepare-release.ts` reads `.changes/unreleased/*.md`, inserts a `## []` section into all 5 changelogs, bumps every surface, updates the root changelog registry tables, and moves consumed fragments to `.changes/archive//`. Validate with `bun run release:validate -- v1.8.7`. ### 3. Merge the release PR — auto-tag + publish Merging a `release vX.Y.Z` PR runs the **Release** workflow **inline on the `pull_request` event**: validate → build → npm publish (provenance) → create+push `vX.Y.Z` (annotated tag, pushed with the workflow's `GITHUB_TOKEN`) → GitHub Release. No secrets are required for the default flow. Releases are PR-driven by design — a manual `git tag && git push --tags` no longer auto-publishes. > npm trusted publishing / provenance now runs on the `pull_request` event (previously `push:tags`); the workflow filename is unchanged. If the first release via this flow fails publish, revert the trigger to `push:tags` and switch to a PAT-pushed auto-tag model. ### Conventions - Never invent a skipped tag (e.g. do not create `v1.8.4` to fill a historical gap). - Bump version + changelog in the same change set via `release:prepare`; do not hand-edit version surfaces (the `release:validate` gate reads the same surface list). - Avoid the #58-class drift: the version registry tables in the root changelogs are bumped automatically — do not hand-edit the registry version cells. ## AI Agent Quality Gate Before opening PRs or proposing "done", an agent must: 1. Confirm the change solves a real, observed maintenance problem (not a theoretical one). 2. Check for duplicate or recently rejected attempts before repeating similar work. 3. Confirm the change belongs in core harness (otherwise recommend a separate plugin/extension path). 4. Show the complete diff to the human partner and get explicit approval. 5. Provide verification evidence for any behavior-shaping changes. 6. If the change is user-facing or behavior-notable, confirm a matching `.changes/unreleased/.md` fragment exists — and that assembled `CHANGELOG*` files were **not** hand-edited for it. If one of these checks fails, stop and report why. ## Changes Usually Rejected - Unrelated bundled edits in one PR. - Speculative fixes without a concrete failure or user impact. - Project-specific customizations disguised as core behavior. - Style-only rewrites of behavior-shaping prompts/skills without evaluation evidence. - Claims that are not supported by code, tests, or reproducible validation. ## Evidence Standard - Behavior change -> show before/after expectation and at least one concrete verification step. - Install/config change -> verify snippets are executable and aligned with current docs. - Prompt/skill change -> explain why the wording change improves outcomes, not only readability. ## Skill Maintenance Essentials - Keep skills as **runtime SSOT**, not maintenance handbooks. - Keep `SKILL.md` focused on execution path; move deep detail to `references/` when needed. - Treat frontmatter `description` as a trigger contract; update it when scenarios change. - Prefer one coherent skill per workflow unit; avoid over-splitting or giant mixed-scope skills. - Use default-first guidance (primary path first, exceptions second) to reduce agent ambiguity. - Preserve role shell minimalism: role binding stays thin; reusable behavior stays in skill references. - When changing behavior-shaping skill text, require evidence (evals, regressions, or concrete outcomes), not wording preference. - **`mstar-*` standalone**: runtime `mstar-*` skills must not require external skills, CLIs, or MCPs in load order; commands may reference bundled non-`mstar-*` assets under `skills/` (e.g. `grill-me` for `/iteration-start` only). **`prompt-engineer`** may additionally follow the repository **`skill-creator`** requirement for new/major skill work (`AGENTS.md`). ## Skill-Creator Requirement - For new skills or major skill rewrites, use skill-creator guidance before editing: - `~/.agents/skills/skill-creator/SKILL.md` - `~/.cursor/skills-cursor/create-skill/SKILL.md` - Keep trigger quality explicit: - `description` must say when to trigger and what outcome it enables. - Add/update trigger phrases when scenarios expand. - If a change alters behavior (not just wording), include evaluation evidence. ## Local scratch layout (`.tmp/`, `.worktrees/`) 统一本地布局约定（gitignored，用完即清）： - 临时文件（一次性探针、日志、浏览器 profile、验证脚本等）→ 仓库根 **`.tmp/*`**，用完即清，不跨轮次残留 - Git feature worktrees → **`.worktrees/*`**（每 plan 一个子目录，如 `.worktrees/-`，`git worktree add .worktrees/ -b feature/`）；合并后 `git worktree remove` 并 `git worktree prune` ## Local maintenance workspace (`.harness/`, gitignored) Use **`.harness/`** only for **in-progress maint docs** on this repo (not published runtime skills): | Path | Purpose | |------|---------| | `.harness/docs/` | Design specs, decomposition notes, ADRs, reports for harness changes | **This repository's harness root is `.mstar/`** (the `mstar-plan-conventions` consumer default — same convention consumer projects use): `status.json`, `plans/`, `iterations/`, `knowledge/`, `sdd/`, `references/`, `archived/` all live under `.mstar/`. `.harness/` is NOT a harness root — it holds maintenance docs only; do not create plan/status artifacts there. **Runtime SSOT** for `mstar-*` skills stays in repo-root **`skills/`** (bundled via `packages/opencode` `bundle-assets`). Do not treat `.harness/skills/` as the publish path. ## Where To Edit (Minimal Routing) - Core harness entry, state machine, Task category, skill index -> `skills/mstar-harness-core/*` - Phase gates (Prepare/Execute, hotfix) -> `skills/mstar-phase-gates/*` - Dispatch, Delegation, anti-recursion, SDD serial, QC default -> `skills/mstar-dispatch-gates/*` - SDD file handoff, per-task review, ledger -> `skills/mstar-sdd/*` - Git branches, worktrees, QC/QA checkout alignment -> `skills/mstar-branch-worktree/*` - Plan directory discovery, init, Spec branch summary -> `skills/mstar-plan-conventions/*` - Plan artifacts (`status.json`, residual, main plan, reports/, knowledge, Done compaction, `templates/`) -> `skills/mstar-plan-artifacts/*` - DESIGN.md design system spec (create/audit/maintain, tokens, completeness checklist, light/dark themes, templates) -> `skills/mstar-design-md/*` - QC baseline and review template -> `skills/mstar-review-qc/*` (PM orchestration); leaf QC execution -> `skills/mstar-roles/references/qc-specialist/*` - Codebase audit → prioritized improvement plans -> `skills/mstar-audit/*` (read-only advisory; plan quality bar -> `skills/mstar-plan-artifacts/references/plan-quality-bar.md`) - Cross-role coding behavior (RCA, verification, test-first discipline, review feedback) -> `skills/mstar-coding-behavior/*` - Skill authoring / trigger contracts -> `skills/mstar-skill-authoring/*` - Role behavior text -> `skills/mstar-roles/references/*` - Host adapters: - Host adapter -> `mstar-host` (in-repo: `skills/mstar-host/*`; OpenCode via `bundle-assets` → `harness-skills/mstar-host/`; Cursor/Codex/Kimi/ZCode/omp via `.cursor-plugin/` / `.codex-plugin` / `.kimi-plugin` / `.zcode-plugin/` / `.omp-plugin/` `skills/`) - OpenCode package: `harness-skills/` + `harness-agents/` from `bundle-assets` (npm publish prepublish + root `postinstall`); plugin reads only package paths, not `process.cwd()` (npm: `@mstar-harness/opencode`) - CLI package -> `packages/cli/*` (package name `@mstar-harness/cli`; local `AGENTS.md`) - Codex plugin manifest -> `.codex-plugin/plugin.json` - Kimi plugin manifest -> `.kimi-plugin/plugin.json` (plugin root is repo root; paths `./skills/`, `./commands/`) - ZCode plugin manifest -> `.zcode-plugin/plugin.json` (plugin root is repo root; paths `./skills/`, `./commands/`, `./agents/`) - omp plugin markers -> `.omp-plugin/plugin.json` + `.claude-plugin/plugin.json` (plugin root is repo root; paths `./skills/`, `./commands/`, `./agents/`) - Codex install metadata generation -> `packages/cli/src/adapters/codex.ts` - ZCode install metadata generation -> `packages/cli/src/adapters/zcode.ts` - omp install/link flow -> `packages/cli/src/adapters/omp.ts` - Maintenance policy (this file) -> `AGENTS.md` ## Skill Sync Rules - Update shared harness semantics before host adapters. - Sync bilingual user-facing docs when installation or behavior expectations change. - Keep cross-host differences explicit and minimal; no silent divergence. - Avoid duplicating the same maintenance guidance across many runtime files. ## Cursor Routing-Eval Usage Rules Use `.cursor/skills/mstar-routing-eval/` only for Cursor maintenance and regression work: - When PM routing logic changes. - When phase gates or dispatch constraints change. - When role/prompt/rule updates may affect routing outcomes. Do not treat routing-eval as a runtime skill for normal implementation tasks. ## Topic skill load matrix (runtime) After `mstar-harness-core`, load **only** what the role and round need (see `skills/mstar-roles/SKILL.md`): | Skill | Typical readers | |-------|-----------------| | `mstar-phase-gates` | PM; product/architect in Prepare | | `mstar-dispatch-gates` | PM; **all leaf executors** before Task/subagent | | `mstar-sdd` | PM on `Execution mode: sdd`; SDD implementer/reviewer subagents (SUBAGENT-STOP); optional **`SDD implementer session: sticky`** (`references/sticky-implementer-session.md`) | | `mstar-branch-worktree` | PM, dev*, QC*, QA, ops when Git/write or QC checkout | | `mstar-plan-conventions` | PM; dev* for path symbols / metadata | | `mstar-plan-artifacts` | PM (status/residual, InReview/QC waves), architect, product-manager, QC* (reports), QA (R#) | Edit topic skills directly (`mstar-phase-gates`, `mstar-branch-worktree`, `mstar-plan-artifacts`, …); do not recreate moved stub files under legacy paths. ## Post-Skill-Change Sync Checklist - [ ] `description` still matches trigger scope and intent. - [ ] `SKILL.md` stays concise; heavy detail moved to `references/` when needed. - [ ] Shared semantics and host adapters remain consistent. - [ ] Cursor routing-eval updated if routing/gate behavior changed. - [ ] User-facing docs updated in both `README.md` and `README_CN.md` if onboarding changed. - [ ] Validation evidence included for behavior-shaping changes. - [ ] Stale cross-references point at topic **`SKILL.md`** or real `mstar-plan-artifacts/references/*` files (no deleted stub paths).