# Cursor host reference

Load when **`mstar-host`** detection resolves **cursor** (CreatePlan / SwitchMode, Task + `subagent_type`, or Cursor `/pm` flow).

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.

## Runtime and upgrade

- **Runtime**: this host ships no bundled store-backed entrypoint — the plugin mounts skills, commands and rules as text, so the floor belongs to whatever executes: a harness CLI invoked from a Cursor session runs through the installed binary's own Node entrypoint (**Node >=24.18.0**; the explicit `node <bundle>` form is the same floor). A check that needs the engine on a below-floor runtime refuses actionably; there is no transport or JSON fallback.
- **Upgrade / reload**: refresh the plugin's installed copy / rules and start a new Cursor session so the mounted skills and commands come from the new build; editing this checkout changes nothing for an installed plugin until that refresh.
- **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 the Morning Star Cursor plugin. `.cursor-plugin/mcp.json` launches `command: "npx"` with args the harness CLI `mcp` subcommand; the file 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. Existing shared-handler workflow ownership, path, state-transition and CAS checks decide admission.
- **Doctor and evidence**: `mstar-harness doctor --target cursor` (global or project scope) reports aligned / mismatch / unavailable from the MCP launch config, checks the Node floor, and never opens `store.db`. An aligned config is not proof that Cursor loaded or ran the server.

## Coordination transport (no host-native seat)

This host ships no native execution transport: it mounts skills, commands and rules as text, 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.

## Plan mode × harness dual-write

