@mstar-harness/opencode 1.8.7 → 1.8.9

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface re
 
 ## [Unreleased]
 
+## [1.8.9] - 2026-08-07
+
+### Harness
+
+- **Phase 5 checkout**: merge-ready product fixes edit **directly** on the control / `spec_integration_branch` checkout; **forbid** opening a separate Phase 5 feature/fix worktree or applying Phase 2's "no product edits on control" rule. SSOT stays in `mstar-iteration` (`phase-4-5-pr-delivery` §5.0); **not** in the general `mstar-branch-worktree` skill.
+
+- Version alignment with harness **1.8.9** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.9**.
+
+## [1.8.8] - 2026-08-06
+
+### Bundled harness skills (`harness-skills/` at publish)
+
+- **`mstar-skill-authoring`**: fold the skill-writer 6 principles into the runtime authoring skill — expert process first, compact 5-question body, 1–3 skill routing, per model+harness validation, encode only model gaps, every edit as paired experiment. Body stays the executable gate; full writer loop / output template / anti-patterns → `references/skillsbench-authoring.md` (progressive disclosure).
+- Tightened `description` trigger contract with exclusions; keep purpose test / frontmatter / progressive disclosure / review template as reusable SSOT.
+- Reframe as **general** skill-authoring guidance (any domain/repo): drop Morning Star / `mstar-*`-only branding from body; keep minimal harness hooks (Load Order + `mstar-host` path resolve) only when working in this repo.
+- Restored `## Skill-relative script and asset paths` heading so `mstar-host` § cross-reference stays valid (Post-Skill-Change stale-ref checklist).
+- Keep changelog SSOT tight in `AGENTS.md`: §1 owns the fragment rule (including no hand-edit of assembled `CHANGELOG*`); Quality Gate #6 stays the executable check; remove copy-paste repeats elsewhere.
+
+- Version alignment with harness **1.8.8** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.8**.
+
 ## [1.8.7] - 2026-08-06
 
 ### Bundled harness skills (`harness-skills/` at publish)

package/harness-commands/iteration-drive.md

@@ -101,7 +101,7 @@ Helper 搜索路径 → **`mstar-iteration/references/phase5-helper-discovery.md
 
 ### 5.1 Loop + review fix hygiene（all modes）
 
-Execute **`mstar-iteration` §5.1 loop**（`references/phase-4-5-pr-delivery.md` §5.1）：status（`gh pr view <number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision` 或宿主等价 API）→ merge conflicts → unresolved reviews → CI → **§5.1a idle push**（一批修复一次 push）→ mode-specific pass（babysit SKILL / greploop / fallback）→ §5.1 review fix hygiene（**comment on same thread + resolve**）→ repeat until §5.5。Fixes **push 到 `spec_integration_branch`**（PR head）；禁止另开分支替代。产品代码修复 → **dispatch** dev/ops；PM 线程不代写。**禁止**为「让 CI 变绿」而改 workflow，除非用户明确授权。多轮仍 blocked → 升级用户。
+Execute **`mstar-iteration` §5.1 loop**（`references/phase-4-5-pr-delivery.md` §5.1）：status（`gh pr view <number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision` 或宿主等价 API）→ merge conflicts → unresolved reviews → CI → **§5.1a idle push**（一批修复一次 push）→ mode-specific pass（babysit SKILL / greploop / fallback）→ §5.1 review fix hygiene（**comment on same thread + resolve**）→ repeat until §5.5。Fixes **push 到 `spec_integration_branch`**（PR head）；禁止另开分支替代。**Checkout（HARD，§5.0）**：直接在 control / 集成分支 checkout 上修；**禁止**另开 Phase 5 fix worktree，**禁止**套用 Phase 2 control 产品编辑禁令。产品代码修复 → **dispatch** dev/ops（Assignment cwd = control）；PM 线程不代写。**禁止**为「让 CI 变绿」而改 workflow，除非用户明确授权。多轮仍 blocked → 升级用户。
 
 ### 5.2 Phase 5 exit checklist（iteration-drive Done）
 

package/harness-skills/mstar-harness-core/SKILL.md

@@ -100,7 +100,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-compound` | 知识结晶 —— 已解决问题→结构化知识文档，双轨（Bug/Knowledge），「是否值得结晶」自检清单，重叠检测，可发现性检查，CONCEPTS.md 协同 |
 | `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档；**项目知识 bootstrap**（无/残旧 STRATEGY.md、CONCEPTS.md、`{KNOWLEDGE_DIR}`）→ `references/project-knowledge-bootstrap.md` |
 | `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
