@mstar-harness/opencode 0.6.20 → 0.6.21

package/harness-skills/mstar-coding-behavior/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: mstar-coding-behavior
-description: Morning Star (启明星) 跨角色通用编码行为准则 —— Think Before Coding（先读懂再改、显式假设、不静默猜测）、Simplicity First（YAGNI 优先不写代码、The Ladder 决策层级、删除优于添加、简洁优于聪明、`simplify:` 标记天花板与升级路径、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不顺手重构、不 piggyback）、Goal-Driven Execution（非平凡逻辑必留一个可运行检查、模糊请求转可验证结果、Step → verify 微模板、分批留 roadmap）。任何实现、调试、重构、审查任务都应优先 Read 本 skill；`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 动手前必读；QC 审查员核对变更是否只做了该做的手术时必读。本 skill 不覆盖分支门禁、QC/QA 路由、Assignment 权限、Done 所有权等不变量（那些以 `mstar-harness-core` 为准）。
+description: Morning Star (启明星) 跨角色通用编码行为准则 —— Think Before Coding（先读懂再改、显式假设、不静默猜测、读 imports/test/项目模式）、Simplicity First（YAGNI 优先不写代码、The Ladder 决策层级含依赖评估、删除优于添加、简洁优于聪明、5 项具名反模式速查、`simplify:` 标记天花板与升级路径、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不顺手重构、不 piggyback）、Debugging（读完整报错与栈追踪、先复现、一步一测、根因分析、Bug 修复前先写复现测试、卡住时坦白）、Goal-Driven Execution（非平凡逻辑必留一个可运行检查、模糊请求转可验证结果、测行为不测实现、已有测试前后对比、不能测试说理由、Step → verify 微模板、分批留 roadmap）、Communication（说做了什么及为什么、标记顾虑、精确表达不确定性、不解释已知的、commit message 质量）。任何实现、调试、重构、审查任务都应优先 Read 本 skill；`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 动手前必读；QC 审查员核对变更是否只做了该做的手术时必读。本 skill 不覆盖分支门禁、QC/QA 路由、Assignment 权限、Done 所有权等不变量（那些以 `mstar-harness-core` 为准）。
 ---
 
 ## Load order（必读顺序）
 
-**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md）。** 本 skill 只约束 **编码与改动风格**（Think / Simplicity / Surgical / Goal-Driven）；**Done 所有权、状态机** 仍以 **`mstar-harness-core`** 为准；**分支 / worktree / QC-QA 检出字段** → **`mstar-branch-worktree`**；**调度防串扰** → **`mstar-dispatch-gates`**。冲突时 **以 `mstar-harness-core` 为准**。
+**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md）。** 本 skill 只约束 **编码与改动风格**（Think / Simplicity / Surgical / Debugging / Goal-Driven / Communication）；**Done 所有权、状态机** 仍以 **`mstar-harness-core`** 为准；**分支 / worktree / QC-QA 检出字段** → **`mstar-branch-worktree`**；**调度防串扰** → **`mstar-dispatch-gates`**。冲突时 **以 `mstar-harness-core` 为准**。
 
 **摘要**：`mstar-harness-core` — 不变量与门禁；本 skill — 实现与审查时的工程习惯，不替代 harness。
 
@@ -43,6 +43,16 @@ Quick check:
 
 **Never lazy about understanding.** Shorten the solution, never the reading. Read the task and every file the change touches fully first; trace the actual flow end to end. A small diff in the wrong place is not efficiency — it is a second bug shipped with confidence.
 
