@mstar-harness/opencode 0.6.21 → 0.6.23

package/harness-commands/bootstrap.md

@@ -0,0 +1,171 @@
+---
+name: 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
+
+1. `mstar-harness-core`
+2. `mstar-roles` → `references/project-manager.md`
+3. `skills/pm/SKILL.md` → **§ Host entry** + **§ Boot**
+4. `mstar-plan-conventions`（路径符号）
+5. `mstar-strategy` → **§ STRATEGY.md structure** + **§ Creating STRATEGY.md**
+6. `mstar-compound` → **references/concepts-vocabulary.md**（CONCEPTS.md 规则）
+7. `mstar-compound-refresh` → **§ Core rules**（知识维护基线）
+
+## Phase 1: Survey — understand what exists
+
+### 1.1 Codebase scan
+
+- Read `README.md` (if exists) to understand project purpose
+- Read `AGENTS.md` / `CLAUDE.md` (if exists) for conventions and maintenance rules
+- Glob for `**/package.json`, `**/pyproject.toml`, `**/go.mod`, `**/Cargo.toml` to identify tech stack
+- Glob for `**/src/`, `**/lib/`, `**/app/` to identify module structure
+- Scan top-level directory layout
+
+### 1.2 Existing knowledge inventory
+
+Check what already exists and note its condition:
+
+| Artifact | Check | Condition |
+|----------|-------|-----------|
+| `STRATEGY.md` | Exists? Is it current/accurate? | `absent` / `stale` / `partial` / `current` |
+| `CONCEPTS.md` | Exists? Covers core domain nouns? | `absent` / `stale` / `partial` / `current` |
+| `{KNOWLEDGE_DIR}/README.md` | Exists? Index populated? | `absent` / `empty` / `partial` / `current` |
+| `{KNOWLEDGE_DIR}/**/*.md` | Any knowledge docs? Are they still accurate? | `none` / `few` / `some` / `many` |
+| `{ITERATION_DIR}/README.md` | Exists? Any past iteration artifacts? | `absent` / `present` |
+| `{SPECS_DIR}/` or `designs/` | Any specs or ADRs? | `absent` / `present` |
+| `docs/` | Any architecture docs, design notes? | Count and note relevance |
+| `{HARNESS_DIR}/status.json` | Exists? Any historical plans? | `absent` / `present` |
+
+Report findings to the user: what exists, what's missing, what's stale.
+
+### 1.3 Deep read — extract knowledge from code
+
+For each primary module / package identified in 1.1:
+
+1. Read the module's exported interface (public classes, functions, APIs)
+2. Read key configuration files (database schema, routes, middlewares)
+3. Identify recurring patterns: error handling style, dependency injection, ORM usage, auth flow
+4. Note any README or docstrings that describe domain concepts
+
+**Output**: a mental model of the project's domain, architecture patterns, conventions, and tech choices.
+
+## Phase 2: Distill STRATEGY.md
+
+Use `mstar-strategy` skill to produce `<repo-root>/STRATEGY.md`.
+
+### If STRATEGY.md is absent
+
+1. Gather context from Phase 1 survey
+2. Ask the user the 5 interview questions（`mstar-strategy` § Phase 2）
+3. Draft and review: keep each section 1-3 sentences
+
+### If STRATEGY.md exists but is stale/partial
+
+1. Present specific findings: "Section X contradicts current code / is outdated because Y changed"
+2. Ask whether to update in-place or rewrite
+3. Apply edits, keeping the Decision Log for historical context
+
+### If STRATEGY.md is current
+
+Skip, note in report.
+
+## Phase 3: Seed CONCEPTS.md
+
+Use `mstar-compound/references/concepts-vocabulary.md` rules to produce `<repo-root>/CONCEPTS.md`.
+
+### Identify core domain nouns
+
+From the codebase survey and STRATEGY.md, extract terms that meet the qualifying bar:
+- Its meaning in this project is precise enough that a new engineer would need it defined
+- It is not general programming vocabulary
+
+**Source areas** to scan:
+- Database schema (table/column names that encode domain concepts)
+- Core model/type definitions
+- API endpoint naming patterns
+- Entity relationship structure
+- README / architecture docs
+- STRATEGY.md domain terms
+
+### Write entries
+
+Each entry: one-sentence definition + optional paragraph for behavioral rules.
+- Cluster by domain relationship
+- Add `*Avoid:*` aliases for retired synonyms
+- No implementation specifics (file paths, class names)
+- Add `## Flagged ambiguities` tail section if needed
+
+### If CONCEPTS.md already exists
+
+Reconcile: keep valid entries, add newly discovered terms, update stale definitions. Do not duplicate.
+
+## Phase 4: Generate baseline knowledge docs
+
+From the Phase 1 survey, identify patterns and conventions worth documenting as knowledge docs in `{KNOWLEDGE_DIR}/`.
+
+### Minimum docs to produce (if absent)
+
+| Knowledge doc | Content source | Category |
+|---------------|---------------|----------|
+| **Architecture overview** | Module structure, tech stack, component interactions | `architecture-patterns/` |
+| **Development conventions** | Linting, testing, commit format, code style from AGENTS.md / configs | `conventions/` |
+| **Project setup** | Dependencies, environment setup, build/run commands | `developer-experience/` |
+| **Key domain patterns** | ORM patterns, auth flow, error handling, API design | `best-practices/` |
+
+Each doc follows the Knowledge track template (`mstar-compound/assets/resolution-template.md`).
+
+### What NOT to generate
+
+- Do not guess implementation details you haven't verified from code
+- Do not document general framework knowledge (e.g., "how to use React")
+- Do not create docs for areas the user explicitly excludes
+
+### If knowledge docs already exist
+
+Apply `mstar-compound-refresh` logic:
+- Keep accurate docs
+- Update stale references
+- Consolidate overlapping docs
+- Delete docs for code that no longer exists
+- Add new docs only for genuinely undocumented patterns
+
+## Phase 5: Indexing & discoverability
+
+1. Create or update `{KNOWLEDGE_DIR}/README.md` index table
+2. Create or update `{ITERATION_DIR}/README.md` index table (if iteration artifacts exist)
+3. Check AGENTS.md references all knowledge artifacts:
+   - If missing `{HARNESS_DIR}/knowledge/` → propose adding
+   - If missing `STRATEGY.md` → propose adding
+   - If missing `CONCEPTS.md` → propose adding
+4. Ask for consent before editing AGENTS.md
+
+## Phase 6: Initialize harness (if absent)
+
+If `{HARNESS_DIR}/` does not exist:
+1. Initialize per `mstar-plan-conventions`（`.mstar/` + subdirectories）
+2. Create empty `status.json` from template (`mstar-plan-artifacts/templates/status.empty.json`)
+
+## Phase 7: Commit
+
+All bootstrap artifacts must be committed:
+
+```bash
+git add STRATEGY.md CONCEPTS.md AGENTS.md {HARNESS_DIR}/ {KNOWLEDGE_DIR}/
+git commit -m "chore: bootstrap project knowledge — STRATEGY.md, CONCEPTS.md, baseline knowledge docs"
+```
+
+Report a summary:
+- STRATEGY.md: created / updated / skipped
+- CONCEPTS.md: created / updated（<N> entries）/ skipped
+- Knowledge docs: <N> created, <N> updated, <N> deleted, <N> kept
+- Harness: initialized / already existed
+- AGENTS.md: updated / not modified