-| `mstar-skill-authoring` | mstar-native skill authoring: trigger contracts, progressive disclosure, pressure scenarios, behavior-change evidence |
+| `mstar-skill-authoring` | 通用 skill 撰写门控（SkillsBench 六原则）：trigger 契约、紧凑 5 问 body、渐进披露、paired 证据 |
 | `mstar-audit` | Read-only codebase audit → prioritized, self-contained improvement plans（`audit-playbook` 9 类别 + `finding-format` + `plan-quality-bar`） |
 | `mstar-roles` | 角色正文 hub |
 | `mstar-host` | 宿主适配（自动识别；`references/opencode.md` / `cursor.md` / `codex.md` / `kimi.md` / `parallel-dispatch.md`） |

package/harness-skills/mstar-iteration/SKILL.md

@@ -355,7 +355,7 @@ Iteration Phase 2 附加：
 
 **Phase 4**（开 PR）与 **Phase 5**（merge-ready loop）完整流程（§4、§5.0、§5.1a push cadence、§5.1 loop、§5.2 exit checklist）→ **`references/phase-4-5-pr-delivery.md`**。
 
-**关键定位（hard）**：Phase 4 开 PR **≠** 迭代交付完成；必须完成 Phase 5 §5.2 merge-ready exit。**Push cadence（§5.1a HARD）**：本地可提前修，**禁止**在 CI / AI review 波次未结束时 `git push`。
+**关键定位（hard）**：Phase 4 开 PR **≠** 迭代交付完成；必须完成 Phase 5 §5.2 merge-ready exit。**Push cadence（§5.1a HARD）**：本地可提前修，**禁止**在 CI / AI review 波次未结束时 `git push`。**Checkout（HARD）**：Phase 5 修复直接在 control / `spec_integration_branch` 上做；**禁止**另开 Phase 5 fix worktree，**禁止**套用 Phase 2「control 禁止产品编辑」（细则 → **`references/phase-4-5-pr-delivery.md`** §5.0）。
 
 ---
 
@@ -379,6 +379,7 @@ Iteration Phase 2 附加：
 
 - **不要将 Phase 4 开 PR 等同于迭代交付完成** — 必须完成 Phase 5 §5.2 merge-ready loop
 - **不要在 Phase 5 CI 仍跑或 AI review 波次未结束时 push**（§5.1a）— 本地可提前修，push 等 idle
+- **不要为 Phase 5 另开 feature/fix worktree**，也不要把 Phase 2 control 产品编辑禁令套到 Phase 5 — 直接在集成分支 checkout 上修
 - **不要在缺 `iteration_base_branch` / `target_branch` 时默认 `main` / `master`**
 - **不要在 iteration-start §1.6 由 product/architect 向 `{KNOWLEDGE_DIR}/` 新增**（知识 → iteration-close **`mstar-compound`**）
 - **不要在 per-plan Done 后立即 compound** — 等 iteration-close 统一做

package/harness-skills/mstar-iteration/references/phase-2-worktree-lease.md

@@ -18,6 +18,8 @@ required.
 Phase 1 Review & Edit may stay on the primary checkout. The control-worktree gate
 starts at **Phase 2 entry**.
 
+**Phase scope**：本参考仅约束 **Phase 2**（含 serial integration merge 与「control 禁止产品编辑 / 每 plan feature worktree」）。**Phase 5** PR merge-ready 修复 **不**沿用该产品编辑隔离——直接在 control / `spec_integration_branch` 上改，**禁止**另开 Phase 5 fix worktree → **`phase-4-5-pr-delivery.md`** §5.0。
+
 ## Control worktree (Phase 2 entry)
 
 1. Resolve all active plans' `metadata.spec_integration_branch` to the **same**

package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md