+**Read before you write.** Before generating code in an existing project:
+
+- Inspect the imports at the top of each file you are about to modify. They tell you which libraries the project actually uses — do not introduce a different library for the same purpose.
+- Look at nearby test files. They document expected behavior more precisely than comments or your own assumptions.
+- Follow existing project patterns. If there is a convention for API routes, file structure, or error handling, match it. Do not silently introduce a different pattern.
+- If you cannot find a precedent for something, say so. "I do not see a pattern for X in the codebase — should I follow approach Y?" is always better than guessing.
+- If you are not 100% sure a method signature or parameter exists, check the actual source code or docs before using it. Confidently calling a non-existent API is one of the costliest agent mistakes — it may compile, then fail at runtime.
+
+The failure mode: you generate "correct" code that is alien to the codebase it lives in. It works but looks like a different person wrote it. The human then has to either rewrite it to match or live with inconsistency forever.
+
 ## 2) Simplicity First
 
 Core idea: implement the smallest durable slice that satisfies the request and acceptance criteria.
@@ -55,7 +65,7 @@ Core idea: implement the smallest durable slice that satisfies the request and a
 2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write.
 3. **Stdlib / built-in covers it?** Use it.
 4. **Native platform feature covers it?** CSS over JS, DB constraint over app code, OS primitive over a library.
-5. **Already-installed dependency solves it?** Use it. Never add a new dependency for what a few lines can do.
+5. **Already-installed dependency solves it?** Use it. Never add a new dependency for what a few lines of code can do. When a new dependency appears necessary, evaluate: (a) can this be done with what is already in the project? (b) can the standard library do it? (c) is the package maintained (check last commit date and issue tracker) and reasonably sized? If you add it, state why in one sentence — silently adding packages is not acceptable.
 6. **Can it be one line?** One line.
 7. **Only then:** the minimum durable code that works.
 
@@ -79,6 +89,16 @@ This signals intent — the simplicity is deliberate, not an oversight — and g
 - Do not confuse "minimum" with "temporary." A small implementation must still align with the long-term target state, stable interfaces, and known follow-up plan.
 - If a workaround is unavoidable, label it as `simplify:` / `temporary`, explain why, and record the removal path in the plan/status artifact before claiming the task is complete.
 
+**Simplicity anti-patterns — stop and reconsider when you spot these:**
+
+| Anti-pattern | Signal |
+|---|---|
+| **Premature abstraction** | You are writing a class / interface / strategy pattern where a single function suffices. |
+| **Speculative error handling** | You are wrapping code in try/catch for errors that cannot happen. |
+| **Unnecessary configurability** | You are making a value configurable (env var, parameter) that will never change. Hardcode it until there is a real reason not to. |
+| **Dead flexibility** | You have an interface with one implementation, or a generic type with one instantiation — cost with zero benefit until a second use exists. |
+| **"In case we need to"** | Your justification for abstraction includes a guess about future requirements. "In case we need to" is not a requirement — it is a guess, and guesses about the future are usually wrong. |
+
 Default rule:
 
 - If 200 lines can be 50 with the same behavior, clarity, and durable architecture, prefer the smaller solution.
@@ -105,7 +125,19 @@ Traceability test:
 
 **Bug fix = root cause, not symptom.** A bug report names a symptom, not the cause. Before editing, grep every caller of the function or code path you are about to touch. The fix belongs where all callers route through — one guard in the shared function is smaller than a guard in every caller. Patching only the path the ticket names leaves every sibling caller still broken. Fix it once, at the narrowest shared point.
 
-## 4) Goal-Driven Execution
+## 4) Debugging
+
+Core idea: when something does not work, investigate. Do not guess.
+
+- **Read the error message entirely** — including the full stack trace. A `TypeError` can mean a hundred different things; the message and trace tell you which one.
+- **Reproduce before fixing.** If you cannot reproduce the problem, you cannot verify your fix. "I think this should fix it" is gambling, not debugging.
+- **Change one thing at a time.** Changing three things and seeing the bug disappear tells you nothing about which change fixed it — or what new bugs the other two introduced. Change one, test, change the next, test.
+- **Fix the root cause, not the symptom.** If a value is unexpectedly null, do not just add a null check and move on. Figure out why it is null. The null check might prevent a crash, but the underlying bug will manifest differently later. Before patching, grep every caller of the affected code path and fix at the narrowest shared point (see Surgical Changes · Bug fix = root cause).
+- **Write a reproduction test before fixing a bug.** Before changing any code, write a minimal test that reproduces the reported behavior. Run it — watch it fail. Then apply the fix. Run it — watch it pass. This is the only way to prove you fixed the actual problem and did not merely suppress symptoms.
+- **Run existing tests before and after your changes.** If tests passed before and fail after, you broke something. If tests were already failing before, say so — do not let your changes get blamed for pre-existing failures.
+- **If you are stuck, say so.** "I have tried X and Y and neither worked. Here is what I am seeing. I think the issue might be Z but I am not sure." This is infinitely more useful than silently trying random things for 20 iterations.
+
+## 5) Goal-Driven Execution
 
 Core idea: convert vague requests into verifiable outcomes and iterate until verified.
 