package/harness-commands/iteration-drive.md

@@ -1,51 +1,63 @@
 ---
 name: iteration-drive
-description: Drive the active iteration to completion — run the PM Autonomous Execute loop (implement → QC → QA → Done) until all plans are Done, then optionally create PR to target branch (default main)
+description: Drive the active iteration to completion — run the Autonomous Execute loop (Phase 2 of mstar-iteration) until all plans are Done, then run iteration-close (Phase 3: compound + compass + roadmap update) on the integration branch, then create PR to target branch (default main)
 agent: project-manager
 ---
 
 # Drive Iteration
 
-Drive the active Morning Star iteration forward. Run the **Autonomous Execute driver** from `skills/pm/SKILL.md` (`§ Autonomous Execute driver`) to advance all non-`Done` plans to completion.
+Drive the active Morning Star iteration forward. The canonical flow is in **`mstar-iteration`** — this command loads it and executes its phases.
 
 ## Boot
 
 1. `mstar-harness-core`
 2. `mstar-roles` → `references/project-manager.md`
-3. `skills/pm/SKILL.md` → focus on **§ When to activate autonomous Execute** and **§ Autonomous Execute driver**
-4. `mstar-dispatch-gates` + host reference
-5. `mstar-plan-artifacts`, `mstar-plan-conventions`, `mstar-branch-worktree`
-
-## Precondition Gate
+3. `skills/pm/SKILL.md` → **§ Host entry** + **§ Boot**（PM role identity + dispatch-first rules）
+4. `mstar-iteration` → **§ Phase 2: Autonomous Execute**（per-plan dispatch loop）+ **§ Phase 3: iteration-close**（compound + compass）
+5. `mstar-dispatch-gates` + host reference
+6. `mstar-plan-artifacts`, `mstar-plan-conventions`, `mstar-branch-worktree`
+
+## Phase 2: Autonomous Execute
+
+Execute **`mstar-iteration` § Phase 2** exactly. Summary:
+
+1. **Precondition gate** (§ 2.0) — three checks before entering
+2. **Session todos** (§ 2.1) — set host todos per plan wave
+3. **Read backlog** (§ 2.2) — `status.json` + `spec_integration_branch`
+4. **Integration branch** (§ 2.3) — checkout/create
+5. **Per-plan loop** (§ 2.4) — for each non-`Done` plan:
+   - Create plan feature branch from integration
+   - Dispatch implement subagents (dispatch-first)
+   - Update `status.json` + main plan after each Completion Report v2
+   - QC tri-review + QA per `mstar-review-qc`
+   - Merge plan branch → integration branch
+   - Cross-plan progress sync → compass
+   - Next plan
+6. Repeat until **all** plans `Done` → exit loop, enter Phase 3
 