@@ -23,7 +23,8 @@
 ### 5.0 Phase boundary
 
 - Phase 5 在 PR head（`spec_integration_branch`）上 push 修复；**禁止**另开替代分支
-- 产品代码修复 → PM **dispatch** dev/ops（`mstar-dispatch-gates`）；PM 线程不代写实现
+- **Checkout / worktree（HARD）**：Phase 5 是 PR 级 **hotfix** loop，**不是** Phase 2 plan 实现。修复直接在 **control worktree**（已检出 `spec_integration_branch` 的 checkout）上编辑、commit、再按 §5.1a push。**禁止**为 Phase 5 另开 feature / fix worktree；**禁止**把 Phase 2「control 禁止产品编辑 / 须 feature worktree」套用到 Phase 5。另开 worktree 浪费时间、磁盘与计算，与 Phase 5 快速收敛 CI/review 的目标相悖。
+- 产品代码修复 → PM **dispatch** dev/ops（`mstar-dispatch-gates`）；Assignment **`Worktree path`** / cwd = control（`metadata.control_worktree_path` 或当前已在集成分支上的 checkout）；PM 线程不代写实现
 - 禁止为「让 CI 变绿」而改 workflow，除非用户明确授权
 - **Push cadence** → **§5.1a**（本地可提前修；**禁止**在 CI / AI review 波次未结束时 push）
 
@@ -66,7 +67,7 @@
 | 2 | `greploop` | **Optional** — only when the **repo** uses Greptile / has `greploop` available; then run for Greptile **5/5** in addition to babysit/`*-babysit` (or fallback) gates |
 | 3 | neither | Command fallback = babysit-equivalent CI + reviews gates |
 
-When both babysit/`*-babysit` and `greploop` apply: **babysit/`*-babysit` first**（CI + reviews），then optional greploop for Greptile score. Discovery paths → host `commands/iteration-drive` / `iteration-loop` Phase 5.
+When both babysit/`*-babysit` and greploop apply: **babysit/`*-babysit` first**（CI + reviews），then optional greploop for Greptile score. Discovery paths → host `commands/iteration-drive` / `iteration-loop` Phase 5.
 
 ### 5.2 Phase 5 exit checklist（迭代交付完成）
 

package/harness-skills/mstar-skill-authoring/SKILL.md

@@ -1,197 +1,158 @@
 ---
 name: mstar-skill-authoring
-description: Morning Star skill authoring and maintenance guidance. Read when creating a new skill, making a major skill rewrite, changing trigger descriptions, evaluating whether behavior-shaping skill text works, or reviewing skill structure before release. This is mstar-native and independent of external skill plugins.
+description: Agent skill 撰写 / 重写 / 优化规范（SkillsBench 实验门控）。在新建任意 skill、大改 SKILL.md、改写 description 触发契约、压缩过长 body、评审 skill 结构、或判断某段行为塑形文案是否值得保留时读取。适用于任何领域的 skill，不限于本仓库专题；不用于普通应用实现。
 ---
 
-# Morning Star Skill Authoring
+# Skill Authoring
 
-This skill defines how Morning Star authors, reviews, and validates runtime skills. It is for skill work, not ordinary application implementation.
+本 skill 约束如何编写、审查与验证 **任意** agent skill（`SKILL.md`）。面向 **skill 工作**，不是普通应用实现。
 
 ## Load Order
 
-Read `mstar-harness-core` first. For repository maintenance, also follow root `AGENTS.md`.
+在本 harness 仓库内工作时：先 Read **`mstar-harness-core`**（加载 / 冲突裁决）；仓库维护另遵根目录 `AGENTS.md`。
 
-When changing existing skills, read every topic skill you touch and any referenced files needed to preserve the single source of truth. Do not rewrite adjacent skills for style only.
+在其它仓库 / 宿主上使用本 skill 时：按当地入口文档加载；本文件的原则与门控仍然适用。
 
-## Core Practices
+改现有 skill 时：读完被改 skill 及其 SSOT 引用；禁止仅为文风重写相邻 skill。
 
-This skill defines Morning Star's reusable skill-authoring practices:
+详细 writer 流程与输出模板 → `references/skillsbench-authoring.md`（需要完整循环时再读）。
 