@@ -129,6 +161,21 @@ Micro template:
    Verify: [specific check]
 ```
 
+**Verification discipline:**
+
+- **Test behavior, not implementation.** A test that checks whether a constructor sets properties is worthless. A test that checks whether validation actually rejects bad input is valuable. Focus on the interesting cases.
+- **If you cannot write a test, say why.** "I cannot easily test this because the database calls are tightly coupled to the business logic" is useful information that may signal a need for restructuring. Do not skip testing without an explanation.
+
+## 6) Communication
+
+Core idea: how you communicate about code matters as much as the code itself.
+
+- **Say what you did and why.** Do not just dump a code block. "I moved the validation into a separate function because it was duplicated in three places and this makes it testable independently" — now the reviewer understands the change without reading every line.
+- **Flag concerns proactively.** If you implemented what was asked but see a problem, say so. "This works but it makes a database call per item — if the list grows large this will be slow. Want me to batch it?" saves hours later.
+- **Be precise about uncertainty.** "I am not sure if this library supports streaming responses" is useful. "I think this should work" is not. Tell the reviewer exactly what to verify.
+- **Match your explanation to context.** If they asked for a REST endpoint, do not explain what REST is. If they asked for a database index, do not explain what indexes do.
+- **Write specific commit messages.** "Fix bug" is useless. "Fix null pointer in user lookup when email contains uppercase chars" tells the next person exactly what happened.
+
 ## Integration Notes
 
 - This skill is additive to `verification-before-completion` (见 `mstar-superpowers-align`) and other Morning Star controls.

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

@@ -18,12 +18,14 @@ description: DESIGN.md design system specification for Morning Star projects. Cr
 
 | Topic | See |
 |-------|-----|
-| Normative spec: section definitions, token naming, light/dark rules | `references/design-md-spec.md` |
+| Normative spec: section definitions, token naming, light/dark rules, **YAML frontmatter structure** | `references/design-md-spec.md` |
 | Three-level completeness checklist (MVP / Standard / Production) | `references/completeness-checklist.md` |
 | Vercel Geist DESIGN.md as annotated reference | `references/vercel-example.md` |
-| Full template with Level 2/3 placeholders | `templates/DESIGN.md.template` |
+| Full template with YAML frontmatter and Level 2/3 placeholders | `templates/DESIGN.md.template` |
 | Dark theme template (same token names, different values) | `templates/DESIGN.dark.md.template` |
 
+**YAML frontmatter is the SSOT for token values.** Colors, typography, spacing, rounded, and components live in the frontmatter as structured, machine-readable data. The Markdown body is supplementary documentation (rules, intent, usage guidance). When reading DESIGN.md, always parse the YAML frontmatter first; when writing, keep frontmatter and body in sync.
+
 **Out of scope:** rendered UI artifacts (use Open Design MCP `user-open-design`); frontend implementation that consumes DESIGN.md tokens (use `@frontend-dev` / `@fullstack-dev`); QC review verdict rules (→ **`mstar-review-qc`**).
 
 ## Location
@@ -74,25 +76,26 @@ Full checklist → `references/completeness-checklist.md`.
 
 ### Workflow 1: Create DESIGN.md (Prepare phase)
 
-1. Read `references/design-md-spec.md` for section definitions
-2. Copy `templates/DESIGN.md.template` to `{PROJECT_ROOT}/DESIGN.md`
+1. Read `references/design-md-spec.md` for section definitions and YAML frontmatter structure
+2. Copy `templates/DESIGN.md.template` to `{PROJECT_ROOT}/DESIGN.md` — the template includes the full YAML frontmatter skeleton
 3. Interview `@product-manager` for brand colors, typography preferences, must-have patterns
-4. Fill Level 1 sections; leave Level 2/3 as-is (commented placeholders)
-5. If plan requires Level 2+ out of the gate, fill those sections too
-6. Run the completeness audit workflow below to confirm level
-7. Report to PM: path created, level achieved, what's needed for next level
+4. Fill Level 1 frontmatter tokens (uncomment and replace `"[placeholder]"` values with concrete hex/px values)
+5. If plan requires Level 2+ out of the gate, uncomment and fill those sections too
+6. Update the body prose to match the frontmatter values (target audience, aesthetic principles, rhythm rules)
+7. Run the completeness audit workflow below to confirm level
+8. Report to PM: path created, level achieved, what's needed for next level
 
 ### Workflow 2: Audit DESIGN.md completeness
 
-1. Read `DESIGN.md` and `DESIGN.dark.md` (if exists)
+1. Read `DESIGN.md` and `DESIGN.dark.md` (if exists) — **parse the YAML frontmatter** for structured token values
 2. Load `references/completeness-checklist.md`
-3. Check each checklist item; note gaps
+3. Check each checklist item; note gaps in both frontmatter (missing/uncommented keys, placeholder values) and body (missing rules/documentation)
 4. Report:
    - Current completeness level
-   - Gaps preventing next level
-   - Presence of upgrade placeholders (`LEVEL2_PLACEHOLDER`, `LEVEL3_PLACEHOLDER`)
+   - Gaps preventing next level (frontmatter gaps vs. body gaps, tagged separately)
+   - Presence of upgrade placeholders (`LEVEL2_PLACEHOLDER`, `LEVEL3_PLACEHOLDER` in both frontmatter comments and body HTML comments)
    - Recommendation: whether to upgrade now or defer
-5. Update DESIGN.md level tag (e.g., `<!-- COMPLETENESS_LEVEL: 1 -->`) if changed
+5. Update DESIGN.md level tag (e.g., `<!-- COMPLETENESS_LEVEL: 1 — last audited YYYY-MM-DD -->`) if changed
 
 ### Workflow 3: Add dark theme
 
@@ -106,9 +109,11 @@ Full checklist → `references/completeness-checklist.md`.
 
 Before writing styled UI code:
 1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
-2. Extract tokens into implementation layer (CSS custom properties, Tailwind config, theme object, etc.)
-3. Follow DESIGN.md Voice & Content rules for copy text
-4. If DESIGN.md is missing or incomplete, report to PM — do not guess tokens
+2. **Parse the YAML frontmatter** for token values — this is the SSOT for colors, typography, spacing, rounded, and components
+3. Resolve component `{colors.X}`, `{typography.X}`, `{rounded.X}` references by tracing back to the corresponding frontmatter keys
+4. Extract tokens into implementation layer (CSS custom properties, Tailwind config, theme object, etc.)
+5. Follow DESIGN.md body Voice & Content rules for copy text
+6. If DESIGN.md is missing, has no frontmatter, or is incomplete, report to PM — do not guess tokens
 
 ## Light/Dark dual-theme rules
 

package/harness-skills/mstar-design-md/references/completeness-checklist.md

@@ -5,10 +5,12 @@ Three-level progressive checklist for evaluating whether a `DESIGN.md` is suffic
 ## How to use
 
 1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
-2. Check each item in the target level (and all lower levels)
-3. An item is **complete** only when concrete values exist — placeholder comments do not count
-4. A `DESIGN.md` is at **Level N** when all items in Level N and below are complete
-5. Record the result in a comment at the top of DESIGN.md:
+2. **Parse the YAML frontmatter** for structured token values — the frontmatter is the SSOT for colors, typography, spacing, rounded, and components
+3. Review the Markdown body for documented rules, rhythm, and usage intent
+4. Check each item in the target level (and all lower levels)
+5. An item is **complete** only when concrete values exist in the frontmatter (uncommented keys with non-placeholder values) — YAML comments and `[LEVEL*]` placeholder values do not count
+6. A `DESIGN.md` is at **Level N** when all items in Level N and below are complete
+7. Record the result in a comment at the top of DESIGN.md:
 
 ```
 <!-- COMPLETENESS_LEVEL: N — last audited YYYY-MM-DD -->