-Check the three conditions from **§ When to activate autonomous Execute**:
+**Dispatch-first constraint** (§ 2.5): PM never implements directly; `1 Assignment ⇒ 1 invoke`.
 
-1. `{HARNESS_DIR}/status.json` exists with at least one plan **not** `Done`
-2. **Pre-implement gate = GO** (`plan` locked, tasks ready)
-3. User intent is **continue Execute**
+## Phase 3: iteration-close
 
-If any is **false** → stop. If Prepare is incomplete → tell the user to run `/iteration-start` first.
+When every plan is `Done`, execute **`mstar-iteration` § Phase 3**:
 
-## Execute Loop
+1. **前置检查** (§ 3.1) — all plans Done, residuals closed, compass synced
+2. **Compound 轮** (§ 3.2) — 收集素材 → 自检清单（Q1-Q8）→ `mstar-compound` → CONCEPTS.md
+3. **更新 compass** (§ 3.3-3.4) — status → completed, roadmap, compound summary, retrospective, index
+4. **Commit** to integration branch:
 
-Follow **§ Autonomous Execute driver** from the PM skill exactly:
+```bash
+git add {ITERATION_DIR}/ {KNOWLEDGE_DIR}/ CONCEPTS.md
+git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
+git push origin <spec_integration_branch>
+```
 
-1. **Session todos** — set host todos for current `plan_id` + next gates
-2. **Read backlog** — `status.json`, active plans, `primary_spec` / `spec_integration_branch`
-3. **Checkout integration branch** — resolve or create from `status.json` metadata
-4. **Per-plan loop** — for each non-`Done` plan:
-   - Create plan feature branch from integration branch
-   - Dispatch implement subagents (dispatch-first, no parent agent implementation)
-   - Update `status.json` + main plan after each Completion Report
-   - QC tri-review + QA per `mstar-review-qc`
-   - Merge plan branch → integration branch
-   - Move to next plan
-5. Repeat until **all** plans in the iteration are `Done`
+## Completion: Create PR
 
-## Completion
+All iteration-close changes committed to integration branch:
 
-When every plan is `Done` in `status.json`:
+- Resolve PR target branch from `status.json` → `target_branch`（default `main`）
+- Create PR from `spec_integration_branch` to target
+- Report summary: plans completed, compound round（结晶文档数）, target branch, PR link
 
-- Resolve the PR target branch from iteration metadata: `status.json` → `target_branch`. Default to `main` if not set.
-- Create a PR from `spec_integration_branch` to the resolved `target_branch`
-- Report a summary: plans completed, branch names, target branch, PR link
+PR 合并后（babysit loop 或手动），本次迭代完整结束。