-- Treat skills as process code that should be tested against pressure scenarios.
-- Use frontmatter descriptions as trigger contracts, not process summaries.
-- Keep `SKILL.md` concise and move heavy detail into `references/`.
-- Prefer concrete trigger symptoms, contexts, and user phrases.
-- Verify behavior-changing skill edits with evidence, not wording preference.
+## 6 条作者原则（必须遵守）
 
-It deliberately avoids external path assumptions, external plugin dependencies, and any requirement to run a non-Morning-Star skill as a prerequisite.
+来源：SkillsBench 大规模实验。违反任一都会降低 agent 性能。
 
-## Skill Purpose Test
-
-Create or expand a skill only when all are true:
+| # | 原则 | 强制动作 |
+|---|------|----------|
+| 1 | **专家流程优先** | 先提取真实操作步骤、决策标准、约束、API 坑与失败恢复；模型只做编辑器。禁止把一键生成稿当最终版。 |
+| 2 | **紧凑程序性** | body 只答 5 问（见下）；详例 / 长文档进 `references/`，按需加载。过长 body 几乎无提升甚至负提升。 |
+| 3 | **路由最小化** | 任务真正需要时才加载；目标 **1–3** 个 skill。description 必须具体到可精准匹配，避免无关激活。 |
+| 4 | **按 model+harness 实测** | 文件可移植 ≠ 行为可移植。在实际使用的模型与宿主（omp / Cursor / Codex / Claude Code 等）分别验证触发、执行、token、回归。 |
+| 5 | **只补模型缺口** | 编码内部约定、受监管流程、脆弱 API、专业判断、反复失败模式。不写模型已会的通用知识。 |
+| 6 | **每次改动=受控实验** | 必须有 paired 证据（with vs without，或 before/after + 可观察标准）。held-out / 压力场景未提升则拒绝合入。禁止“感觉更好”。 |
 
-1. The behavior should be reused across multiple projects, roles, or tasks.
-2. The behavior requires judgment or sequencing that is not better enforced by code.
-3. The existing Morning Star skill tree does not already contain the same rule.
-4. The trigger can be stated clearly enough for agents to know when to read it.
+## Body 必须回答的 5 问
 
-Do not create a skill for:
+合格 `SKILL.md` **只**清晰回答：
 
-- One-off project conventions; put those in project `AGENTS.md`.
-- Mechanical rules that can be linted or scripted.
-- A solved incident narrative with no reusable technique.
-- Another copy of a rule already owned by an existing `mstar-*` skill.
+1. **何时加载？**（触发 / 排除）
+2. **按什么顺序与关键决策点执行？**
+3. **哪些约束 / 不变量绝不可违反？**
+4. **正确结果长什么样？**（成功标准 / 证据）
+5. **主路径不够时打开哪些额外资源？**
 
-## Frontmatter Contract
+答不进这 5 问的内容 → 删或移到 `references/`。
 
-Required fields:
-
-```yaml
----
-name: mstar-example
-description: Use when...
----
-```
-
-Rules:
+## Skill Purpose Test
 
-- `name` is stable, lowercase, and hyphenated.
-- `description` is the trigger contract.
-- Start with the situations that should cause the skill to load.
-- Include concrete symptoms, contexts, roles, and artifacts.
-- Do not summarize the whole workflow in the description.
-- Keep descriptions specific enough to avoid loading on unrelated tasks.
+仅当全部成立才新建 / 扩写 skill：
 
-Bad description:
+1. 行为应跨多项目、角色或任务复用。
+2. 需要判断或排序，且不宜用代码强制。
+3. 现有 skill 树尚未拥有同一规则（避免副本）。
+4. 触发条件可写清，agent 知道何时读取。
 
-```yaml
-description: Explains how to write plans with steps, tests, commits, and review gates.
-```
+不要为这些建 skill：一次性项目约定（放项目 `AGENTS.md` / 等价处）、可 lint/脚本化的机械规则、无复用手法的事故叙述、已有 skill 规则的副本。
 
-Better description:
+## Frontmatter Contract
 
 ```yaml
-description: Use when a non-trivial task has a spec or requirements and needs a written implementation plan before code changes.
+---
+name: example-skill
+description: Use when...
+---
 ```
 