@@ -20,15 +22,19 @@ The minimum bar for an agent to produce UI without hallucinating colors and typo
 
 ### Checklist
 
-- [ ] **Overview** — design system name and aesthetic principles stated
-- [ ] **Colors — Background** — at least one surface color (`background-100`)
-- [ ] **Colors — Text** — at least one text color (`gray-1000` or equivalent)
-- [ ] **Colors — Accent** — at least one accent color for links/actions (`blue*` or brand equivalent)
-- [ ] **Colors — Semantic** — at least one error color (`red*`) and warning color (`amber*`)
-- [ ] **Typography — Body** — at least one body text token with font family, size, weight, line height
-- [ ] **Typography — Heading** — at least one heading token
-- [ ] **Spacing** — base unit declared (4px or 8px) and at least 5 scale steps
-- [ ] **Breakpoints** — at least 2 responsive breakpoints defined
+- [ ] **Frontmatter exists** — YAML frontmatter block with `---` delimiters present and parseable
+- [ ] **Frontmatter `version`** — `version: 0.1.0` declared
+- [ ] **Frontmatter `name` and `description`** — design system name and description filled (non-placeholder)
+- [ ] **Overview** — design system name and aesthetic principles stated in body
+- [ ] **Colors — Background** — frontmatter has `colors.background-100` with a concrete hex value (not `"[LEVEL*]"` placeholder)
+- [ ] **Colors — Text** — frontmatter has `colors.gray-1000` and `colors.gray-900` with concrete hex values
+- [ ] **Colors — Accent** — frontmatter has `colors.blue-700` (or brand equivalent) with a concrete hex value
+- [ ] **Colors — Semantic** — frontmatter has `colors.red-700` (error) and `colors.amber-700` (warning) with concrete hex values
+- [ ] **Typography — Body** — frontmatter has at least one `typography.copy-*` token with all five properties filled
+- [ ] **Typography — Heading** — frontmatter has at least one `typography.heading-*` token with all five properties filled
+- [ ] **Spacing** — frontmatter has `spacing.base` declared and at least 5 numbered steps with pixel values
+- [ ] **Rounded** — frontmatter has `rounded.sm` with a concrete pixel value
+- [ ] **Breakpoints** — at least 2 responsive breakpoints documented in body
 
 ### What an agent CAN do at Level 1
 