package/harness-commands/iteration-start.md

@@ -6,15 +6,16 @@ agent: project-manager
 
 # Start Iteration
 
-Start a new Morning Star harness iteration. Follow Prepare gates from `mstar-phase-gates` (specify → clarify → plan).
+Start a new Morning Star harness iteration. Detailed workflow → **`mstar-iteration` § Phase 1: iteration-start**；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
 
 ## 0. Boot
 
 1. `mstar-harness-core`
 2. `mstar-roles` → `references/project-manager.md`
-3. `skills/pm/SKILL.md` → **§ Host entry** (PM role identity) + **§ Boot** (load order)
-4. `mstar-phase-gates` → Prepare (specify → clarify → plan)
-5. `mstar-plan-conventions`, `mstar-plan-artifacts`
+3. `skills/pm/SKILL.md` → **§ Host entry** + **§ Boot**
+4. `mstar-iteration` → **§ Phase 1: iteration-start**（迭代范围、compass 模板、状态初始化）
+5. `mstar-phase-gates` → Prepare（specify → clarify → plan）
+6. `mstar-plan-conventions`, `mstar-plan-artifacts`
 
 ## 1. Research
 
@@ -35,6 +36,8 @@ Load harness entry, then survey structured and unstructured sources:
 
 Identify deferred or incomplete items from prior iterations as priority candidates for this iteration.
 
+Also read `STRATEGY.md`（if exists）for strategic alignment.
+
 ## 2. Explore Directions
 
 Explore candidate directions targeting **product completeness**:
@@ -53,11 +56,12 @@ Run the **grill-me skill** to stress-test candidate directions with the user:
 
 ## 4. Write Compass & Plans
 
-Produce harness artifacts:
+Produce harness artifacts per **`mstar-iteration` § 1.3 创建迭代 compass**（template: `mstar-iteration/references/iteration-compass-template.md`）：
 
-- `{ITERATION_DIR}/<iteration-id>-compass.md` — iteration vision, scope, roadmap batches, deferred items
+- `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — iteration scope, plans table, milestones, acceptance criteria, non-goals, roadmap position
 - `{PLAN_DIR}/<plan-id>-<name>.md` for each plan in this iteration
-- Register all plans in `{HARNESS_DIR}/status.json`
+- Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts`）
+- Update `{ITERATION_DIR}/README.md` index（per `mstar-iteration` § 1.4）
 
 ## 5. Review & Edit Chain
 

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