-Why: descriptions are often visible before the body. If the description summarizes the workflow, agents may follow the summary and skip the full skill.
+- `name`：稳定、小写、连字符。
+- `description`：**触发契约**，不是流程摘要。写清症状、上下文、角色、产物与排除条件。
+- 第三人称；足够具体以避免无关加载（原则 3）。
+- 禁止在 description 里总结整条 workflow（否则 agent 可能只跟摘要、跳过 body）。
 
-## Body Structure
+Bad：`Explains how to write plans with steps, tests, commits, and review gates.`  
+Better：`Use when a non-trivial task has a spec or requirements and needs a written implementation plan before code changes.`
 
-Use this default structure unless the skill has a better local pattern:
+## 默认 Body 结构
 
 ```markdown
 # Skill Title
 
 ## Load Order
-What must be read first, and what owns conflicts.
-
 ## Scope
-When this applies and what it does not own.
-
 ## Workflow
-The shortest reliable execution path.
-
 ## Decision Rules
-Tables or bullets for common branches.
-
 ## Evidence
-What proves the skill was followed.
-
 ## References
-Optional files to read only when needed.
 ```
 
 Keep `SKILL.md` focused on the main execution path. Move long examples, templates, schemas, and detailed variants into `references/`, `templates/`, or `scripts/`.
 
 ## Skill-relative script and asset paths
 
-When a skill ships executables or assets under `scripts/` / `templates/` / `references/`, name them as **skill → relative path**:
-
-- Good: skill **`mstar-sdd`** → `scripts/sdd-workspace`
-- Good: `<mstar-sdd>/scripts/sdd-workspace` (placeholder for the loaded skill root)
-- Bad in runtime docs: `skills/mstar-sdd/scripts/sdd-workspace` as if it were a consumer-project cwd path
-- Bad in shipped rules / CLI notes: `skills/mstar-host/references/…` as a consumer cwd path — use **`mstar-host`** → `references/…` (omp may also cite `skill://mstar-host/references/…`)
-
-Agents discover skills by **name**; they often miss files when docs present a full repo-relative path and they search that literal string under the app checkout. Resolve the loaded skill directory first, then append `scripts/…` / `references/…`. **How** to resolve differs by host — use **`mstar-host`** § Resolve loaded skill root (omp `skill://`, Cursor plugin checkout under `~/.cursor/plugins/…` or `.cursor/plugins/…`, OpenCode `harness-skills/`, Codex/Kimi/ZCode plugin mounts). Reserve `skills/<name>/…` only for harness-repo maintenance notes that explicitly say "from this repository root".
-
-## Progressive Disclosure
+When a skill ships executables or assets under `scripts/` / `templates/` / `references/`, name them as **skill → relative path**：
 
-Use three levels:
+- Good: skill **`my-skill`** → `scripts/do-thing`
+- Good: `<my-skill>/scripts/do-thing`（已加载 skill 根的占位写法）
+- Bad：把 `skills/my-skill/scripts/do-thing` 写成消费仓库 cwd 下的字面路径
 
-1. Frontmatter: trigger only.
-2. `SKILL.md`: core execution path.
-3. Resources: details loaded only for the relevant variant.
+Agents 按 **skill 名** 发现 skill；文档若给出完整仓内相对路径，agent 常在应用仓库 cwd 下按字面搜索而找不到。先解析已加载 skill 根目录，再拼 `scripts/…` / `references/…`。
 
-If `SKILL.md` grows large because it covers multiple domains, split by reference file:
+在本 harness：解析方式见 **`mstar-host`** § Resolve loaded skill root（omp `skill://`、各宿主插件挂载等）。其它环境按当地 skill 安装约定解析。
 
-```text
-skill-name/
-  SKILL.md
-  references/
-    opencode.md
-    cursor.md
-    codex.md
-```
+## Progressive Disclosure
 
-The body must tell the reader exactly which reference to open and when.
+1. Frontmatter：仅触发  
+2. `SKILL.md`：主执行路径  
+3. `references/` / `templates/` / `scripts/`：变体细节，按需加载  
 
-## Trigger Quality Checklist
+多宿主 / 多域细节按文件拆分，并在 body 写明「何时打开哪份」。
 