@@ -48,7 +54,7 @@ The minimum bar for an agent to produce UI without hallucinating colors and typo
 
 ### Verdict
 
-- **All 9 items checked → Level 1 complete**
+- **All 13 items checked → Level 1 complete**
 - **Missing items → below Level 1 (insufficient for agent UI generation)**
 
 ## Level 2 — Standard (consistent components)
@@ -60,17 +66,18 @@ Prerequisite: Level 1 complete.
 ### Checklist
 
 - All Level 1 items complete
-- [ ] **Colors — Full background scale** — `background-100` through at least `background-300`
-- [ ] **Colors — Full gray solid scale** — `gray-100` through `gray-1000` (10 steps)
-- [ ] **Colors — Gray alpha scale** — at least `gray-alpha-100` through `gray-alpha-600`
-- [ ] **Colors — All accent scales** — `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink` with at least `700`/`800`/`900`/`1000` steps each
-- [ ] **Typography — Headings** — at least 3 heading levels (e.g., `heading-32`, `heading-24`, `heading-20`)
-- [ ] **Typography — Labels** — at least one label token
-- [ ] **Typography — Buttons** — at least one button typography token
-- [ ] **Spacing** — full 9-step scale (4, 8, 12, 16, 24, 32, 40, 64, 96px) and three-step rhythm documented
-- [ ] **Breakpoints** — at least 4 breakpoints
-- [ ] **Components — Button** — at least primary and secondary variants with size variants (default 40px, small 32px), plus hover/active/disabled/focus states
-- [ ] **Components — Input** — at least default variant with size variants, plus hover/active/disabled/focus/error states
+- [ ] **Colors — Full background scale** — frontmatter has `colors.background-100`, `background-200`, `background-300` active (uncommented, filled)
+- [ ] **Colors — Full gray solid scale** — frontmatter has `colors.gray-100` through `gray-1000` (10 steps) all active
+- [ ] **Colors — Gray alpha scale** — frontmatter has `colors.gray-alpha-100` through at least `gray-alpha-600` all active
+- [ ] **Colors — All accent scales** — frontmatter has `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink` scales, each with at least `700`/`800`/`900`/`1000` steps active
+- [ ] **Typography — Headings** — frontmatter has at least 3 heading levels active (e.g., `heading-32`, `heading-24`, `heading-20`)
+- [ ] **Typography — Labels** — frontmatter has at least one `label-*` token active
+- [ ] **Typography — Buttons** — frontmatter has at least one `button-*` token active
+- [ ] **Spacing** — frontmatter `spacing:` has full 9-step scale active; three-step rhythm documented in body
+- [ ] **Rounded** — frontmatter `rounded:` has `sm`, `md`, `lg`, `full` all active
+- [ ] **Breakpoints** — at least 4 breakpoints documented in body
+- [ ] **Components — Button** — frontmatter `components:` has `button-primary` and `button-secondary` with all properties filled, plus `button-small` size variant; body documents hover/active/disabled/focus states
+- [ ] **Components — Input** — frontmatter `components:` has `input` with all properties filled; body documents states
 
 ### What an agent CAN do at Level 2
 