@@ -0,0 +1,251 @@
+---
+name: mstar-compound
+description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀为结构化知识文档，存入 `{KNOWLEDGE_DIR}`。支持 Bug track（症状/失败尝试/解决方案）与 Knowledge track（上下文/指南/适用场景）双轨。含重叠检测（更新已有文档）、可发现性检查（AGENTS.md 索引）、CONCEPTS.md 领域词汇协同。触发：迭代收口时（`mstar-iteration` § iteration-close）批量执行；也可独立触发。产出：`{KNOWLEDGE_DIR}/<category>/<slug>.md` + 可选 AGENTS.md 更新。
+---
+
+# mstar-compound（知识结晶）
+
+## Load order
+
+**Read `mstar-harness-core` first.** Path symbols (`{KNOWLEDGE_DIR}`, `{HARNESS_DIR}`) → **`mstar-plan-conventions`**. On conflict, **`mstar-harness-core` wins**.
+
+## Purpose
+
+After solving a non-trivial problem, `mstar-compound` captures the learning as a structured document in `{KNOWLEDGE_DIR}`, so future plan research, debugging, and implementation can find and reuse it.
+
+**In the mstar lifecycle**, compound is triggered at iteration-close (`mstar-iteration` § Phase 3), not per-plan Done. It can also be invoked standalone for ad-hoc captures outside formal iterations.
+
+Knowledge that isn't captured evaporates when the session ends. Knowledge that is captured but not discoverable is equally lost. This skill addresses both.
+
+## 产物存储位置
+
+**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。本 skill 不重定义路径；知识文档 → `{HARNESS_DIR}/knowledge/<category>/<slug>.md`，CONCEPTS.md → `<repo-root>/CONCEPTS.md`。`<category>` 取值见 `references/category-mapping.md`。
+
+## 是否值得结晶（自检清单 · 必须逐条回答）
+
+在调用本 skill 前，PM（或触发方）**必须**逐条回答以下问题。得分仅用于辅助决策，不替代判断。
+
+### 自检问题（每条回答 Yes / No / Not sure）
+
+| # | 问题 | 说明 |
+|---|------|------|
+| Q1 | 这个问题的诊断过程耗时是否 ≥ 15 分钟（或 ≥ 3 次尝试）？ | 若只是 1-2 次尝试就找到答案，可能太琐碎 |
+| Q2 | 解决方案是否涉及**非显而易见**的知识（隐含假设、框架行为、workaround）？ | 显而易见的知识无需文档化（如"少了个分号"） |
+| Q3 | 同一个开发者在未来遇到类似问题时，是否可能**再次花费相似的时间**来诊断？ | 核心问题：知识能否复用？ |
+| Q4 | 问题的**根因**是否是项目特定的（不是通用语言/框架问题）？ | 通用问题可搜索到，项目特定问题必须自己记录 |
+| Q5 | `{KNOWLEDGE_DIR}` 中是否**已有**与此高度重叠的文档？ | 若有 → 更新已有文档，不新建（见 Phase 2 重叠检测） |
+| Q6 | 此解决方案是否可能**引导未来架构决策**或成为约定？ | Knowledge track 的典型触发条件 |
+| Q7 | 此解决方案中的"**什么没起作用**"部分是否有价值？ | 失败的尝试往往是最有教学价值的部分 |
+| Q8 | 问题是否涉及** ≥ 2 个模块/组件**的交互？ | 跨模块问题最难排查，最值得记录 |
+
+### 决策矩阵
+
+| 得分 | 行动 |
+|------|------|
+| **Yes ≥ 4**（含 Q5=No） | **强烈建议结晶**。执行完整 Phase 1-7。 |
+| **Yes = 3** | **建议结晶**。使用 Lightweight 模式（Phase 1 单遍）。 |
+| **Yes ≤ 2** | **跳过**。在 conversation/Completion Report 中注明"跳过结晶（<简述原因>）"。 |
+| **Q5 = Yes（高重叠）** | 无论其它得分如何，**不要新建**。执行 Phase 2 重叠检测，更新已有文档即可。 |
+| **任一 Not sure** | 倾向于回答者的默认判断。若 Q1-Q4 有 ≥ 2 个 Yes，仍建议结晶。 |
+
+### 示例判定
+
+```
+Q1: Yes — debug 了 40 分钟
+Q2: Yes — ActiveRecord 的 counter_cache 在 after_destroy 回调中的时序问题
+Q3: Yes — 下次遇到类似时序问题仍会踩坑
+Q4: Yes — 是项目特有 model 结构导致的
+Q5: No  — grep 了 knowledge/ 无匹配
+Q6: No  — 纯 bug 修复
+Q7: Yes — 第一次尝试了手动更新 counter 导致数据不一致
+Q8: No  — 只涉及一个 model
+→ Yes = 5 → 强烈建议结晶（Bug track）
+```
+
+## Integration with mstar lifecycle
+
+Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），不在 per-plan Done 后单独执行：
+
+```
+iteration-start → [plan lifecycle × N: specify→...→Done] → iteration-close
+                                                                  │
+                                                             mstar-compound
+                                                             (per-iteration round)
+                                                                  │
+                                                             {KNOWLEDGE_DIR}
+                                                                  │
+                                               feeds back into next iteration's specify / plan
+```
+
+迭代内所有 plan Done 后，PM 回顾整轮迭代中产生的可结晶知识，批量 compound。per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动。
+
+## When to use (trigger)
+
+- **迭代收口时**（`mstar-iteration` § iteration-close）：PM 批量回顾所有 plan 的产物
+- **独立触发**（非迭代模式或紧急情况）：任何非平凡问题解决后，PM 或开发者手动触发
+- **Debug 后**：`mstar-iteration` 尚未启用时，重大 bug 修复后手动触发
+
+### Skip when
+
+- 自检清单判定 ≤ 2 个 Yes
+- Q5 高重叠（应更新已有文档而非新建）
+- 纯机械性工作：格式化、依赖升级、typo 修复
+- 问题仍在进行中或方案未经验证
+
+## Two tracks
+
+The skill classifies work into one of two tracks based on problem type:
+
+| Track | What it captures | Section structure |
+|-------|-----------------|-------------------|
+| **Bug** | Incident-level fix — "X broke, here's why and how we fixed it" | Problem, Symptoms, What Didn't Work, Solution, Why This Works, Prevention |
+| **Knowledge** | Durable guidance — "this is how we do X, and why" | Context, Guidance, Why This Matters, When to Apply, Examples |
+
+Track is determined by `problem_type`. See `references/category-mapping.md` for the full mapping.
+
+## Execution modes
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Full** (default) | Most cases | Dispatches research subagents for context analysis, solution extraction, and overlap detection |
+| **Lightweight** | Simple fixes, context-tight sessions | Single-pass documentation, no subagents, faster |
+
+In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
+
+## Phase 1: Gather context
+
+Read the conversation history to understand:
+- What problem was solved (the concrete issue)
+- What was tried and didn't work
+- What the working solution was
+- Why the solution works (root cause)
+- Which files/modules were involved
+- The plan_id if applicable (link to `status.json`)
+
+If `{KNOWLEDGE_DIR}/README.md` exists, scan its index for related existing documents.
+
+Classify the problem into a track (bug vs knowledge) and category using `references/category-mapping.md`.
+
+## Phase 2: Overlap detection
+
+Before creating a new doc, check if an existing doc covers the same ground:
+
+1. Extract keywords from the problem (module names, error messages, technical terms)
+2. Search `{KNOWLEDGE_DIR}/**/*.md` using frontmatter fields (`module:`, `tags:`, `problem_type:`)
+3. Score overlap across dimensions: problem statement, root cause, solution approach, referenced files, prevention
+
+| Overlap | Action |
+|---------|--------|
+| **High** (4-5 dimensions match) | **Update** the existing doc with fresher context instead of creating a new one. Add `last_updated` field. |
+| **Moderate** (2-3 dimensions match) | Create new doc; flag for consolidation review (potential `mstar-compound-refresh` trigger) |
+| **Low/None** | Create new doc normally |
+
+## Phase 3: Write the document
+
+### 3.1 Determine path
+
+Category → directory under `{KNOWLEDGE_DIR}/`. Examples:
+- Bug track: `build-errors/`, `runtime-errors/`, `performance-issues/`, `database-issues/`, `security-issues/`, `integration-issues/`
+- Knowledge track: `architecture-patterns/`, `design-patterns/`, `conventions/`, `workflow-patterns/`, `tooling-decisions/`, `best-practices/`
+
+Filename: `<sanitized-slug>.md` (lowercase, hyphen-separated, no date prefix).
+
+### 3.2 Frontmatter
+
+Required fields for both tracks (SSOT: `references/schema.yaml`):
+
+```yaml
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum value>
+category: <directory name>
+severity: critical|high|medium|low
+plan_id: <optional, link to status.json>
+tags: [<keywords>]
+---
+```
+
+Bug-track adds: `symptoms`, `root_cause`, `resolution_type`.
+Knowledge-track adds: `applies_when` (optional).
+
+### 3.3 Body
+
+Follow the section structure from `assets/resolution-template.md` for the determined track.
+
+### 3.4 Validate
+
+After writing, validate the YAML frontmatter:
+- `---` delimiters are correct
+- All required fields present
+- Enum values match allowed values
+- `date` is YYYY-MM-DD format
+- Array fields use `[item1, item2]` syntax
+
+## Phase 4: Discoverability check
+
+Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.
+
+If `{KNOWLEDGE_DIR}` is not mentioned in the root instruction file, propose the smallest addition that surfaces the knowledge store. Example:
+
+```markdown
+- `{HARNESS_DIR}/knowledge/` — captured solutions and reusable patterns
+```
+
+Ask for user consent before applying (PM can approve). If the user declines, the doc is still written — only the discoverability edit is skipped.
+
+## Phase 5: CONCEPTS.md synergy
+
+If the captured learning introduces or clarifies a domain term whose meaning is project-specific and not obvious to a newcomer, propose adding it to `CONCEPTS.md` at the repo root.
+
+Read `references/concepts-vocabulary.md` for inclusion rules. Only propose when the term meets the qualifying bar:
+- Its meaning in this project is precise enough that a new engineer would need it defined
+- It is not general programming vocabulary
+
+If `CONCEPTS.md` doesn't exist yet, ask whether to seed it. A seed populates the core domain nouns of the area the learning touches; a full repo-wide bootstrap is the job of `mstar-compound-refresh`.
+
+## Phase 6: Update indexes
+
+1. Add a row to `{KNOWLEDGE_DIR}/README.md` index table (create if missing):
+   - Document (link), Source Plan (`plan_id`), Description, Status (`Active`)
+
+2. If `plan_id` was provided, optionally update `status.json` metadata to reference this doc under `knowledge_refs`.
+
+## Phase 7: Refresh trigger
+
+After capturing, check if the new learning suggests an older doc may now be stale (contradicted, superseded, or in a refactored domain). If so, recommend:
+
+```
+Consider: /pm compound-refresh <scope hint>
+```
+
+Do not automatically run refresh — only flag when there's a concrete reason.
+
+## CONCEPTS.md bootstrap requests
+
+If invoked specifically to create CONCEPTS.md from scratch (not to document a solved problem), redirect to `mstar-compound-refresh` (which handles full repo-wide vocabulary bootstrapping). `mstar-compound` only seeds vocabulary as a side effect of capturing a real learning.
+
+## Support files
+
+Read on demand at the step that needs them:
+
+- `references/schema.yaml` — canonical frontmatter schema (Phase 3)
+- `references/category-mapping.md` — problem_type → directory + track mapping (Phase 1)
+- `references/concepts-vocabulary.md` — CONCEPTS.md rules (Phase 5)
+- `assets/resolution-template.md` — section structure per track (Phase 3)
+
+## Skill dependencies
+
+This skill integrates with:
+- **`mstar-plan-conventions`** — path symbols (`{KNOWLEDGE_DIR}`, `{HARNESS_DIR}`)
+- **`mstar-plan-artifacts`** — `status.json` linking, index maintenance
+- **`mstar-compound-refresh`** — for knowledge maintenance after capture
+
+## NOT to do
+
+- Do not create a doc for trivial fixes (typos, formatting, dep bumps)
+- Do not write the doc before the solution is verified
+- Do not skip the overlap check — creating duplicates degrades the knowledge store
+- Do not edit AGENTS.md without user consent
+- Do not create CONCEPTS.md entries for general programming vocabulary
+- Do not modify product code — this skill writes documentation only