When **Plan mode** is active, **CreatePlan is session UX**; SSOT is **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`) — `{PLAN_DIR}/<plan-id>-<name>.md`, ACTIVE store.db registry/workflow/plan rows.

Before first **CreatePlan**: Read `mstar-conventions`, `mstar-artifacts`, Prepare gates from `mstar-phase-gates` when not hotfix. Full procedure: **`cursor-plan-mode-bridge.md`**.

**Bootstrap CreatePlan todos (prefix, before implement):**

| Todo ID | Purpose |
|---------|---------|
| `harness-init` | Init `{HARNESS_DIR}`, `{PLAN_DIR}`, process-artifact gitignore set (`plans/`, `iterations/`, `sdd/`, `status.json`, `workflows/`, `projects/`, …) via `mstar harness scaffold`, then `mstar store init` for the ACTIVE store |
| `spec-register` | Register store-backed workflow/plan rows through `mstar workflow register`; prepare via `mstar plan prepare` + spec stub if applicable |
| `mirror-plan` | Write SSOT main plan under `{PLAN_DIR}/` |

Each **implement todo**: per–task-ID **git commit** on Working branch → SSOT `- [x]` → PM public plan-state update in store.db → `git log -1 --format='%h %an <%ae>'` evidence.
Each implement todo's commit uses the configured identity; missing/failing identity is Blocked, never fabricate or use `-c` identity overrides → `mstar-roles/references/_shared/leaf-executor-core.md` § Git NEVER (repo writes).

Before **SwitchMode → Agent for ordinary per-plan implementation**: mirror plan exists, `mstar status validate` / `mstar plan show` confirms registered workflow/plan identity, bootstrap todos are done. Never use only the Cursor URI as **Plan Path**. Phase 1 restricted-prototype preparation uses the exception below, not premature formal drafts.

After **Build**: reload `mstar-harness-core` + this reference and resume as PM orchestration on the same carrier. Finish any pending Phase 1 design checkpoint before drafting; dispatch implementation only after its own gates, never from Build alone.

**`mstar-iteration` Phase 1 in Plan mode**: CreatePlan once as a blank session carrier; persist/show §1.2.5 package HTML when permitted; feedback → same-prototype revision → re-presentation until current-design approval, then formal drafts. Select product/architect by remaining gaps and reuse, with mandatory writer last. Formal Review / integration still wait for **Build**. Restricted writes/invoke use the bridge's normal Build / SwitchMode recovery for **prototype preparation only**; no second plan or permission bypass. Details → **`cursor-plan-mode-bridge.md`** § `mstar-iteration` Phase 1 in Plan mode.

Enforcement: `rules/mstar-cursor-plan-mode.mdc` when plugin active.

## `/pm` precedence

1. User explicit instructions
2. Project `AGENTS.md` / `CLAUDE.md`
3. `mstar-harness-core` and `mstar-*` skills
4. `mstar-host` + this reference

## Task tool (QC: SDD → N=3)

- **`Execution mode: sdd`**: **N=3** Tasks (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) + branch review-package path (N rules → `parallel-dispatch.md`).
- **`inline`**: **N=1** per `parallel-dispatch.md`.
- SDD implement/reviewer: ready-task scheduling per **`mstar-sdd`** — implementer Task per task id with `subagent_type` matching the implementer role when listed; task reviewer = new Task with `subagent_type: "code-reviewer"` (Cursor L2 review; not qc-specialist*) when listed, else generic fallback per C5 — no `resume` for reviewers. See **`mstar-sdd`**.

## SDD sticky implementer (Cursor Task resume)

When Assignment has **`SDD implementer session: sticky`** (`mstar-sdd/references/sticky-implementer-session.md`):

| Turn | Task tool |
|------|-----------|
| **First task** (or after `fresh` reset) | `subagent_type: <Execute as>` + `implementer-prompt.md` body; capture returned **agent id** → `{SDD_DIR}/implementer-session.json` → `host_agent_id` |
| **Task 2+** | `resume: <host_agent_id>` + `implementer-continuation-prompt.md` body (new brief path + report path only) |

**Rules:**

- **1 implement dispatch ⇒ 1 Task** per task id (resume counts as the implement dispatch for that task).
- **Task reviewer**: always **new** Task — **no** `resume` for reviewers.
- After each task reviewer passes, PM updates `progress.md` and `implementer-session.json` `last_task`.
- If `resume` fails or agent id missing → reset to **`fresh`** for that task; log reason in Status Update.

## Dispatch execution（canonical）

Cursor PM dispatch = **`Task`** with `subagent_type` matching the Assignment `Execute as` role. Flat JSON field shape → **Task invoke schema (Cursor)** below.

**Role-binding field:** **`subagent_type`** (flat sibling of `prompt`) — must equal the Assignment `Execute as`.
**Engine scope (#156):** Cursor exposes no dispatcher identity, so the caller-scoped `antiRecursionPrecheck` leg is **skipped** on this host — the binding field carries the **spawn target**, and target == `Execute as` is the compliant C5 pattern — and the red line stays **prompt-level** (`mstar-dispatch-gates` § 承接方反递归红线). Caller-side hard enforcement exists only where the host declares a dispatcher binding (`dsh.md`).

- **1 Assignment ⇒ 1 Task**; parallel batches ⇒ **N Tasks in one message** → **`parallel-dispatch.md`** (`mstar-dispatch-gates`).
- Paste-only: Assignment Markdown **does not** start work; PM thread **must not** implement, review, or edit specialist deliverables by loading another role reference in the same session (`Acting as role: …` is **not** dispatch) → **`parallel-dispatch.md`** § Paste-only failure.
- No callable `Task` / subagent for required work → **`Blocked`** — report to user; do not substitute in-thread execution.
- **Only exception:** user explicitly overrides harness dispatch for this turn (document the override).
- Concurrent writers / QC cwd alignment → **`mstar-branch-worktree`** (not a separate “mode”).
- Implement subagents: recipient is already `Execute as`; **no** recursive Task with same `subagent_type`. Assignment wins (`Delegation: forbidden` unless stated).

## Task invoke schema (Cursor)

Cursor’s live **Task** tool expects a **flat** JSON argument object. `prompt` and `subagent_type` are **sibling fields** — not nested, not stringified. Official behavior docs cover subagents/parallel/resume; the flat field shape below is Morning Star’s operational SSOT for Cursor (live-tool contract).

### Canonical flat shape

```json
{
  "description": "3-5 word UI title",
  "prompt": "<full Assignment Markdown body>",
  "subagent_type": "<Execute as role id or built-in>",
  "model": "<optional host slug>",
  "run_in_background": false
}
```

### Required vs optional fields

| Field | Required | Notes |
|-------|----------|-------|
| `prompt` | yes | Full Assignment Markdown string (IDENTITY, gates, Plan Path, Working branch, …) |
| `subagent_type` | yes | Must equal Assignment `Execute as` (Morning Star role id when using custom agents) |
| `description` | recommended | Short UI title only (3–5 words); never the Assignment body |
| `model` | optional | Host slug for the **session's own model policy** — host-owned and optional; mstar prescribes no tier. Omit to inherit the host default |
| `run_in_background` | optional | Default false unless PM intentionally backgrounds |
| `resume` | sticky continue only | Omit on fresh dispatch; see sticky section |

### Must-have example (single dispatch)

```text
Task(
  description: "Implement auth middleware",
  prompt: "<full Assignment body>",
  subagent_type: "fullstack-dev",
  model: "<optional>",
  run_in_background: false
)
```

Rules:

- `subagent_type` **=** Assignment `Execute as` — never OpenCode’s `subagent` key.
- `prompt` = plain Markdown Assignment text, **not** a JSON object string of the whole call.
- `description` = UI title only; do not put the Assignment there.

### Parallel batch (N Tasks, one message)

When `N ≥ 2`, emit **N** separate Task tool calls in **one** assistant message (`parallel-dispatch.md`). Each call is still a flat object with its own `prompt` + `subagent_type`.

### Anti-patterns (do not send)

| Anti-pattern | Correct |
|--------------|---------|
| Args as one stringified JSON blob | Flat sibling fields on the Task tool |
| Field name `subagent` (OpenCode) | `subagent_type` |
| `CallMcpTool` / MCP wrap for Task | Native Task tool only |
| Missing `subagent_type` | Always set; match `Execute as` |
| Assignment JSON stuffed only into `prompt`, no top-level `subagent_type` | Both `prompt` and `subagent_type` present |
| Nested `{ "arguments": { ... } }` Task payload | Flat object at tool-call top level |
| Treating paste-only `## Assignment` as dispatch | Must emit Task call(s) |