@@ -105,15 +112,14 @@ Prerequisite: Level 2 complete.
 ### Checklist
 
 - All Level 1 and Level 2 items complete
-- [ ] **DESIGN.dark.md exists** — dark theme file with same token names, dark-appropriate values
-- [ ] **Dark theme covers all tokens** — every token in DESIGN.md has a corresponding entry in DESIGN.dark.md
-- [ ] **Elevation — Shadows** — at least 3 elevation levels (card, popover, modal) with explicit `box-shadow` values
-- [ ] **Motion — Easing** — easing curve declared
-- [ ] **Motion — Durations** — at least state change, popover, modal durations
-- [ ] **Motion — Reduced motion** — `prefers-reduced-motion` rule declared
-- [ ] **Shapes — Border radius** — at least 4 radius tokens (surface/input, menu/modal, fullscreen, pill)
-- [ ] **Components — Full library** — at least Card, Modal, Tooltip, Menu/Dropdown tokens
-- [ ] **Voice & Content** — writing rules documented: casing conventions, action naming, error format, toast format, empty state format
+- [ ] **DESIGN.dark.md exists** — dark theme file with `---` YAML frontmatter present, same key structure as DESIGN.md
+- [ ] **Dark theme frontmatter parity** — every token in DESIGN.md frontmatter (`colors`, `typography`, `spacing`, `rounded`, `components`) has a corresponding active entry in DESIGN.dark.md frontmatter with dark-appropriate values
+- [ ] **Elevation — Shadows** — at least 3 elevation levels (card, popover, modal) with explicit `box-shadow` values in body
+- [ ] **Motion — Easing** — easing curve declared in body
+- [ ] **Motion — Durations** — at least state change, popover, modal durations in body
+- [ ] **Motion — Reduced motion** — `prefers-reduced-motion` rule declared in body
+- [ ] **Components — Full library** — frontmatter `components:` has at least Card, Modal, Tooltip, Menu/Dropdown variants
+- [ ] **Voice & Content** — writing rules documented in body: casing conventions, action naming, error format, toast format, empty state format
 
 ### What an agent CAN do at Level 3