package/harness-skills/mstar-compound/assets/resolution-template.md

@@ -0,0 +1,94 @@
+# Resolution templates for mstar-compound
+
+## Bug track template
+
+```markdown
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum>
+category: <directory>
+severity: <critical|high|medium|low>
+symptoms: ["<symptom 1>", "<symptom 2>"]
+root_cause: <fundamental cause>
+resolution_type: <enum>
+tags: [<keyword1>, <keyword2>]
+---
+
+# <Title>
+
+## Problem
+<1-2 sentence description of the issue>
+
+## Symptoms
+- <Observable symptom 1>
+- <Observable symptom 2>
+
+## What Didn't Work
+- <Failed approach 1>: <why it failed>
+- <Failed approach 2>: <why it failed>
+
+## Solution
+<The actual fix with code examples when applicable>
+
+```lang
+// Before
+<broken code>
+
+// After
+<fixed code>
+```
+
+## Why This Works
+<Root cause explanation and why the solution addresses it>
+
+## Prevention
+- <Strategy 1 to avoid recurrence>
+- <Strategy 2>
+- <Test case or lint rule if applicable>
+```
+
+## Knowledge track template
+
+```markdown
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum>
+category: <directory>
+severity: <critical|high|medium|low>
+applies_when: ["<condition 1>", "<condition 2>"]
+tags: [<keyword1>, <keyword2>]
+---
+
+# <Title>
+
+## Context
+<What situation, gap, or friction prompted this guidance>
+
+## Guidance
+<The practice, pattern, or recommendation>
+
+```lang
+// Example of the pattern
+<code>
+```
+
+## Why This Matters
+<Rationale and impact of following or not following this guidance>
+
+## When to Apply
+- <Condition or situation 1>
+- <Condition or situation 2>
+
+## Examples
+### Before
+```lang
+<code before>
+```
+
+### After
+```lang
+<code after>
+```
+```