@mstar-harness/omp 3.6.0-alpha.4

package/skills/mstar-host/references/cursor-plan-mode-bridge.md

@@ -0,0 +1,170 @@
+# Cursor Plan Mode × Harness Dual-Write Bridge
+
+> **Load order**: Read **`mstar-harness-core`** first, then **`mstar-host`** and **`references/cursor.md`**, then **`references/_shared/plan-mode-bridge-core.md`** (shared contract) + this bridge. When plan management is required, also read **`mstar-conventions`** and **`mstar-artifacts`** before the first **CreatePlan** in Plan mode. Path symbols `{HARNESS_DIR}`, `{PLAN_DIR}`, `{SPECS_DIR}` are defined in `mstar-conventions`. On conflict, **`mstar-harness-core`** wins.
+
+**Shared contract** (dual-write SSOT rule + priority, bootstrap init, Build resume contract, bootstrap todos, implement done-gate, Phase 1 gate, shared anti-patterns) → **`references/_shared/plan-mode-bridge-core.md`**. This bridge covers Cursor **CreatePlan** / **SwitchMode** / Plan-mode specifics only.
+
+## When this applies
+
+- Cursor **Plan mode** is active (system guidance to use **CreatePlan** / **SwitchMode**).
+- Morning Star plugin or `/pm` is in use (`mstar-host`, `pm` skill, or `rules/mstar-cursor-plan-mode.mdc`).
+
+## Before the first CreatePlan
+
+1. **Read** (minimum): `mstar-conventions`, `mstar-artifacts` (SKILL.md); Prepare gates from `mstar-phase-gates` if not hotfix.
+2. **Discover** `{HARNESS_DIR}` / `{PLAN_DIR}` per `mstar-conventions` (prefer `.mstar/` + `.mstar/plans/`; reuse legacy `.agents/` only when already present and `.mstar/` is absent).
+3. **Initialize** if absent — checklist in core; full PM checklist (incl. process-artifact gitignore set): `mstar-roles/references/project-manager/plan-management.md` (canonical gitignore snippet → `mstar-conventions` SKILL.md「Git 跟踪策略」).
+
+## CreatePlan specifics
+
+Bootstrap todos `harness-init` / `spec-register` / `mirror-plan` (emit first, in order, before any implement todos) → core.
+
+### `spec-register` minimum fields
+
+Add a root `workflows[]` entry to `status.json` (v2) + one `plans[]` object to the workflow snapshot:
+
+```json
+// {HARNESS_DIR}/status.json (v2 root) — active lifecycle entry
+{
+  "id": "<plan-id>",
+  "type": "plan",
+  "started_at": "YYYY-MM-DD",
+  "dir": "workflows/<plan-id>"
+}
+```
+
+```json
+// {WORKFLOW_DIR}/<plan-id>/snapshot.json — plan row (schema_version 1)
+{
+  "id": "<plan-id>",
+  "status": "Todo",
+  "file": ".mstar/plans/<plan-id>-<short-name>.md",
+  "metadata": {
+    "primary_spec": "<spec-id or path if known>",
+    "description": "<one-line summary>"
+  }
+}
+```
+
+Set `updated_at` on `status.json` / the snapshot to today (`YYYY-MM-DD`). Commit **tracked results** in the business repo when applicable: `{HARNESS_DIR}/AGENTS.md`, `{KNOWLEDGE_DIR}/`, `{SPECS_DIR}/` (default git policy — see `mstar-conventions`). Do **not** default `git add` for `status.json`, `workflows/`, `projects/`, `plans/`, or `iterations/`.
+
+### `mirror-plan` minimum content
+
+- YAML or markdown frontmatter with `plan_id`, title, status (`Todo` / `InProgress` — not `Done` unless PM/QA authority).
+- **Task list** as markdown checkboxes (`- [ ]` / `- [x]`) matching CreatePlan implement todos.
+- **Roadmap / deferred scope** section when delivery is staged, partial, or uses a temporary workaround.
+- Link: “SSOT status: `{HARNESS_DIR}/status.json` (v2 `workflows[]`) → `{WORKFLOW_DIR}/<id>/snapshot.json` `plans[]`; open residuals → `{PROJECT_DIR}/<id>/residuals.json`.”
+
+After **CreatePlan**, keep CreatePlan body and mirror file **in sync** when scope changes (update both in the same coordination round).
+
+### CreatePlan body template (copyable)
+
+Use this structure in CreatePlan `plan` markdown; mirror the same sections into `{PLAN_DIR}/<plan-id>-<name>.md`.
+
+```markdown
+# Plan: <title>
+
+**plan_id**: <plan-id>
+**HARNESS_DIR**: .mstar/
+**Plan file (SSOT)**: .mstar/plans/<plan-id>-<short-name>.md
+**status.json**: .mstar/status.json
+
+## Prepare gates
+
+- specify: [done|n/a]
+- clarify: [done|n/a]
+- plan: [done|in progress]
+
+## Roadmap / deferred scope
+
+- Target state: <complete outcome>
+- Current slice: <what this plan/batch delivers>
+- Later slices: <batch/order/owner or trigger>
+- Deferred scope / temporary workaround removal: <tracking location or N/A>
+- Final Done definition: <condition for full completion>
+
+## Tasks (mirror as checkboxes in SSOT plan file)
+
+### Bootstrap (fixed prefix — complete before implement)
+
+1. harness-init — init .mstar/, status.json (v2), process-artifact gitignore set
+2. spec-register — register the root `workflows[]` entry + snapshot plan row; spec stub if applicable
+3. mirror-plan — write .mstar/plans/<plan-id>-<short-name>.md
+
+### Implement
+
+- [ ] <task-id-1>: <description>
+  - Done when: git commit on Working branch + checkbox [x] in SSOT plan + evidence below
+- [ ] <task-id-2>: ...
+
+## Working branch
+
+<branch-name or "PM to assign before implement">
+
+## Verification
+
+- Commands / tests required before InReview
+```
+
+## Implement todo completion gate (every code todo)
+
+Commit → SSOT checkbox → `status.json` sync → `git log -1 --oneline` evidence; NEVER list → core. Dev-role NEVER rules also apply when executing as implementer: `mstar-roles/references/fullstack-dev-shared.md` (Git NEVER).
+
+## SwitchMode → Agent (pre-flight)
+
+Before switching from Plan to Agent for implementation (or declaring Plan phase complete):
+
+- [ ] `{PLAN_DIR}/<plan-id>-<name>.md` exists on disk
+- [ ] Root `status.json` `workflows[]` contains the entry and `{WORKFLOW_DIR}/<id>/snapshot.json` contains the `plans[]` row with matching `id` and `file`
+- [ ] Bootstrap todos `harness-init`, `spec-register`, `mirror-plan` are **done**
+- [ ] CreatePlan implement todos reference **task ids** traceable to SSOT plan checkboxes
+- [ ] If staged/partial/temporary, CreatePlan and SSOT plan both contain `Roadmap / deferred scope`
+- [ ] **Plan Path** for any Assignment uses the SSOT path, not the Cursor plan URI
+
+If any item fails → **Blocked**; finish harness sync before implement.
+
+## Build resume contract
+
+→ core. Cursor delta: **Build** resumes the current plan in Agent mode; do not assume it replays `/pm` or re-enters a role skill automatically.
+
+## PM in Plan mode (`/pm`)
+
+When `/pm` runs under Plan mode:
+
+- Load this reference via **`mstar-host`** (Cursor detection) after `mstar-harness-core`.
+- **CreatePlan** todos **must** include the three bootstrap prefix items.
+- Prepare phase (`specify → clarify → plan`) still applies; `mirror-plan` is the harness **`plan`** artifact, not a substitute for clarify.
+- Before QC dispatch, read **`mstar-review-qc`** (unchanged).
+
+## `mstar-iteration` Phase 1 in Plan mode
+
+When starting a **new iteration** under Cursor Plan mode (host command may orchestrate Phase 1):
+
+| Phase | Behavior | Forbidden |
+|-------|----------|-----------|
+| Early CreatePlan | After read-only research, **CreatePlan once** with blank Phase 1 scaffold + Build-bound todos; **record the returned plan file path** | Wait until direction lock finishes; call CreatePlan again later |
+| Feedback loop | User gives **direction / opinions only** (no questionnaire). Agent explores, recommends, and **edits that same plan file in place** (+ SSOT drafts). Absorb feedback → update again | Routine one-question-at-a-time interview; gate plan updates on user answers; write a second `*.plan.md`; open interview helpers before feedback-close |
+| Feedback-close | When user signals feedback done (e.g. 反馈结束 / 总结 / 准备 Build): if blocking gaps remain → **minimal** deferred interview on gaps only, still editing the **same** plan file; else ready for Build | Start the interview helper as the main Plan-session loop |
+| Pre-Build | Maintain documents only | Execute Review chain, commit, or create `spec_integration_branch` |
+| Build | Finalize SSOT from the **same** CreatePlan body → sequential Review & Edit → PM lock → integration branch | Replay feedback/interview; finalize from a different plan URI than View Plan |
+
+**Single CreatePlan URI (HARD)**: one CreatePlan per Phase 1 Plan session. Updates use file edit tools on that path. If a duplicate plan file was created by mistake: merge into the original, delete the duplicate, keep View Plan on the original.
+
+**Bootstrap relationship**: ordinary per-plan work still uses `harness-init` / `spec-register` / `mirror-plan`. Phase 1 CreatePlan uses Phase 1 todos (`harness-init` → `finalize-compass-plans` → review-edit seats → `pm-lock` → `integration-branch`). Snapshot `plans[]` rows should exist as drafts before Build when direction has converged.
+
+**Helpers**: third-party interview helpers are **not** named here; host **command** layer may use them only after feedback-close when gaps remain.
+
+## Anti-patterns (Cursor-specific)
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Follow-up only in chat / no roadmap section | Add `Roadmap / deferred scope` to CreatePlan and SSOT plan before implement |
+| Phase 1 Plan mode: second CreatePlan / stale open plan | Edit the original plan file only; merge+delete duplicates |
+| Phase 1 Plan mode: interview loop before feedback-close | Feedback-driven autonomous plan updates; deferred interview only after close signal if gaps remain |
+
+## Related skills
+
+- `mstar-conventions` — discovery, init, plan-writing path gate
+- `mstar-artifacts` — `status.json`, review bundle summaries, checkboxes, residual
+- `mstar-phase-gates` — Prepare / Execute order
+- `mstar-roles/references/project-manager/dispatch-and-assignment.md` — Checkpoint: commit → Completion Report → Status Update

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

