@mstar-harness/opencode 1.8.3 → 1.8.5

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface re
 
 ## [Unreleased]
 
+## [1.8.5] - 2026-08-06
+
+### Bundled harness skills (`harness-skills/` at publish)
+
+- Sync `mstar-host` § Resolve loaded skill root + host-reference skill-root cues; `mstar-skill-authoring` anti-pattern for rules/CLI cwd paths.
+- Version alignment with harness **1.8.5** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.5**.
+
+## [1.8.4] - 2026-08-06
+
+- **Bundled skills**: skill-relative script path naming (`mstar-sdd` → `scripts/…`) so agents resolve scripts from the loaded skill directory instead of consumer-cwd `skills/…` paths.
+- Version alignment with harness **1.8.4** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.4**.
+
 ## [1.8.3] - 2026-08-05
 
 - **Bundled skills**: omp host C5 corrected — prefer live-schema Morning Star role `task.agent` values from discovered `agents/*.md`; keep C5b skill load; update shared host-role-binding + parallel-dispatch docs.

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

@@ -41,6 +41,20 @@ Order matters: check `cursor` → `opencode` → `omp` → `kimi` → `zcode`
 
 When PM dispatches **N >= 2** concurrent assignees (QC tri-review, dual-track implement, etc.) and the host exposes actual invoke / Task / subagent tools, read **`references/parallel-dispatch.md`** in the dispatch round (shared with `mstar-dispatch-gates`). Without a callable invoke tool when dispatch is required → **`Blocked`**; Assignment Markdown alone is not dispatch.
 
+## Resolve loaded skill root
+
+Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **Resolve the loaded skill directory first** — do **not** open `skills/<name>/…` from a consumer app cwd (that layout exists in the harness source / plugin package only).
+
+| Host | Prefer | Filesystem fallback (only if the host cannot load by name) |
+|------|--------|--------------------------------------------------------------|
+| **omp** | `skill://<name>` / `skill://<name>/<rel>` / `/skill:<name>` | Plugin package root `skills/<name>/` after install/link — not app cwd |
+| **Cursor** | Skill **name** via plugin skills | Global `~/.cursor/plugins/local/morning-star-harness/skills/<name>/`; project `.cursor/plugins/morning-star-harness/skills/<name>/` |
+| **Codex** | Skill **name** via plugin | Plugin-mounted `skills/<name>/`; project command skills under `.agents/skills/<name>/` |
+| **OpenCode** | Skill **name** via `@mstar-harness/opencode` | Package-internal `harness-skills/<name>/` — never `process.cwd()/skills/` |
+| **Kimi / ZCode** | Skill **name** / `/skill:<name>` | Plugin mount `./skills/<name>/` from the installed plugin root |
+
+Authoring convention: **`mstar-skill-authoring`** § Skill-relative script and asset paths. Per-host URI / mount detail: `references/<host>.md`.
+
 ## Conflict order
 
 1. User explicit instructions (this turn)

package/harness-skills/mstar-host/references/codex.md