-Before committing a skill change:
+## 验证门控（原则 4 + 6）
 
-- Does the description say when to trigger, not merely what the skill contains?
-- Does it include common synonyms and role/task contexts?
-- Does it avoid overbroad terms that would load it constantly?
-- Does the body define conflict ownership?
-- Does it point to one source of truth instead of repeating long rules?
-- Does it state the expected evidence for behavior-shaping changes?
+行为塑形改动必须留下证据，任选可观测形式：
 
-## Pressure Scenarios
+- 2–3 个压力 prompt（无 skill 易失败；有 skill 应通过）
+- before/after 期望 + 触发短语 + 一次具体校验（检索、链接、dry-run）
+- 记录失败原因、token / 延迟回归；未提升则回滚文案
 
-For new skills or major behavior rewrites, write 2-3 pressure prompts that would fail without the skill:
+压力场景骨架：
 
 ```json
 {
-  "skill_name": "mstar-example",
+  "skill_name": "example-skill",
   "evals": [
     {
       "id": 1,
-      "prompt": "A realistic task that tempts the agent to violate the intended rule.",
-      "expected_output": "What compliant behavior looks like.",
+      "prompt": "会诱使 agent 违反目标规则的真实任务",
+      "expected_output": "合规行为长什么样",
       "files": []
     }
   ]
 }
 ```
 
-Good pressure prompts:
-
-- Create the mistake the skill is meant to prevent.
-- Mention realistic artifacts and role boundaries.
-- Have observable pass/fail criteria.
-- Avoid testing trivia from the skill body.
-
-If full eval runs are not practical for the change, record manual evidence: before/after expectation, affected trigger phrase, and one concrete validation step such as search results, link checks, or a dry-run prompt review.
+## 完成时主动说明
 
-## Maintenance Discipline
+写完 / 大改 skill 后必须交代：
 
-- Preserve runtime/maintenance split: skills describe runtime behavior; root `AGENTS.md` describes repository maintenance.
-- Keep role shells thin; reusable behavior belongs in topic skills or role references.
-- Do not introduce parallel manuals for the same workflow.
-- Do not rename or split skills without updating role matrices, README tables, host adapters, and install docs.
-- Behavior-shaping wording changes need evidence: evals, regressions, concrete user outcomes, or a documented failure mode.
+1. **删了 / 压了什么**，以及如何满足原则 2 与 5  
+2. **如何验证原则 6**（paired 证据或压力场景）  
+3. **触发契约**是否仍足够窄（原则 3）
 
 ## Review Template
 
-Use this when reviewing a skill PR:
-
 ```markdown
 ## Skill Review
 - Trigger contract:
+- 5 questions covered:
+- Principles 2/5 compactness:
 - SSOT alignment:
-- Runtime vs maintenance split:
 - Progressive disclosure:
-- Evidence for behavior change:
+- Evidence for behavior change (P6):
 - Stale references checked:
 - Verdict: Approve | Request Changes | Needs Discussion
 ```
+
+## References
+
+| 何时 | 打开 |
+|------|------|
+| 需要完整 skill-writer 流程、原则细则、输出模板 | `references/skillsbench-authoring.md` |

package/harness-skills/mstar-skill-authoring/references/skillsbench-authoring.md

