# ZCode host reference

Load when **`mstar-host`** detection resolves **zcode** (ZCode client session, `Agent` / `AskUserQuestion` / `EnterPlanMode` / `TodoWrite` tools, or `/morning-star-harness:*` plugin commands).

Plan mode: read **`zcode-plan-mode-bridge.md`** when `EnterPlanMode` / `ExitPlanMode` is active.

Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2** concurrent `Agent` invocations.

## ZCode-only context

- Plugin manifest: **`.zcode-plugin/plugin.json`** (plugin root is the **repo root**; paths stay `./skills/`, `./commands/`, `./agents/`).
- Runtime skills: repo `skills/` mounted by the plugin (`"skills": "./skills/"`).
- Plugin commands: repo `commands/` → `/morning-star-harness:<name>` (e.g. `/morning-star-harness:iteration-start`).
- Plugin agents: repo `agents/*.md` (role frontmatter `name` + **single-line quoted English `description`** — ZCode's flat frontmatter parser cannot read `|-` block scalars and silently drops nested `tools`/`permission` maps). ZCode registers them as callable `subagent_type`s in both bare (`fullstack-dev`) and plugin-qualified (`morning-star-harness:fullstack-dev`) forms (see C5).
- **No `sessionStart.skill`** (ZCode has no Kimi-style session auto-load) — enter PM manually via **`/morning-star-harness:pm`** or the **`pm`** skill, then **Read next** → `mstar-harness-core` → `project-manager.md`.
- **Plugin hooks** (`hooks/hooks.json`, ZCode-only surface): **SessionStart** injects harness-workspace context ({HARNESS_DIR} + `status.json` summary) when a harness workspace is detected — a partial substitute for the missing session auto-load; **PreToolUse (Bash)** enforces the `mstar-branch-worktree` gates deterministically (no direct commit on the default protected branch → `MSTAR_ALLOW_DEFAULT_BRANCH_COMMIT=1` escape; no bare `git push --force` → use `--force-with-lease`; disable with `MSTAR_BRANCH_GUARD=off`); **PreToolUse (Write|Edit)** runs the engine-backed coordination-write gate: under opt-in `.mstarc`/compass hard enforcement it blocks writes to harness coordination documents (`status.json`, workflow snapshots), and it **unconditionally** refuses the two authority invariants in every mode — a direct write to the issue/catalog store (`{HARNESS_DIR}/store.db`, `-wal`, `-shm`) and a write to a retired project register while the store is the active authority — plus an unreadable authority (below-floor runtime, missing `node:sqlite`, corrupt or busy store), which fails closed with the engine's refusal code. Soft-enforced and unrelated writes still pass silently. Disable the whole hook with `MSTAR_WRITE_GATE=off`. Silent no-op outside git repos / harness workspaces. Skill text stays authoritative; these hooks only backstop it.
- Install (user-scoped, recommended): `npx the harness CLI init --target zcode --scope global`, then in ZCode **Settings → Plugin Management → Discover** install **morning-star-harness** from the **mstar-local** marketplace. Direct-add also works without the CLI: the repo ships `.claude-plugin/marketplace.json` (root `marketplace.json` fallback), which ZCode discovers when refreshing a `github`-source marketplace.
- Plugins are **user-scoped** (all projects); managed copy lives under `~/.zcode/cli/plugins/` after install.
- Project `.agents/skills/` symlinks are **not** required when using the plugin — commands and skills come from the plugin mount.

## Runtime and upgrade

- **Runtime**: the plugin **hooks** are Node scripts — run them under **Node >=24.18.0** (in-process native `node:sqlite`; the store capability is acquired lazily, so a status-only write never opens the database). Harness **commands** invoked as CLI go through the installed binary's own Node entrypoint (**Node >=24.18.0**; the explicit `node <bundle>` form is the same floor) — one runtime floor for both, never two. Below-floor or missing-capability refuses actionably; no transport or JSON fallback.
- **Upgrade / reload**: update **morning-star-harness** from the `mstar-local` marketplace (see § Plugin/CLI version alignment) or re-run `init --target zcode`, then reload the plugin. Materialized sources under `~/.zcode/cli/plugins/` are refreshed by that install, not by editing this checkout.
- **Readiness, not an action**: refreshing an *installed* copy is a bounded, authorized ops act — an authority flip first quiesces, then reloads/upgrades (or explicitly excludes) every installed reader/writer and attests the versions it saw. Editing harness docs or source performs none of it. If this host cannot reload safely, stop at the exact manual-restart step, have the user restart, then re-verify entrypoint/runtime/version/session identity read-only before the flip.

## MCP delivery

- **Native install and loading**: install **morning-star-harness** from the `mstar-local` marketplace. `.zcode-plugin/mcp.json` launches `command: "npx"` with args the harness CLI `mcp` subcommand; its comment requires a published CLI release containing `mcp`. Require **Node >=24.18.0**.
- **Context boundary**: optional `host` selects validated host context, not a role or authority; `sessionId` is the main conversation session. Per-call child-agent attribution is neither required nor performed. Shared workflow ownership, path, transition and CAS checks remain authoritative.
- **Doctor and evidence**: `mstar-harness doctor --target zcode` reports aligned / mismatch / unavailable from the MCP launch config, checks Node's floor, and never opens `store.db`. H6b's config-launched package smoke is superseded by the in-CLI server; installed-host behavior remains unverified and separately authorized.

## Coordination transport (no host-native seat)

This host ships no native execution transport: skills, commands and agents mount as text (plus the ZCode PreToolUse hook, which gates Git commands, not coordination writes), so every coordinated write goes through the **shared CLI** under an **independently acquired execution identity** — the ACTIVE route (`--session-ref` + the addressed scope's full execution token as `--expect` + `--operation`). There is no host-side session file here, no per-call identity injection and nothing to pass down to a child: a session reference is a **lookup, not a bearer credential**, and the engine compares the acquired caller inside its own transaction (→ `mstar-use-cli/references/plan-and-workflow.md`).

Restarting this host or opening a new session does **not** re-issue an identity: a launcher that mints a local identity mints a **new** one, and a copied id is never claimed. A stopped or unreachable coordinator is replaced only by the explicit recovery verb that owns the current authority (`mstar session recover`) — never by restarting a process, re-running a command, or editing a document.

## Skill loading

1. On entry: invoke **`pm`** (via `/morning-star-harness:pm` or `/skill:pm`) → **Read next** loads `mstar-harness-core`, then `mstar-roles` → `project-manager.md` when PM is active.
2. Read `mstar-host` and this ZCode reference.
3. If Plan mode is active, read `zcode-plan-mode-bridge.md`.
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. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.

## Tools map (default agent)

| ZCode tool | Harness use |
|------------|-------------|
| **Agent** | Primary dispatch — delegate one subagent task (`subagent_type`: bare Morning Star role id, e.g. `fullstack-dev`; `general-purpose` fallback; `Explore` read-only) |
| **AskUserQuestion** | Structured clarify (1–4 questions, 2–4 options each); prefer over free-form when choices are known |
| **EnterPlanMode** / **ExitPlanMode** | Plan mode entry/approval → **`zcode-plan-mode-bridge.md`** |
| **TodoWrite** | Session UX only; mirror to authored SSOT plan / store-backed plan row through public plan verbs when durable |
| **Bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
| **Read** | File reads (text + images) |
| **Edit** / **Write** | Edits |
| **Glob** / **Grep** | Search (prefer over shell find/grep) |
| **WebSearch** / **WebFetch** | External docs / facts |
| **Skill** | Invoke bundled skills (`/morning-star-harness:pm`, `mstar-harness-core`, …) |
| **TaskOutput** / **TaskStop** | Long-running task management when present |

OpenCode-style `question`/`task`, Cursor **Task**, and Kimi **AgentSwarm** are **not** ZCode tools — do not assume them.

## Role agents (C5)

ZCode registers the plugin's Morning Star agents (`agents/*.md`) as callable **`subagent_type`** values alongside the built-in profiles, in both **bare role id** (`fullstack-dev`) and **plugin-qualified** (`morning-star-harness:fullstack-dev`) forms. Prefer the **bare role id** (verified on ZCode 0.16.5: the bare form loads the role shell body; the qualified form can silently fall back to the default prompt):

| `subagent_type` | ZCode profile | Harness mapping |
|-----------------|---------------|-----------------|
| `<role-id>` (bare, e.g. `fullstack-dev`, `qc-specialist`) | Registered plugin agent | **Preferred** for the matching Morning Star role |
| `Explore` | Built-in read-only exploration | Orientation, codebase survey, Prepare explore passes |
| `general-purpose` | Built-in general profile | **Universal fallback** when a role id is not exposed |

Role shells are thin — each body only states the role identity and points at the `mstar-roles` skill — so C5b prompt binding stays **required** on every dispatch regardless of `subagent_type`.

### Role binding in prompt (C5b — required)

ZCode C5/C5b SSOT is **this file** — do **not** load `_shared/host-role-binding-core.md` (that file is Kimi only). Role shells are thin (identity + skill pointer, not the full role prompt), so every role dispatch must carry:

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`** — bare Morning Star role id per C5; `general-purpose` fallback.

Paste-only Assignment **without** an invoke call is **not** dispatch. Anti-recursion NEVER: leaf executors are already `Execute as` — no recursive invoke of the same role; Assignment wins (`Delegation: forbidden` unless stated). Independent ready implementers may run concurrently after isolation; scheduling → **`parallel-dispatch.md`** § SDD implement.

**Role-binding field:** **`subagent_type`** — the bare Morning Star role id per C5 (`general-purpose` / `Explore` fallbacks); the thin role shell still needs the C5b prompt binding above.
**Engine scope (#156):** no engine dispatch gate observes caller identity here (the binding field carries the **invoke target**, not the dispatching seat), so this red line stays **prompt-level** (`mstar-dispatch-gates` § 承接方反递归红线). Caller-side hard enforcement exists only where the host declares a dispatcher binding (`dsh.md`).

ZCode invoke shape (same turn):

```text
Agent(
  subagent_type: "fullstack-dev",
  description: "<short task label>",
  prompt: "<full Assignment body including Execute as + Act as + skill load>"
)
```

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` → `zcode.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.

<task body>
```

Role id not exposed (older ZCode) → `subagent_type: "general-purpose"` with the same body. For **`Explore`** orientation:

```text
Agent(subagent_type: "Explore", description: "...", prompt: "... Act as explore-only orientation; Execute as: n/a ...")
```

## PM dispatch (`Agent`)

Harness **dispatch** on ZCode = **one or more `Agent` tool calls** with correct **`subagent_type`** and role-bound prompts (C5b — this file). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.

| Harness | ZCode |
|---------|-------|
| `Execute as: <role-id>` | Role id in Assignment + **Act as** + skill load in **Agent** prompt (C5b) |
| `subagent_type` for invoke | bare role id (e.g. `fullstack-dev`, `qc-specialist`); `general-purpose` fallback; `Explore` for read-only |
| Parallel batch **N** | **N `Agent`** calls in **one assistant message** |

### QC default

- **`Execution mode: sdd`**: **N=3** `Agent` calls (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each prompt **Act as** the respective QC role, all via bare `subagent_type: "qc-specialist"` / `"qc-specialist-2"` / `"qc-specialist-3"` (`general-purpose` fallback; N rules → `parallel-dispatch.md`).
- **`inline`**: **N=1** per `parallel-dispatch.md`.

Cannot emit required **N** → **`Blocked`**.

### SDD implement

- **`Execution mode: sdd`**: one implementer **`Agent`** per task id (bare role id per C5, `general-purpose` fallback); task reviewer = new **`Agent`** with **Act as `code-reviewer`** (`subagent_type: "code-reviewer"`, `general-purpose` fallback; ZCode L2 review; not qc-specialist*), always with C5b prompt binding — no sticky resume unless host adds it later. Ready-task scheduling → **`parallel-dispatch.md`** § SDD implement.
- Independent ready implementers use isolated parallel tracks; never share a writable worktree or session.

## Clarify

- Prefer **`AskUserQuestion`** for 1–3 high-impact choices with known options.
- Fallback: one concise Markdown question after codebase exploration cannot answer it.
- `AskUserQuestion` for plan approval is wrong in Plan mode — use **`ExitPlanMode`** for plan sign-off.
- "Question asked" ≠ clarify done; blocking ambiguity → **`Blocked`** or escalation.

## Commands and skills paths

| Surface | Path / invocation |
|---------|-------------------|
| Plugin skills | `/skill:<skill-name>` or auto-load from `skills/` via plugin |
| Plugin commands | `/morning-star-harness:iteration-start` etc. |
| Session entry | `/morning-star-harness:pm` or `/skill:pm` → `mstar-harness-core` via pm **Read next** |

## Files, shell, and approvals

- Prefer **Glob** / **Grep** for search; **Write** / **Edit** for edits.
- Respect ZCode permission prompts for destructive operations.
- Do not edit `~/.zcode/` credentials, managed plugin copies, or user secrets without explicit consent.

## Git and final evidence

- Git work follows `mstar-branch-worktree` and Assignment **Working branch** / **Branch policy**.
- Completion reports cite concrete commands, artifacts, and commit lines when required.

## Gotchas

- Plugin install materializes source under `~/.zcode/cli/plugins/` — edit the harness checkout + reinstall to pick up harness changes.
- Session todos (`TodoWrite`) are not durable SSOT unless mirrored to `{HARNESS_DIR}`.
- Morning Star roles **are** registered as ZCode subagent types from `agents/*.md` — but the shells are thin, so role binding is **still always** prompt + skill load (C5b); prefer bare role ids, the qualified form can fall back to the default prompt.
- ZCode has no `sessionStart.skill`; new sessions do **not** auto-load PM — invoke `/morning-star-harness:pm` or `/skill:pm` manually.

## Plugin/CLI version alignment

- Installed plugin versions live under `~/.zcode/cli/plugins/cache/<marketplace>/morning-star-harness/<version>/` (one version directory per install; highest semver wins).
- Update entry: **Settings → Plugin Management → update from the `mstar-local` marketplace**.
- Behavioral contract (when to check, which side to update) → **`mstar-harness-core`**「版本对齐（CLI ↔ host 插件）」.