### Self-check before send

1. Tool name is **Task** (not MCP, not OpenCode `task`+`subagent`).
2. Top-level keys include **`prompt`** and **`subagent_type`** (siblings).
3. `subagent_type` equals Assignment `Execute as`.
4. `prompt` is Markdown Assignment text, not stringified JSON of the whole call.
5. If sticky continue: `resume` + continuation prompt per sticky section; else omit `resume`.
6. If `N ≥ 2`: this message contains **exactly N** Task calls (`parallel-dispatch.md`).

### Sticky / resume (pointer)

First vs resume field set → **SDD sticky implementer (Cursor Task resume)** above. Do not restate those tables here.

- Fresh: `subagent_type` + full implementer prompt; capture agent id.
- Continue: `resume: <host_agent_id>` + continuation prompt; still flat sibling fields.
- Reviewers: never `resume`.

## Clarify

- No `question` tool: structured Markdown or Cursor UI.
- “Question asked” ≠ clarify done; high-impact ambiguity → `Blocked` or escalation.

## Execution Discipline

Implementation roles use `mstar-coding-behavior` for RCA, test-first checks, review feedback, and completion evidence. Plan checkpoints remain in `mstar-phase-gates`; external skill plugins are not required.

## Gotchas

- Single-seat and tri-review need identical `plan_id` and review scope fields.
- Task parallelism does not relax branch/worktree isolation.

## Project rules

Project `AGENTS.md` / `CLAUDE.md` upward from cwd override global harness defaults when they conflict with Cursor-side rules; user instructions win.