@@ -23,7 +23,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless the user is maintaining this repository or the skill is not installed and must be read from the checkout.
+Use skill names in prompts and references. Avoid absolute local paths unless the user is maintaining this repository or the skill is not installed and must be read from the checkout. Skill-root resolve (plugin `skills/<name>/`, project `.agents/skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Clarify
 

package/harness-skills/mstar-host/references/cursor.md

@@ -6,6 +6,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (Task tool uses same turn model
 
 ## Cursor-only context
 
+- Skill root: load by skill **name**; filesystem fallback → `mstar-host` § Resolve loaded skill root (`~/.cursor/plugins/local/morning-star-harness/skills/<name>/` or project `.cursor/plugins/morning-star-harness/skills/<name>/`). Never app-cwd `skills/<name>/`.
 - Role prompts: `mstar-roles`; **`/pm`** or **`pm` skill** → general PM orchestration (per-plan dispatch, gates, QC) without an iteration command. Host **`commands/`** for formal iteration Phase 1–5 (semantics → **`mstar-iteration`**).
 - Routing-eval: `.cursor/skills/mstar-routing-eval/` — regression tooling only; not runtime load order.
 

package/harness-skills/mstar-host/references/kimi.md

@@ -25,7 +25,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed.
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Tools map (default agent)
 

package/harness-skills/mstar-host/references/omp.md

@@ -28,7 +28,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Prefer `skill://<name>/…` / `/skill:<name>` over absolute local paths unless maintaining this repository.
+Use skill names in prompts and references. Prefer `skill://<name>/…` / `/skill:<name>` over absolute local paths unless maintaining this repository. Full skill-root table (all hosts) → `mstar-host` § Resolve loaded skill root.
 
 ## Internal URLs
 

package/harness-skills/mstar-host/references/opencode.md

@@ -6,6 +6,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (read in dispatch rounds).
 
 ## Role loading
 
+- Skill root: load by skill **name** from `@mstar-harness/opencode` (`harness-skills/<name>/` inside the package). Never `process.cwd()/skills/` — see `mstar-host` § Resolve loaded skill root.
 - **PM entry**: **`/pm`** or **`pm` skill** → `project-manager` for general orchestration; host **`commands/`** for formal iteration Phase 1–5 (semantics → **`mstar-iteration`**).
 - **Role shell**: `agents/<id>.md` referenced by `opencode.json` `agent.<id>` (frontmatter + role binding only).
 - **Role body**: `mstar-roles` `references/<id>.md` (or shared references + parameters).

package/harness-skills/mstar-host/references/zcode.md

@@ -25,7 +25,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed.
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Tools map (default agent)
 

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

@@ -288,10 +288,10 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree；plans / status / iterations / SDD 经 control 绝对路径）：
    - **默认 `Execution mode: sdd`**（多 task plan；hotfix 可 `inline`）。
    - PM 载入 **`mstar-sdd`** 后，按 plan task 顺序 **串行** per-task 循环（**不是**一次派发 dev 做全部 tasks）：
-     1. `sdd-workspace <plan-id>` → `{SDD_DIR}`
-     2. `task-brief <plan-file> N` → `{SDD_DIR}/task-N-brief.md`；记录 `BASE_SHA`
+     1. skill **`mstar-sdd`** → `scripts/sdd-workspace <plan-id>` → `{SDD_DIR}`
+     2. `scripts/task-brief <plan-file> N` → `{SDD_DIR}/task-N-brief.md`；记录 `BASE_SHA`
      3. Dispatch **one** implementer subagent（`references/implementer-prompt.md`：brief 路径 + report 路径 + `Model tier`；**禁止**贴整份 plan）
-     4. Implementer `DONE` → `review-package BASE HEAD` → task diff 文件
+     4. Implementer `DONE` → `scripts/review-package BASE HEAD` → task diff 文件
      5. Dispatch **one** task reviewer subagent（brief + report + diff + Global Constraints）
      6. Fix loop 直至 review clean；append `{SDD_DIR}/progress.md`；更新 `status.json` / plan checkbox
      7. Next task
@@ -320,7 +320,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 | 文件交接 | brief / report / diff / `progress.md` 在 `{SDD_DIR}`；dispatch prompt **只给路径**，不贴 plan 全文或 task 历史 |
 | Assignment 字段 | 每个 implement dispatch 须含 `Execution mode: sdd`、`SDD dir`、`Model tier`；§2.0 #5 未 waive 时还须含绝对 `Worktree path` + verified `execution_lease`；**禁止**省略 `Model tier` |
 | 大包 inline | **禁止**把 T1–Tn 或整份 plan 写进 **一个** `fullstack-dev` leaf Assignment 冒充 SDD |
-| 分支 diff | 全部 task 完成后 `review-package MERGE_BASE HEAD` → `{SDD_DIR}/review/` branch diff → plan QC tri（N=3） |
+| 分支 diff | 全部 task 完成后 skill **`mstar-sdd`** → `scripts/review-package MERGE_BASE HEAD` → `{SDD_DIR}/review/` branch diff → plan QC tri（N=3） |
 
 Iteration Phase 2 附加：
 

package/harness-skills/mstar-plan-artifacts/references/status-and-residuals.md

@@ -475,7 +475,8 @@ Prefer **`archived/residuals/`**; migrate and delete history key when possible.
 # Replace .mstar with your resolved {HARNESS_DIR}; legacy projects may use .agents.
 jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .mstar/status.json
 jq '.entries[] | select(.id == "R1")' .mstar/archived/residuals/01-data-infrastructure.json
-bash skills/mstar-plan-artifacts/scripts/tech-debt-rollup.sh .mstar/status.json
+# skill mstar-plan-artifacts → scripts/tech-debt-rollup.sh (not a consumer cwd path)
+bash <mstar-plan-artifacts>/scripts/tech-debt-rollup.sh .mstar/status.json
 ```
 
 (`//` right-hand side = legacy read path.)
@@ -508,8 +509,9 @@ Append-only log for merge closure, batch archive, `tech_debt_summary` refresh, e
 **Compute (canonical):** run the read-only script (do **not** hand-count):
 
 ```bash
-# From repo root; pass path to status.json if not .mstar/status.json
-bash skills/mstar-plan-artifacts/scripts/tech-debt-rollup.sh .mstar/status.json
+# Resolve from skill mstar-plan-artifacts → scripts/tech-debt-rollup.sh
+# Pass path to status.json if not .mstar/status.json
+bash <mstar-plan-artifacts>/scripts/tech-debt-rollup.sh .mstar/status.json
 ```
 
 - Prints computed `total_open`, `by_severity`, `by_target`, `by_plan`.

package/harness-skills/mstar-plan-conventions/SKILL.md

@@ -65,7 +65,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 PM 在需要持久化追踪时：
 
 1. 建 `.mstar/`、`plans/`、`status.json`（空模板见 **`mstar-plan-artifacts/templates/status.empty.json`**）
-2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 `mstar-sdd/scripts/sdd-workspace` 创建）
+2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 skill **`mstar-sdd`** → `scripts/sdd-workspace` 创建）
 3. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（见下文「Git 跟踪策略」）— CLI `init` 可自动添加
 4. Git：**进程本地、结果共享** — 默认跟踪 `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**`；`plans/`、`iterations/`、`status.json` 等为**本地会话 SSOT**，默认 gitignored。跨 clone 持久 handoff = knowledge + specs + `{HARNESS_DIR}/AGENTS.md`（及根 `CONCEPTS.md` / `STRATEGY.md` 若使用）；须跨 clone 的 residual 须提升（compound）或写入 tracked results — **勿**默认 `git add` `status.json` / `plans/`。
 

package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md

@@ -14,7 +14,7 @@
 
 1. 创建 `{HARNESS_DIR}`（推荐 `.mstar/`）与 `{PLAN_DIR}`（推荐 `.mstar/plans/`）。
 2. 初始化 `status.json`：从 **`mstar-plan-artifacts/templates/status.empty.json`** 复制；residual canonical 见 **`mstar-plan-artifacts` SKILL.md**；字段与生命周期见 **`mstar-plan-artifacts/references/status-and-residuals.md`**。
-3. 初始化可选 `notes.json`（**`mstar-plan-artifacts/templates/notes.empty.json`**）；`sdd/` 空目录占位（per-plan 子目录由 `mstar-sdd/scripts/sdd-workspace` 创建）。
+3. 初始化可选 `notes.json`（**`mstar-plan-artifacts/templates/notes.empty.json`**）；`sdd/` 空目录占位（per-plan 子目录由 skill **`mstar-sdd`** → `scripts/sdd-workspace` 创建）。
 4. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」；legacy `.agents/` 有等价表）。
 5. **Profile B**（统一 Done 压缩）时另建 `{HARNESS_DIR}/archived/plans/` 与 `archived/plans-done.json`（自 **`mstar-plan-artifacts/templates/plans-done.empty.json`** 复制；schema 仅 `{ "plans": [] }`，见 **`mstar-plan-artifacts/references/done-compaction.md`**）。
 6. 可选：创建 `{ITERATION_DIR}`（`iterations/` + `README.md`）与 `{KNOWLEDGE_DIR}`（`knowledge/` + `README.md`）；`{HARNESS_DIR}/specs/`（解析后的 `{SPECS_DIR}` 默认落点）；内容边界见 `mstar-plan-conventions` SKILL.md 与 `references/knowledge-and-designs.md`。

package/harness-skills/mstar-roles/references/project-manager/dispatch-and-assignment.md

@@ -137,7 +137,7 @@ When `metadata.control_worktree_path` is set and worktree mode is **not** waived
 | **`Worktree path`** | Absolute **feature** checkout (`execution_lease.worktree_path`) — product/source edits only |
 | **`Control harness root`** | Absolute `<control_worktree_path>/{HARNESS_DIR}` |
 | **`Plan Path`** | Absolute under control harness (not relative from feature cwd) |
-| **`SDD dir`** | Absolute under control harness; run `sdd-workspace` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
+| **`SDD dir`** | Absolute under control harness; run skill **`mstar-sdd`** → `scripts/sdd-workspace` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
 
 Do **not** waive worktree because default-gitignored `plans/` are missing under the feature checkout — see `mstar-branch-worktree` 「Harness path SSOT under default gitignore」.
 ## Completion Report Template

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

@@ -39,12 +39,12 @@ Batch all findings for the human in one message. If clean, proceed silently.
 ## Per-task loop (PM only)
 
 1. Record `BASE_SHA` (never use `HEAD~1` later)
-2. `sdd-workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `sdd-workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
-3. `task-brief <plan> N` → brief file
+2. skill **`mstar-sdd`** → `scripts/sdd-workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `scripts/sdd-workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
+3. `scripts/task-brief <plan> N` → brief file
 4. Dispatch implementer:
    - **`SDD implementer session: fresh`** (default) — new subagent; templates: `references/implementer-prompt.md`
    - **`SDD implementer session: sticky`** — first task: same as fresh + write `{SDD_DIR}/implementer-session.json` with `host_agent_id`; later tasks: host **resume** + `references/implementer-continuation-prompt.md` (see **`references/sticky-implementer-session.md`**)
-5. On `DONE`: `review-package BASE HEAD` → diff file
+5. On `DONE`: `scripts/review-package BASE HEAD` → diff file
 6. Dispatch **fresh** task reviewer — **`subagent_type: generalPurpose`** (L2; **not** `qc-specialist*`) — brief, report, diff, Global Constraints — `references/task-reviewer-prompt.md` — **never** sticky resume for reviewers
 7. Fix loop for Critical/Important; re-review until approved
 8. Append `progress.md`; update `status.json` `task_commits[]` and `implementer-session.json` `last_task` if sticky
@@ -81,7 +81,7 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
 
 ## After all tasks
 
-1. `review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
+1. `scripts/review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
 2. PM dispatches **plan QC tri-review (L3)** — **`QC mode: full tri-review`**, **N=3** — with branch review-package path and report paths under `{SDD_DIR}/review/` → **`mstar-review-qc`** · **`mstar-dispatch-gates`**. Layer SSOT → **`mstar-review-qc/references/review-responsibility-boundaries.md`**. PM writes `{SDD_DIR}/review/qc-consolidated.md` and durable main-plan gate summary. **Mandatory whenever `Execution mode: sdd`** (single-plan or iteration).
 3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review
 4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
@@ -109,13 +109,15 @@ Minor findings → `## Minor (for plan QC)` section in same file.
 
 ## Scripts
 
-From repo: `skills/mstar-sdd/scripts/` (bundled in OpenCode as `harness-skills/mstar-sdd/scripts/`).
+Scripts live under this skill: **`mstar-sdd`** → `scripts/<name>`.
+
+Resolve the loaded **`mstar-sdd`** skill directory first, then run the script by skill-relative path. **Do not** treat `skills/mstar-sdd/scripts/...` as a consumer-project cwd path — that layout exists only in the harness source tree (and OpenCode's bundled `harness-skills/mstar-sdd/scripts/`).
 
 | Script | Usage |
 |--------|--------|
-| `sdd-workspace` | `PLAN_ID [CONTROL_ROOT]` → creates `{SDD_DIR}` under control harness when set (`MSTAR_CONTROL_ROOT` or 2nd arg); fail closed on linked worktree without `status.json` |
-| `task-brief` | `PLAN_FILE TASK_N [OUTFILE]` |
-| `review-package` | `BASE HEAD [OUTFILE]` |
+| `scripts/sdd-workspace` | `PLAN_ID [CONTROL_ROOT]` → creates `{SDD_DIR}` under control harness when set (`MSTAR_CONTROL_ROOT` or 2nd arg); fail closed on linked worktree without `status.json` |
+| `scripts/task-brief` | `PLAN_FILE TASK_N [OUTFILE]` |
+| `scripts/review-package` | `BASE HEAD [OUTFILE]` |
 
 ## References
 

package/harness-skills/mstar-sdd/references/file-handoffs.md

@@ -4,12 +4,14 @@ PM and subagents move artifacts as **files**, not pasted text. Pasted content st
 
 ## Before implementer dispatch
 
-1. `export SDD_DIR=$(skills/mstar-sdd/scripts/sdd-workspace <plan-id>)`
+Resolve scripts from skill **`mstar-sdd`** → `scripts/…` (loaded skill directory). Do **not** run `skills/mstar-sdd/scripts/…` from a consumer project cwd.
+
+1. `export SDD_DIR=$(<mstar-sdd>/scripts/sdd-workspace <plan-id>)`
    - Iteration L1 (implementer cwd = feature worktree):  
      `export MSTAR_CONTROL_ROOT=<control_worktree_path>`  
      or `sdd-workspace <plan-id> <control_worktree_path>`  
      so `{SDD_DIR}` lands on the control harness (default-gitignored plans/status/sdd). Do not create a second SDD tree under the feature checkout.
-2. `skills/mstar-sdd/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
+2. `<mstar-sdd>/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
 3. Record `BASE_SHA` (`git rev-parse HEAD` before dispatch).
 4. Dispatch implementer with:
    - One line scene-setting (where task fits)
@@ -31,7 +33,7 @@ Implementer writes full report to `task-N-report.md`. Return to PM only:
 ## After implementer DONE
 
 1. `HEAD_SHA=$(git rev-parse HEAD)`
-2. `skills/mstar-sdd/scripts/review-package "$BASE_SHA" "$HEAD_SHA" "$SDD_DIR/review-....diff"`
+2. `<mstar-sdd>/scripts/review-package "$BASE_SHA" "$HEAD_SHA" "$SDD_DIR/review-....diff"`
 3. Dispatch task reviewer with: brief path, report path, diff path, Global Constraints (verbatim from plan).
 
 **Never use `HEAD~1` as BASE** — multi-commit tasks truncate.
@@ -63,7 +65,7 @@ After all tasks:
 ```bash
 MERGE_BASE=$(git merge-base <target-branch> HEAD)
 mkdir -p "$SDD_DIR/review"
-skills/mstar-sdd/scripts/review-package "$MERGE_BASE" HEAD "$SDD_DIR/review/branch-review-....diff"
+<mstar-sdd>/scripts/review-package "$MERGE_BASE" HEAD "$SDD_DIR/review/branch-review-....diff"
 ```
 
 Pass **branch** diff path and bundle report paths (`$SDD_DIR/review/qc1.md` …) to QC dispatch — not task-level diffs. Raw QC/QA files stay in the gitignored review bundle; PM records durable summary and open residuals in **local** plan/`status.json` (session SSOT) and promotes cross-clone decisions into tracked knowledge/specs/`AGENTS.md` per `mstar-plan-conventions` git policy.

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

@@ -103,6 +103,17 @@ 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
 
 Use three levels:

package/package.json

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