@mstar-harness/opencode 1.8.2 → 1.8.5

package/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.
+- Version alignment with harness **1.8.3** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.3**.
+
+## [1.8.2] - 2026-08-05
+
+- Version alignment with harness **1.8.2** (README/host-detection docs; no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.2**.
+
 ## [1.8.1] - 2026-08-05
 
 - **Bundled skills/commands lossless optimization** (SkillsBench principles): compact `SKILL.md` bodies + progressive disclosure — extracted Phase 3/4/5 and compound workflow to `references/`; compressed `mstar-coding-behavior` and QC review lenses; deduped anti-pattern lists, leaf-role Completion Report/Git NEVER (new `_shared/leaf-executor-core.md`), host role-binding (new `_shared/host-role-binding-core.md`) and plan-mode bridges (new `_shared/plan-mode-bridge-core.md`); slimmed 4 commands to thin boot+route+delegate orchestrators (943 → 388 lines); tightened frontmatter descriptions; `Completion Report v2` → `Completion Report`. No rule, gate, or field name altered or dropped.

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-host
-description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, omp). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, omp task/ask/hub with built-in task.agent types and role-in-prompt binding, sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
+description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, omp). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, omp task/ask/hub preferring live-schema role agents (agents/*.md) with C5b skill-load binding (generic task/scout only as fallback), sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
 ---
 
 # Morning Star Host Adapter
@@ -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/_shared/host-role-binding-core.md

@@ -1,20 +1,26 @@
 # Host role-binding core (C5/C5b)
 
-Shared role-binding contract for hosts that **cannot bind Morning Star roles via agent config** (Kimi, ZCode, omp). Cursor / OpenCode / Codex bind roles through agent config or `subagent_type` role ids and do **not** use this file. Read from the active host reference when dispatching.
+Shared role-binding contract for **Kimi / ZCode** — hosts where Morning Star role ids are **never** valid invoke types, so picking `subagent_type` alone cannot carry Assignment IDENTITY + skill load.
 
-## C5 — built-in invoke types only
+Other hosts follow their own `references/<host>.md` and do **not** use this file for agent selection. Read this file only when the active host reference is Kimi or ZCode.
 
-- The host ships **built-in subagent types only**; the active host reference's C5 mapping table is the authoritative type list.
-- Morning Star role ids (`project-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid invoke types on these hosts — never invent agent names.
+## C5 — invoke type selection (Kimi / ZCode)
+
+| Host | Invoke-type selection (C5) | Prompt role binding (C5b) |
+|------|----------------------------|---------------------------|
+| **Kimi / ZCode** | Built-in types only (`coder` / `explore` / `plan`, …). Morning Star role ids are **never** valid invoke types. | **Required** |
+
+- **Never invent** agent / subagent names. The **live tool schema** (plus the active host reference C5 table) is SSOT every session.
+- Morning Star role ids (`product-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid invoke types — map via the host reference table (`coder` / `explore` / `plan`, …), then rely on C5b.
 
 ## C5b — role binding in prompt (required)
 
-Because the host cannot bind roles via agent config, every dispatch **must** carry the played Morning Star role in the **Assignment** and in the **invoke prompt**:
+Every dispatch on Kimi / ZCode **must** carry the played Morning Star role in the **Assignment** and in the **invoke prompt**:
 
 1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
 2. **`Act as <role-id>`** (or equivalent) at the top of the invoke prompt.
 3. **Skill load list** — instruct the subagent to read `mstar-roles` → `references/<role-id>.md` (or shared reference + parameters) and topic skills per that reference.
-4. **`subagent_type` / `agent`** — pick from the host's built-in types only (C5 table in the host reference).
+4. **`subagent_type`** — pick from the live built-in set per the host C5 table (not a Morning Star role id).
 
 Paste-only Assignment **without** an invoke call is **not** dispatch.
 
@@ -36,9 +42,10 @@ Paste-only Assignment **without** an invoke call is **not** dispatch.
 **Plan Path**: .mstar/plans/20260717-example.md
 
 **IDENTITY:** You ARE `fullstack-dev`. Act as `fullstack-dev` for this task.
+
 Load: `mstar-harness-core` → `mstar-host` → `<host>.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
 
 <task body>
 ```
 
-The active host reference shows the matching invoke shape (same turn).
+The active host reference shows the matching invoke shape (same turn) — e.g. Kimi/ZCode `Agent` with `subagent_type: "coder"` plus this C5b body.

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

@@ -11,14 +11,14 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 - Plugin markers: **`.omp-plugin/plugin.json`** (Morning Star host marker) and **`.claude-plugin/plugin.json`** (Claude-compatible marketplace discovery). Plugin root is the **repo root**; paths stay `./skills/`, `./commands/`, `./agents/`.
 - Runtime skills: repo `skills/` discovered after `omp plugin install` / `omp plugin link` (OMP extension-package sub-discovery) or Claude marketplace install.
 - Plugin commands: repo `commands/<name>.md` → slash **`/<name>`** (e.g. `/iteration-start`). omp uses the **filename** as the command name (no `morning-star-harness:` prefix).
-- Plugin agents: repo `agents/*.md` may be discovered, but Morning Star role ids are **not** assumed to be valid `task.agent` values — see C5/C5b.
+- Plugin agents: repo **`agents/*.md`** are discovered into the live **`task.agent`** list after install/link + reload. Morning Star **subagent** role ids (`product-manager`, `architect`, `fullstack-dev`, `qc-specialist`, …) are valid `agent` values **when listed** — see C5. `project-manager` is **`mode: primary`** (orchestration seat), not a typical `task` dispatch target.
 - **No Kimi-style `sessionStart.skill`** — enter PM manually via **`/skill:pm`** (or the `pm` skill), then **Read next** → `mstar-harness-core` → `project-manager.md`.
 - Install (user-scoped, recommended):
   - `omp plugin install github:btspoony/mstar-harness`
   - or CLI: `npx @mstar-harness/cli init --target omp --scope global` (links `~/.mstar/harness`)
 - Project scope: `omp plugin install github:btspoony/mstar-harness --scope project` or `npx @mstar-harness/cli init --target omp --scope project`.
 - Local maintainers: `omp plugin link /path/to/mstar-harness` (or the CLI-managed `~/.mstar/harness` checkout).
-- After install/link: `omp plugin list` should show package **`morning-star`** (root `package.json` name). Reload / new session to pick up skills and commands.
+- After install/link: `omp plugin list` should show package **`morning-star`** (root `package.json` name). Reload / new session to pick up skills, commands, and agents.
 
 ## Skill loading
 
@@ -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
 
@@ -48,7 +48,7 @@ omp resolves **internal URL schemes** natively (see <https://omp.sh/#urls>), so
 
 | omp tool | Harness use |
 |----------|-------------|
-| **`task`** | Primary dispatch — fan out one or more subagents (`agent` ∈ built-ins; batch via `tasks[]` + shared `context`) |
+| **`task`** | Primary dispatch — fan out one or more subagents (`agent` = live-schema id; prefer Morning Star role id; batch via `tasks[]` + shared `context`) |
 | **`ask`** | Structured clarify (options + recommended); prefer over free-form when choices are known |
 | **`hub`** | Optional peer messaging / long-running process control among subagents — not a substitute for Assignment + `task` |
 | **bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
@@ -68,7 +68,7 @@ task(
   tasks: [
     {
       name: "CamelCaseId",
-      agent: "task",          # built-in only — see C5
+      agent: "<Execute as role-id>",   # prefer live-schema role agent — see C5
       task: "<full Assignment body including Act as + skill load>"
     }
   ]
@@ -79,36 +79,87 @@ Single-task shorthand may exist depending on host version — always match the l
 
 ## Role agents (C5 — hard constraint)
 
-omp ships **built-in `task.agent` types**. Exact names vary by omp version — **read the live `task` tool schema**. Common set (docs + current releases):
+**Live `task` tool schema is SSOT every session.** Exact `agent` names vary by omp version and which `agents/*.md` were discovered after plugin install/link. Read the tool's Available Agents list before dispatch — do not invent names; do not hard-code stale tables over the live list.
 
-| `agent` | Typical use | Harness mapping |
-|---------|-------------|-----------------|
-| `scout` / `explore` | Fast read-only investigation | Orientation, codebase survey, Prepare explore passes |
-| `plan` | Architectural planning | Prepare plan-only work when appropriate |
-| `reviewer` / `security-reviewer` | Structured review | Optional QC assist — still bind Morning Star QC role in prompt (C5b) |
-| `designer` | UI/UX | Optional when Assignment is UI-heavy `frontend-dev` |
-| `librarian` | External library/API research | Optional research assist |
-| `sonic` / `quick_task` | Mechanical / low-reasoning | Mechanical transcription only |
-| `task` | General-purpose worker | **Default for Morning Star roles** (`product-manager`, `fullstack-dev`, `qc-specialist`, …) |
+### Selection order (required)
 
-Morning Star role ids (`project-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid `task.agent` values unless the live schema explicitly lists them after a custom-agent unpack. Do not invent agent names.
+1. **Role match first** — if Assignment `Execute as: <role-id>` appears in the live `task.agent` list, set **`agent: "<role-id>"`**. Examples commonly present after Morning Star plugin discovery: `product-manager`, `architect`, `frontend-dev`, `fullstack-dev`, `fullstack-dev-2`, `ops-engineer`, `prompt-engineer`, `qa-engineer`, `qc-specialist`, `qc-specialist-2`, `qc-specialist-3`, `writing-specialist`.
+2. **Generic built-in only as fallback** — when the role id is **absent** from the live schema, pick the closest host built-in and keep full C5b prompt binding:
+
+| Fallback `agent` | When |
+|------------------|------|
+| `scout` / `explore` | Read-only orientation / codebase survey / Prepare explore |
+| `reviewer` / `security-reviewer` | Optional QC assist **only if** the matching `qc-specialist*` agent is missing |
+| `designer` | UI-heavy work when `frontend-dev` is missing |
+| `librarian` | External library/API research assist |
+| `sonic` / `quick_task` | Mechanical / low-reasoning transcription only |
+| `task` (or omit if schema says omit = general worker) | Last resort general worker when no specialist fits |
+
+3. **Anti-pattern** — **`agent: "task"` (or omitting agent) while a matching role agent is listed** is incorrect dispatch. Prefer the specialist; generic `task` is not the Morning Star default when role agents are available.
+
+### Notes
+
+- `project-manager` is the **primary** orchestration agent (`agents/project-manager.md` `mode: primary`). Do not dispatch PM-to-PM via `task` unless the live schema explicitly lists it **and** the Assignment requires it.
+- Host generics (`scout`, `reviewer`, `designer`, …) remain useful for non-role orientation / assist — they do not replace a listed Morning Star role agent for role-owned deliverables.
 
 ### Role binding in prompt (C5b — required)
 
-Role-binding contract + Assignment template → **`_shared/host-role-binding-core.md`** (C5/C5b). omp-specific invoke shapes, same turn:
+omp C5/C5b SSOT is **this file** — do **not** use `_shared/host-role-binding-core.md` (that file is Kimi/ZCode only). Even when `agent` already matches the role id, still bind Morning Star process in the Assignment / `task` body (agent shell ≠ full role prompt; skill load is not automatic).
+
+Required in every role dispatch:
+
+1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
+2. **`Act as <role-id>`** (or equivalent) at the top of the `task` body.
+3. **Skill load list** — instruct the subagent to read `mstar-roles` → `references/<role-id>.md` (or shared reference + parameters) and topic skills per that reference.
+4. **`agent`** — live-schema role id per C5 above (not “always `task`”).
+
+Paste-only Assignment **without** a `task` invoke is **not** dispatch.
+
+Assignment / prompt template:
+
+```markdown
+## Assignment
+
+**Execute as**: fullstack-dev
+**Delegation**: forbidden
+**Working branch**: feat/example
+**Plan Path**: .mstar/plans/20260717-example.md
+
+**IDENTITY:** You ARE `fullstack-dev`. Act as `fullstack-dev` for this task.
+
+Load: `mstar-harness-core` → `mstar-host` → `omp.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
+
+<task body>
+```
+
+omp invoke shapes, same turn:
 
 ```text
 task(
   context: "Morning Star dispatch for plan 20260717-example",
   tasks: [{
     name: "ImplementAuth",
-    agent: "task",
+    agent: "fullstack-dev",   # live-schema role id matching Execute as
     task: "<full Assignment body including Act as + skill load>"
   }]
 )
 ```
 
-For explore-only orientation:
+Review & Edit / Prepare specialist chain (sequential, **N=1** each turn):
+
+```text
+task(
+  context: "Review & Edit — product scope",
+  tasks: [{
+    name: "ReviewEditProduct",
+    agent: "product-manager",
+    task: "<Assignment: Execute as product-manager; Act as + skill load>"
+  }]
+)
+# wait for return, then architect, then writing-specialist — each with agent: "<role-id>"
+```
+
+For explore-only orientation (no Morning Star role deliverable):
 
 ```text
 task(
@@ -122,24 +173,24 @@ task(
 
 ## PM dispatch (`task`)
 
-Harness **dispatch** on omp = **one or more `task` tool calls** with correct **`agent`** values and role-bound assignment text (C5b → **`_shared/host-role-binding-core.md`**). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.
+Harness **dispatch** on omp = **one or more `task` tool calls** with correct **`agent`** values and role-bound assignment text (C5 + C5b in this file). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.
 
 | Harness | omp |
 |---------|-----|
-| `Execute as: <role-id>` | Role id in Assignment + **Act as** + skill load in **task** body (C5b) |
-| `agent` for invoke | built-ins only (default `task`; explore → `scout`/`explore`) |
+| `Execute as: <role-id>` | **`agent: "<role-id>"`** when listed in live schema; else generic built-in + C5b |
+| Role identity / skills | Assignment **Act as** + skill load in **task** body (C5b) — always |
 | Parallel batch **N** | **N** `tasks[]` entries in **one** `task` call, or **N** `task` calls in **one** assistant message |
 
 ### QC default
 
-- **`Execution mode: sdd`**: **N=3** task entries (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each body **Act as** the respective QC role; prefer `agent: "task"` (or `reviewer` only when it does not drop Morning Star QC skill load). N rules → `parallel-dispatch.md`.
+- **`Execution mode: sdd`**: **N=3** task entries — prefer `agent: "qc-specialist"`, `"qc-specialist-2"`, `"qc-specialist-3"` when listed; each body still **Act as** the respective QC role + QC skill load. If a seat is missing from the live schema, fall back per C5 (generic + C5b) for that seat only. N rules → `parallel-dispatch.md`.
 - **`inline`**: **N=1** per `parallel-dispatch.md`.
 
 Cannot emit required **N** → **`Blocked`**.
 
 ### SDD implement (serial)
 
-- **`Execution mode: sdd`**: one implementer `task` entry per task id; task reviewer = new entry (no sticky resume unless host resume/id is available and recorded). Serial rule → **`parallel-dispatch.md`** § SDD implement.
+- **`Execution mode: sdd`**: one implementer `task` entry per task id with `agent` matching the implementer role when listed; task reviewer = new entry (no sticky resume unless host resume/id is available and recorded). Serial rule → **`parallel-dispatch.md`** § SDD implement.
 - **Never** multiple implementer entries in one message for the same plan.
 
 ## Clarify
@@ -174,6 +225,8 @@ Cannot emit required **N** → **`Blocked`**.
 - Installed npm/git plugin package name is root **`morning-star`** (`package.json`); Morning Star display name remains **morning-star-harness**.
 - Marketplace (Claude) installs and `omp plugin install` are different discovery providers — prefer one install path per machine to avoid duplicate skill listings.
 - Session plan UI / todos are not durable SSOT unless mirrored to `{HARNESS_DIR}`.
-- No custom guaranteed Morning Star `task.agent` profiles — role binding is **always** prompt + skill load (C5b).
+- After install/link, **reload / new session** so `agents/*.md` appear in the live `task.agent` list — stale sessions may only show host generics and wrongly push you to `agent: "task"`.
+- Role agent shell ≠ full role prompt: **C5b skill load remains required** even when `agent` already equals the role id.
 - omp has no `sessionStart.skill`; new sessions do **not** auto-load PM — invoke `/skill:pm` manually.
 - Do not confuse omp **`task.agent`** with OpenCode **`subagent`** or Cursor **`subagent_type`**.
+- Do not treat Kimi/ZCode “built-ins only → always `coder`/`task`” habits as omp defaults when Morning Star role agents are listed.

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/parallel-dispatch.md

@@ -17,7 +17,7 @@ Printing `## Assignment` in the main thread **without** matching host invocation
 
 1. Finalize all `N` Assignment payloads (after any prerequisite turn).
 2. Count distinct `Execute as` sessions (`N`).
-3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type` (JSON field shape → `cursor.md` § Task invoke schema); Kimi: **N `Agent`** calls (each prompt carries **Act as** + skill load; `subagent_type` ∈ {`coder`,`explore`,`plan`} only — see `kimi.md` C5/C5b); omp: **one `task` call with N `tasks[]`** (or N `task` calls) with built-in `agent` + **Act as** / skill load (see `omp.md` C5/C5b); each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
+3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type` (JSON field shape → `cursor.md` § Task invoke schema); Kimi: **N `Agent`** calls (each prompt carries **Act as** + skill load; `subagent_type` ∈ {`coder`,`explore`,`plan`} only — see `kimi.md` C5/C5b); omp: **one `task` call with N `tasks[]`** (or N `task` calls) with `agent` = live-schema role id matching `Execute as` when listed (else generic built-in) + **Act as** / skill load (see `omp.md` C5/C5b); each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
 4. Optionally post a short **Status Update** after invocations (audit trail only — does not replace step 3).
 
 ## Hard rules

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.2",
+  "version": "1.8.5",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {