@mstar-harness/opencode 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to the `@mstar-harness/opencode` package are documented in t
 
 The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface releases.
 
+## 1.3.0
+
+- Bundled commands: retire `/mstar-bootstrap`; bootstrap procedure → `mstar-compound-refresh/references/project-knowledge-bootstrap.md`.
+- Bundled skills: `mstar-compound-refresh` and `mstar-harness-core` short pointers for project knowledge bootstrap.
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.3.0**.
+
+## 1.2.1
+
+- Bundled commands: `/iteration-start` Cursor Plan mode path — blank Phase 1 CreatePlan scaffold, staged grill-me plan updates, Build-gated Review chain.
+- Bundled skills: `mstar-iteration` §1.2 host Plan UX scaffold-then-converge; `mstar-host` Cursor Phase 1 Plan mode bridge (no command-name reverse refs).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.2.1**.
+
 ## 1.2.0
 
 - Bundled commands: add `/iteration-loop` (autonomous Phase 1→5; optional `direction` + `scale`).

package/README.md

@@ -28,7 +28,7 @@ npx @mstar-harness/cli init --target opencode
 |-----------------|----------|
 | `harness-skills/` | `mstar-harness-core`, `mstar-iteration`, `mstar-sdd`, roles, phase/dispatch gates, … |
 | `harness-agents/` | Role shells (`project-manager`, `fullstack-dev`, `qc-specialist`, …) |
-| `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/mstar-bootstrap` |
+| `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/iteration-loop` |
 
 The plugin resolves **only paths inside this package** — not `process.cwd()/skills`, so your app repo root does not affect harness loading.
 

package/harness-commands/iteration-start.md

@@ -22,17 +22,106 @@ Start a new Morning Star harness iteration. **Not Done until the Review & Edit c
 
 **完成定义**：compass `status: locked` + 三角色 invoke 已返回 + pre-commit checklist 全 `[x]` — 不是初稿落盘。
 
-Detailed workflow → **`mstar-iteration` § Phase 1: iteration-start**（含 §1.6 Review & Edit chain）；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
+Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit chain）；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
+
+**Path split（HARD）**：
+
+| 宿主上下文 | 走哪条 |
+|------------|--------|
+| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → §P（本命令 Plan 分支）— **先**空白 CreatePlan，再动态 grill-me 改文档；**Build 前不执行** Review 链 / commit / integration 分支 |
+| **其它**（Agent、OpenCode、非 Plan） | §0 Boot → §1–§6（Research → Explore → grill-me → Write → Review → branch） |
 
 ## 0. Boot
 
 1. `mstar-harness-core`
 2. `mstar-roles` → `references/project-manager.md`
-3. `mstar-iteration` → **§ Phase 1: iteration-start**（迭代范围、compass 模板、**§1.5.5 产物边界**、§1.6 Review & Edit chain、状态初始化）
+3. `mstar-iteration` → **§ Phase 1**（迭代范围、compass 模板、**§1.5.5 产物边界**、§1.6 Review & Edit chain、状态初始化）
 4. `mstar-dispatch-gates`
 5. `mstar-phase-gates` → Prepare（specify → clarify → plan）
 6. `mstar-plan-conventions`, `mstar-plan-artifacts`
-7. `mstar-host` → active host reference（invoke 能力）
+7. `mstar-host` → active host reference（invoke 能力）；若 Cursor Plan mode → 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）
+
+**若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
+
+## P. Cursor Plan mode（Phase 1 scaffold → staged grill → Build）
+
+**Detect**：会话处于 Cursor Plan mode（系统要求 CreatePlan / SwitchMode，或 Plan 工具可用且当前为 Plan 会话）。
+
+**语义**：Plan 模式期间 **只维护 CreatePlan + SSOT 草稿**；**不**把 grill 段标成已执行 todo；**不**派发 Review 链；**不** commit；**不**建 integration 分支。点 **Build** 后才执行下方 Build todos（对齐 `mstar-host/references/cursor-plan-mode-bridge.md` · Phase 1 in Plan mode）。
+
+### P.1 Research（只读）
+
+执行与 §1 相同的调研（structured + unstructured + `STRATEGY.md`）。**不要**在本步写 compass/plans 终稿。
+
+### P.2 Early CreatePlan（空白脚手架 — 先于方向锁定）
+
+Research 后 **立刻** CreatePlan（**禁止**等 grill-me 全部完成再 CreatePlan）。
+
+**CreatePlan 最小结构**（session mirror；dual-write 草稿见 P.3）：
+
+```markdown
+# Phase 1: <iteration-id-or-TBD>
+
+## Direction
+TBD
+
+## Scope
+TBD
+
+## Acceptance Criteria
+TBD
+
+## Non-Goals
+TBD
+
+## Delivery Branch Policy
+| Field | Value |
+|-------|-------|
+| iteration_base_branch | TBD |
+| spec_integration_branch | TBD |
+| target_branch | TBD |
+
+## Plans
+| plan_id | Name | Status | Notes |
+|---------|------|--------|-------|
+| TBD | | Todo | |
+
+## Grill-me log
+（每段收敛后追加：日期 / 议题 / 决议）
+```
+
+**Build 才勾的 todos**（顺序；**不要**把 grill 段写成 Build todo）：
+
+1. `harness-init` — 若 `{HARNESS_DIR}` / `status.json` 缺失则初始化
+2. `finalize-compass-plans` — 将 CreatePlan 正文落成 compass + `{PLAN_DIR}/` plans + `status.json` 登记 + `{ITERATION_DIR}/README.md`
+3. `review-edit-product-manager` — §5.1 invoke
+4. `review-edit-architect` — §5.2 invoke
+5. `review-edit-writing-specialist` — §5.3 invoke
+6. `pm-lock` — §5.4 compass `status: locked` + Prepare gates
+7. `integration-branch` — §6
+
+### P.3 Dynamic grill-me（不固定段数）
+
+**Before this step:** Read `skills/grill-me/SKILL.md`（**仅本命令**引用；勿从 `mstar-*` 加载）。
+
+**Direction lock mode: `interactive`**。按决策树 **动态切段**（段数不固定；随用户需求增减）：
+
+- 一段一问；能靠读代码回答的先探索代码
+- 每段收敛后 **立刻** 更新 CreatePlan body（Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans 表）并 **追加** `## Grill-me log`
+- 同轮 dual-write SSOT **草稿**（可选但推荐）：`{ITERATION_DIR}/` compass stub、`{PLAN_DIR}/` plan stubs、`status.json` 业务 plan 行（方向收敛后至少有草稿登记）
+- **禁止**：固定死 4/5 段；把 grill 标成「已执行完的 todo」；Plan 模式内派发 §5 / commit / §6
+
+用户表示方向/范围已够用、可 Build 时 → 停止 grill；确认 CreatePlan 与草稿 SSOT 已反映锁定内容。
+
+### P.4 Build（执行 Phase 1 可执行门禁）
+
+用户点击 **Build**（或 Plan → Agent）后：
+
+1. 按 Build todos 顺序执行：`harness-init` → `finalize-compass-plans` → §5 Review 链（5.1→5.2→5.3）→ `pm-lock` → §6
+2. **禁止**把 Build 当成重新跑一遍 grill-me
+3. pre-commit checklist（见 §5）全 `[x]` 后再 commit / push integration 分支
+
+**非 Plan 路径从这里继续 ↓**
 
 ## 1. Research
 
@@ -57,6 +146,8 @@ Also read `STRATEGY.md`（if exists）for strategic alignment.
 
 ## 2. Explore Directions
 
+> **非 Plan 路径**。Cursor Plan mode 已在 §P 处理；勿与 §P 并行再跑一遍。
+
 Explore candidate directions targeting **product completeness**:
 
 - Default to completing deferred items from previous iterations
@@ -65,9 +156,11 @@ Explore candidate directions targeting **product completeness**:
 
 ## 3. Lock Direction — bundled `grill-me`
 
+> **非 Plan 路径**。Cursor Plan mode 用 §P.3 动态 grill-me（先 CreatePlan 再分阶段改文档）。
+
 **Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。
 
-This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step** references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
+This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step**（及 §P.3）references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
 
 **Before this step:** Read `skills/grill-me/SKILL.md`.
 
@@ -83,6 +176,8 @@ Run **grill-me** to stress-test candidate directions with the user:
 
 ## 4. Write Compass & Plans
 
+> **非 Plan 路径**。Plan mode 在 §P.2–P.3 维护草稿，Build 时由 `finalize-compass-plans` 落盘终稿。
+
 Produce harness artifacts per **`mstar-iteration` § 1.3**（template: `mstar-iteration/references/iteration-compass-template.md`）：
 
 - `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`

package/harness-skills/mstar-compound-refresh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mstar-compound-refresh
-description: Morning Star 知识维护 —— 审查 `{KNOWLEDGE_DIR}` 中文档是否仍准确、去重叠合并、清理过期知识。触发：`mstar-compound` 发现可合并文档、定期维护、或显式调用。产出：更新/合并/删除/标记为 stale 的文档 + 维护报告。
+description: Morning Star 知识维护与项目知识 bootstrap —— 审查 `{KNOWLEDGE_DIR}` 文档是否仍准确、去重叠合并、清理过期知识；或从代码库提炼 STRATEGY.md、CONCEPTS.md、基线 knowledge 脚手架（无/残旧/空白 knowledge）。触发：`mstar-compound` 发现可合并文档、定期维护、项目缺 STRATEGY.md/CONCEPTS.md/{KNOWLEDGE_DIR}、stale knowledge scaffolding、显式 bootstrap 请求、或显式 refresh。产出：更新/合并/删除知识文档 + 维护报告；或 bootstrap 产物（STRATEGY.md、CONCEPTS.md、基线 knowledge）。
 ---
 
 # mstar-compound-refresh（知识维护）
@@ -25,6 +25,16 @@ Knowledge documents in `{KNOWLEDGE_DIR}` age. Code changes, conventions evolve,
 | Scheduled maintenance | "It's been a quarter, let's audit knowledge" |
 | Domain refactored | After a major module rewrite |
 | Explicit user request | `/pm compound-refresh performance-issues` |
+| **Project knowledge bootstrap** | No/stale/partial `STRATEGY.md`, `CONCEPTS.md`, or `{KNOWLEDGE_DIR}` — see below |
+
+## Bootstrap vs refresh
+
+| Mode | When | Procedure |
+|------|------|-----------|
+| **Refresh** | `{KNOWLEDGE_DIR}` exists; audit accuracy, merge overlaps, delete stale docs | This skill § Process (Phases 1–6) |
+| **Bootstrap** | No knowledge scaffolding, or artifacts are absent/stale enough to warrant full distillation from codebase | **`references/project-knowledge-bootstrap.md`** (7-phase: survey → STRATEGY.md → CONCEPTS.md → baseline knowledge → indexing → harness init → commit) |
+
+Read the bootstrap reference on demand; do not paste its body into this SKILL.md.
 
 ## Maintenance outcomes
 

package/{harness-commands/mstar-bootstrap.md → harness-skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md}

@@ -1,23 +1,17 @@
----
-name: mstar-bootstrap
-description: Bootstrap or refresh a project's knowledge scaffolding — distill STRATEGY.md, CONCEPTS.md, and baseline knowledge docs from the existing codebase and any docs. Use when a project has no knowledge infrastructure, stale/partial docs, or needs a fresh distillation.
-agent: project-manager
----
-
 # Bootstrap Project Knowledge
 
 Distill a coherent knowledge baseline from the current project — useful when the project has no `STRATEGY.md` / `CONCEPTS.md` / `{KNOWLEDGE_DIR}`, has partial or outdated ones, or has accumulated documentation debt.
 
 **Goal**: produce a minimal, accurate, opinionated knowledge foundation that future iteration-start and plan-work can ground in.
 
-## Boot
+## Load order (bootstrap)
 
 1. `mstar-harness-core`
-2. `mstar-roles` → `references/project-manager.md`
+2. `mstar-compound-refresh` (this skill)
 3. `mstar-plan-conventions`（路径符号）
 4. `mstar-strategy` → **§ STRATEGY.md structure** + **§ Creating STRATEGY.md**
 5. `mstar-compound` → **references/concepts-vocabulary.md**（CONCEPTS.md 规则）
-6. `mstar-compound-refresh` → **§ Core rules**（知识维护基线）
+6. This reference — **§ Core rules** in `mstar-compound-refresh/SKILL.md`（知识维护基线）
 
 ## Phase 1: Survey — understand what exists
 

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

@@ -97,7 +97,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-review-qc` | PM：QC tri 编排、residual 留档、四层边界；leaf 执行 → `mstar-roles/references/qc-specialist/` |
 | `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Review Feedback / Goal-Driven / Communication |
 | `mstar-compound` | 知识结晶 —— 已解决问题→结构化知识文档，双轨（Bug/Knowledge），「是否值得结晶」自检清单，重叠检测，可发现性检查，CONCEPTS.md 协同 |
-| `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档 |
+| `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档；**项目知识 bootstrap**（无/残旧 STRATEGY.md、CONCEPTS.md、`{KNOWLEDGE_DIR}`）→ `references/project-knowledge-bootstrap.md` |
 | `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
 | `mstar-skill-authoring` | mstar-native skill authoring: trigger contracts, progressive disclosure, pressure scenarios, behavior-change evidence |
 | `mstar-roles` | 角色正文 hub |

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

@@ -11,7 +11,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an
 - Plugin source: `.codex-plugin/plugin.json`.
 - Runtime skills: repo `skills/` mounted by the Codex plugin (`"skills": "./skills/"`).
 - Custom agent source: repo `codex/agents/*.toml`; CLI/manual install links these into `~/.codex/agents/` or project `.codex/agents/`.
-- **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5.
+- **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5; project CLI install (`mstar-harness init --target codex --scope project`) materializes `iteration-start`, `iteration-drive`, and `iteration-loop` as `.agents/skills/<name>/SKILL.md` symlinks.
 - Role files under root `agents/` are for hosts that load OpenCode/Cursor-style agent shells; Codex uses `codex/agents/*.toml` and still loads `mstar-roles` references directly.
 - Tool and plugin availability can be lazy-loaded or session-dependent. Use the tools actually present in the current session; do not infer capability from documentation alone.
 

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

@@ -183,6 +183,23 @@ When `/pm` runs under Plan mode:
 - 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, **immediately** CreatePlan with blank Phase 1 scaffold (Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans / Grill log placeholders) + Build-bound todos | Wait until interactive direction lock finishes before CreatePlan |
+| Staged interactive lock | Dynamic number of clarify stages in the Plan session; after each stage, **update CreatePlan body** and dual-write SSOT **drafts** (`{ITERATION_DIR}` compass stub, `{PLAN_DIR}` plan stubs, `status.json` rows when direction converges) | Treat lock stages as completed Build todos; fix a hard-coded stage count; dispatch Review & Edit / commit / integration branch |
+| Pre-Build | Maintain documents only | Execute Review chain, commit, or create `spec_integration_branch` |
+| Build | Run Phase 1 executable todos: finalize SSOT → sequential Review & Edit (`product-manager` → `architect` → `writing-specialist`) → PM lock → integration branch | Replay interactive direction lock as if Plan session never happened |
+
+**Plan mode ≠ executing todos.** Build = Phase 1 executable gate (Review chain, lock, branch).
+
+**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`). Business `plans[]` rows should exist as drafts before Build when direction has converged.
+
+**Helpers**: third-party interview helpers are **not** named here; host **command** layer discovers them when needed.
+
 ## Anti-patterns
 
 | Anti-pattern | Fix |
@@ -194,6 +211,8 @@ When `/pm` runs under Plan mode:
 | Skip `spec-register` | Add `plans[]` row before implement |
 | Build starts coding in the parent session | Resume PM context; dispatch implement work or block on missing Assignment |
 | Follow-up only in chat / no roadmap section | Add `Roadmap / deferred scope` to CreatePlan and SSOT plan before implement |
+| Phase 1 Plan mode: grill/lock finishes before first CreatePlan | CreatePlan blank scaffold first; update body each lock stage |
+| Phase 1 Plan mode: Review / commit / branch before Build | Keep Pre-Build document-only; execute those todos after Build |
 
 ## Related skills
 

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

@@ -29,6 +29,8 @@ Before **SwitchMode → Agent**: mirror plan exists; `status.json` lists `plan_i
 
 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 blank scaffold **before** interactive direction lock; update CreatePlan + SSOT drafts each lock stage; **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

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

@@ -92,6 +92,8 @@ compass/plans 初稿落盘前，必须锁定**单一**迭代方向、成功标
 | **`interactive`** | **默认**（未显式声明 mode 时一律用此） | 与用户/产品**逐问**收敛方向与 branch policy；不得静默默认 `main`/`master` |
 | **`autonomous`** | **仅**当 caller / Assignment **显式**声明 `Direction lock mode: autonomous`（或等价书面 opt-in） | 代码优先调研 → 排序候选 → **锁定推荐方向并落盘 rationale**；不因「是否同意该方向」例行问用户。细则 → **`references/autonomous-direction-lock.md`** |
 
+**宿主 Plan UX（interactive）**：若宿主提供 Plan 会话（先写 session plan、后点 Build 才执行 todos），允许 **先 scaffold 空白 Phase 1 文档/todos，再分阶段收敛**方向与 branch policy，并在每段收敛后更新 scaffold；**非** Plan 会话仍按「收敛后再写 compass/plans 初稿」的默认顺序。此条 **不**改变 autonomous 路径，也 **不**要求非 Plan 宿主先写空文件。
+
 **禁止**：在未显式 opt-in 时自行切换到 `autonomous`（例如仅因读了本 skill 或存在 roadmap next）。
 
 **Branch policy gate（interactive — 默认路径）**：若用户、现有 roadmap、或项目约定未明确 `iteration_base_branch` / `target_branch`，PM 必须检查当前分支并向用户确认。**不得**因为存在 `main` / `master` 就默认从默认分支开 iteration 或向默认分支提 PR。

package/package.json

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