@@ -0,0 +1,183 @@
+# 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.
+
+## 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`, `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` 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/`, …), `status.json` (v2 template) |
+| `spec-register` | Register the root `workflows[]` entry + snapshot plan row (`{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`) + 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]` → optional snapshot sync → `git log -1 --oneline` evidence.
+
+Before **SwitchMode → Agent**: mirror plan exists; snapshot lists `plan_id` + root `workflows[]` entry; bootstrap todos done. **Never** use only the Cursor plan URI as **Plan Path**.
+
+After **Build**: treat the run as plan resume, not `/pm` replay. Reload `mstar-harness-core` + this Cursor reference, resume Morning Star plans as `project-manager` orchestration, and dispatch implementation through Task unless the user explicitly overrides the harness.
+
+**`mstar-iteration` Phase 1 in Plan mode**: CreatePlan **once** (blank scaffold); then **feedback-driven** in-place updates on that same plan file; deferred interview only after user signals feedback-close **and** gaps remain; **do not** run Review & Edit / commit / integration branch until **Build**. Detail → **`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: **serial** — 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.
+
+- **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 from Assignment **Model tier** mapping |
+| `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.
+
+## Model tier (SDD + QC)
+
+Map Assignment **`Model tier`** to Task `model` (host-specific slugs):
+
+| Tier | Typical use |
+|------|-------------|
+| `fast` | Transcription tasks; 1–2 file mechanical edits |
+| `standard` | SDD prose implementer; task reviewer floor; plan QC tri seats |
+| `capable` | Large branch QC diff; integration judgment |
+
+**Turn count beats token price** — reviewers and prose implementers use `standard` floor minimum. See `mstar-sdd` SKILL.
+
+## Project rules
+
+Project `AGENTS.md` / `CLAUDE.md` upward from cwd override global harness defaults when they conflict with Cursor-side rules; user instructions win.