@@ -0,0 +1,117 @@
+# SkillsBench Skill-Writer Reference
+
+Load this only when creating, rewriting, or optimizing a `SKILL.md` and you need the full writer loop. Runtime agents following an already-good skill should not need this file.
+
+## Role
+
+You are a strict AI Agent Skill engineer. When drafting, rewriting, or optimizing **any** `SKILL.md` (any domain, any repo), obey all six principles below. Any violation lowers agent performance.
+
+## Six Principles (refined)
+
+### 1. Start from real expert process, not model improvisation
+
+- Extract the domain expert’s real steps, decision criteria, constraints, API pitfalls, and failure-recovery paths first.
+- Treat the model as editor / implementer only.
+- Accept candidate edits only after an evaluation gate (held-out prompts, pressure scenarios, or concrete before/after checks).
+- Never ship a one-shot model-generated skill as the final version.
+
+### 2. Keep the skill compact and procedural
+
+`SKILL.md` body must stay short. Prefer compact / standard length; long docs rarely help and often hurt.
+
+The body must answer **only** these five questions:
+
+| # | Question | Typical section |
+|---|----------|-----------------|
+| a | When should this skill load? | description + Scope |
+| b | In what order, with which decision points? | Workflow / Decision Rules |
+| c | Which constraints / invariants must never be violated? | Scope / hard rules |
+| d | What does correct look like? | Evidence / success criteria |
+| e | Which extra resources to open when the main path is not enough? | References |
+
+Use progressive disclosure: core path in body; examples, long tables, host variants, schemas → `references/` and load on demand.
+
+Delete or relocate anything that does not serve a–e.
+
+### 3. Load only the 1–3 skills the task truly needs
+
+- Minimize routing. More than ~3 skills dilutes context and lowers pass rate.
+- Write descriptions specific enough for precise matching; include exclusions when over-trigger risk is high.
+- Do not activate unrelated skills “just in case”.
+
+### 4. Test each model + harness combination independently
+
+- File portability ≠ behavior portability.
+- Validate on the actual model and host in use (direct chat / omp / Cursor / Codex / Claude Code / …):
+  - trigger accuracy
+  - execution correctness
+  - token cost
+  - regressions against prior wording
+
+### 5. Encode only gaps the base model cannot reliably fill
+
+Prefer encoding:
+
+- internal conventions and SSOT ownership
+- regulated or safety-critical procedures
+- fragile APIs and host-specific resolution rules
+- professional judgment and recurring failure modes
+
+Do **not** restate generic knowledge the model already has — that wastes tokens and adds noise.
+
+### 6. Treat every skill edit as a controlled experiment
+
+- Require paired evaluation: with-skill vs without-skill, or before vs after with observable criteria.
+- Accept only when success rate and trajectory quality improve on held-out / pressure cases.
+- Record failure reasons, token cost, latency, and regressions.
+- Reject “feels better” judgments.
+
+## Writer workflow
+
+1. **Collect expert path** — steps, branches, invariants, pitfalls, recovery (P1).
+2. **Gap filter** — keep only what the base model misses or mis-orders (P5).
+3. **Draft description** — third person; explicit trigger + exclusion; no workflow summary (P3).
+4. **Draft compact body** — answer the five questions; move bulk to `references/` (P2).
+5. **Wire progressive disclosure** — body names exactly which reference to open when.
+6. **Pressure / paired check** — 2–3 prompts that fail without the skill; confirm improvement (P4, P6).
+7. **Ship note** — list deletions/compressions (P2/P5) and how P6 was verified.
+
+## Output template
+
+```markdown
+### Description
+<third-person trigger + exclusions>
+
+### Body
+<compact SKILL.md answering the five questions>
+
+### Changelog vs prior / draft
+- Removed / compressed: ...
+- Why this serves P2 and P5: ...
+- How P6 was verified: ...
+- Trigger narrowness (P3): ...
+```
+
+## Layout mapping (optional, this harness)
+
+When authoring inside the Morning Star harness repo, map concerns as follows. Outside this repo, ignore this table and use the local project’s entry docs.
+
+| Writer concern | Home in this harness |
+|----------------|----------------------|
+| Global load / conflict | `mstar-harness-core` |
+| Skill authoring rules | this skill (`mstar-skill-authoring`) |
+| Host path resolution | `mstar-host` |
+| Repo maintenance (rename/index) | root `AGENTS.md` |
+| Runtime vs maintenance split | runtime rules in skills; maintenance in `AGENTS.md` |
+
+Default body skeleton and review checklist live in the parent `SKILL.md`; do not duplicate them here unless this reference is read in isolation.
+
+## Anti-patterns
+
+- Pasting a long tutorial into `SKILL.md` “for completeness”
+- Description that narrates the whole procedure
+- Encoding style preferences with no failure mode
+- Copying another skill’s rule into a new skill instead of extending SSOT
+- Accepting edits after a single cherry-picked happy-path demo
+- Bundling multiple domains into one body instead of splitting references
+- Framing a general authoring skill as if it only applied to one product’s skill tree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "1.8.7",
+  "version": "1.8.9",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {