@mstar-harness/omp 3.6.0-alpha.4

package/harness-skills/mstar-conventions/references/artifact-storage-paths.md

@@ -0,0 +1,53 @@
+# 产物存储路径（SSOT · 路径符号解析后）
+
+> **Authority**: `mstar-conventions` `references/artifact-storage-paths.md`.
+> Symbol definitions (`{HARNESS_DIR}`, `{KNOWLEDGE_DIR}`, `{PLAN_DIR}`, etc.) → `mstar-conventions` SKILL.md § 路径符号。
+> All `mstar-*` skills that produce or operate on files **must** follow this table; do not redefine paths locally.
+
+## Harness 子树内（`{HARNESS_DIR}/` 下）
+
+这些是 agent handoff 用的结构化产物。**Git 跟踪**遵循 `mstar-conventions` SKILL.md「Git 跟踪策略」：**进程本地、结果共享** — `plans/`、`iterations/`、`status.json`、`workflows/`、`projects/`、`sdd/` 等默认 gitignored；`AGENTS.md`、`knowledge/`、`specs/` 默认 tracked。
+
+| 产物 | 解析后路径（默认 `.mstar/`） | 读写的技能 |
+|------|---------------------------|-----------|
+| **知识文档** | `.mstar/knowledge/<category>/<slug>.md` | `mstar-compound`（写）、`mstar-compound-refresh`（读写） |
+| **知识索引** | `.mstar/knowledge/README.md` | `mstar-compound`（写）、`mstar-compound-refresh`（读写） |
+| **主 plan** | `.mstar/plans/<plan-id>-<name>.md`（gitignored；本地会话 SSOT） | PM / `mstar-artifacts` |
+| **Review bundle（QC/QA 原始过程报告）** | `{HARNESS_DIR}/sdd/<plan-id>/review/`（gitignored；默认 `.mstar/sdd/<plan-id>/review/`） | `mstar-sdd`、`mstar-review-qc`、`qa-engineer` |
+| **SDD scratch** | `{HARNESS_DIR}/sdd/<plan-id>/`（gitignored；含 per-task handoff 与 `review/` bundle） | `mstar-sdd` |
+| **status.json（v2 根）** | `.mstar/status.json`（gitignored；本地会话 SSOT；`{version: 2, updated_at, workflows[]}` 活跃 lifecycle 登记） | `mstar-artifacts`、`mstar-iteration` |
+| **workflow snapshot** | `{HARNESS_DIR}/workflows/<id>/snapshot.json`（gitignored；每 lifecycle 运行态：`plans[]` 行 + leases + branch anchors；`<id>` = plan id 或 iteration id） | `mstar-artifacts`、`mstar-iteration`、`mstar-branch-worktree` |
+| **workflow notes ledger** | `{HARNESS_DIR}/workflows/<id>/notes.jsonl`（gitignored；append-only 运行时笔记） | `mstar-artifacts`、`mstar-iteration` |
+| **project roadmap** | `.mstar/projects/<id>/roadmap.md`（gitignored；frontmatter `{project_id, title, status, created_at, milestones[]?, residuals_ref?}` + 正文约定） | `mstar-artifacts`、`mstar-iteration` |
+| **project register** | `.mstar/projects/<id>/residuals.json`（gitignored；open residual SSOT：`entries[<plan-id>]` 数组；项目缺失用 `_default`） | `mstar-artifacts`、`mstar-review-qc` |
+| **project references（研究语料）** | `.mstar/projects/<id>/references/`（gitignored；主题化 surveys / epic 备注 / 第三方 notes，与项目绑定；与 `{SPECS_DIR}` / `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` 不同） | `mstar-project-governance`、`mstar-artifacts` |
+| **迭代 package** | `.mstar/iterations/<iteration-id>/`（gitignored；`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
+| **迭代索引** | `.mstar/iterations/README.md`（gitignored；一行 = 一次迭代） | `mstar-iteration`（读写） |
+| **规格** | `{HARNESS_DIR}/specs/`（默认 tracked；解析见 `mstar-conventions`） | `mstar-artifacts` |
+| **harness AGENTS** | `.mstar/AGENTS.md`（tracked） | PM / init |
+| **archived knowledge** | `.mstar/archived/knowledge/`（保留原 `{KNOWLEDGE_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-artifacts` |
+| **archived specs** | `.mstar/archived/specs/`（保留原 `{SPECS_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-artifacts` |
+
+## 仓库根目录（`<repo-root>/`，与 `.git/` 同级）
+
+这些是人类和所有 agent 的共同入口，**不在** `{HARNESS_DIR}` 子树内。
+
+| 产物 | 解析后路径 | 读写的技能 |
+|------|----------|-----------|
+| **CONCEPTS.md** | `<repo-root>/CONCEPTS.md` | `mstar-compound`（写/协同）、`mstar-compound-refresh`（reconciliation/bootstrapping） |
+| **STRATEGY.md** | `<repo-root>/STRATEGY.md` | `mstar-strategy`（读写） |
+| **AGENTS.md 更新** | `<repo-root>/AGENTS.md`（或 `CLAUDE.md`） | `mstar-compound`（可发现性检查编辑）、`mstar-strategy`（索引编辑） |
+
+## 禁止操作区域
+
+以下目录**不属于** harness 知识/策略的产出目标，skills 不得在其中写入：
+
+| 路径 | 说明 |
+|------|------|
+| `docs/` | 人类文档（安装、贡献指南等），知识产物不放此处 |
+| `{ITERATION_DIR}/` | 迭代 package（compass + guides/specs）；知识文档不放此处 |
+| `{SPECS_DIR}/` | 仅限冻结规格/ADR，运行时知识不放此处 |
+
+## `<category>` 取值
+
+知识文档的 `<category>` 子目录由 `mstar-compound` 的 `references/category-mapping.md` 定义，在 `{KNOWLEDGE_DIR}` 下按需创建。示例：`runtime-errors/`、`conventions/`、`architecture-patterns/` 等。

package/harness-skills/mstar-conventions/references/effort-estimation.md

@@ -0,0 +1,38 @@
+# 工期与工作量预估（Agent 语境 · Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：写 Effort 字段前须已 Read **`mstar-harness-core`** skill（SKILL.md）以对齐「仅 agent-oriented、禁止人天/日历」的全局不变量；本 reference 为口径细则展开。
+
+在 OpenCode / Cursor 等多角色 agent 编排下，**所有「工期 / 工作量 / Effort」类预估只描述 agent 实施量级**：在规格与验收已就绪、上下文可加载的前提下，**agent 连续或少量会话内**完成实现与基础自证（跑通命令/单测等）需要多少**agent 工作量**。
+
+## 硬性规则（不得混入人工时间）
+
+凡使用本 harness 的计划、PRD、架构文档、Assignment、Status Update 中的 **Effort / 工期 / 预估** 表述：
+
+- **必须**只反映 **agent 执行与会话**（见下节尺码与会话带）。
+- **禁止**纳入任何**人类时间**，包括但不限于：人天 / person-days / FTE、人类日历天或周、等待人工评审、会议、排期空档、发布窗口、合规签批排队、跨团队人类响应时间。
+- **禁止**用「标了轴的人天」变相写人类时间；**本节字段内不要使用人天 / FTE / 人类日历**。
+- **QC/QA 在流程中的迭代**：视为 **agent 会话**的一部分（可多算几次会话），**不要**单独加「人类审查要等 X 天」。
+
+若业务方必须另做**人类排期或合同人天**，须在**与本 Effort 字段完全分离**的文档或章节（例如路线图、商务附件）中撰写，**不得**写进 `Effort (agent-oriented)` 或同名小节，以免与 agent 预估混读。
+
+## 推荐写法：T 恤尺码 + agent 会话带
+
+1. **XS**：单文件 / 单测点 / 配置微调 — 通常 **<1** 次完整 agent 回合可交付。  
+2. **S**：局部模块小改 — 约 **1** 次专注会话。  
+3. **M**：单功能横切少量文件 — 约 **1–3** 次会话（含流程内 QC/QA agent 迭代则取上沿）。  
+4. **L**：多模块、新子系统、或强依赖摸底 — 约 **3–8** 次会话；**应拆里程碑**。  
+5. **XL**：接近子系统级或未知域 — **先 spike / 原型**，未摸底前不给紧凑数字预估。
+
+「**会话**」指：一次连贯的 agent 运行（读上下文 → 实现 → 运行验证），**不是**人类 8 小时工作日。
+
+## 文档与模板中的字段名（建议）
+
+- **PRD / 产品文档**：**`## Effort (agent-oriented)`** — 仅 **Complexity (XS–XL) + agent session band + 假设**（规格已锁、契约稳定等）。  
+- **架构 / 技术计划**：**`### Implementation effort (agent-oriented)`** — 同上；区分 **spike** vs **build**。  
+- **PM Assignment `Constraints`**：**`Effort (agent-oriented)`**: `M, ~2–4 agent sessions — assumes plan locked and contracts stable`。  
+- **Status Update**：剩余工作仅用 agent 会话语言（如「约 1 次会话可收口」），**不写**人类日历或人天。
+
+## 与不确定性的关系
+
+- **规格未锁、接口未定、依赖外部凭证**：标 **`blocked` / `spike required`**，改为「先 1 次摸底会话再更新 Effort」，仍**只**用 agent 会话描述。  
+- **高危变更 / 生产发布**：人类审批或发布节奏**不计入**本节 Effort；若需记录依赖，用 **阻塞/依赖清单**（非时间预估字段）。

package/harness-skills/mstar-conventions/references/harness-bootstrap-and-agents-layering.md

@@ -0,0 +1,96 @@
+# Harness 初始化与 `AGENTS.md` 分层策略（Morning Star）
+
+> **Load order**：使用本参考初始化仓库前，须先 Read `mstar-harness-core` 与 `mstar-conventions`；冲突以 `mstar-harness-core` 为准。
+
+## 目标
+
+给新仓或迁移仓提供一套可复制的启动方式，确保：
+
+- `status.json` / residual / review bundle 有唯一落点；
+- 根规则与 harness 规则不互相覆盖；
+- 目录级 `AGENTS.md` 只承载增量边界，不变成重复手册。
+
+## Bootstrap 最小步骤
+
+1. 创建 `{HARNESS_DIR}`（推荐 `.mstar/`）与 `{PLAN_DIR}`（推荐 `.mstar/plans/`）。
+2. 初始化 `status.json`：从 **`mstar-artifacts/templates/status.empty.json`** 复制（**v2 形状**：`version: 2` + `workflows: []`）；residual canonical 见 **`mstar-artifacts` SKILL.md**；字段与生命周期见 **`mstar-artifacts/references/status-and-residuals.md`**。`projects/_default/`（`roadmap.md` + 空 `residuals.json`）由 **`scaffoldHarness` / `mstar harness scaffold` 预建**；其余 project id 与 `workflows/` 子目录由 engine writers 按需创建（**不**在 bootstrap 预建）。
+3. `sdd/` 空目录占位（per-plan 子目录由 **`mstar-sdd`** → `mstar sdd workspace <plan-id>` 创建）。
+4. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（canonical snippet → `mstar-conventions` SKILL.md「Git 跟踪策略」；legacy `.agents/` 有等价表）。
+5. 可选：创建 `{ITERATION_DIR}`（`iterations/` + `README.md`）与 `{KNOWLEDGE_DIR}`（`knowledge/` + `README.md`）；`{HARNESS_DIR}/specs/`（解析后的 `{SPECS_DIR}` 默认落点）；内容边界见 `mstar-conventions` SKILL.md 与 `references/knowledge-and-designs.md`。
+6. 创建 `{HARNESS_DIR}/AGENTS.md`（harness 子树规则；**tracked**）：符号表可复述 `{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 与 `docs/` 分工；新项目推荐 `.mstar/AGENTS.md`，已有项目可继续使用 `.agents/AGENTS.md`。
+7. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `{HARNESS_DIR}/AGENTS.md` 作为 harness SSOT。
+8. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
+
+**程序化路径**：`mstar harness scaffold [path]`（CLI，默认 cwd）一次性完成步骤 1–2（含 `projects/_default/`）、4 与 6 —— 调用 engine `scaffoldHarness`、追加 canonical gitignore snippet（已存在则跳过）、写最小 `{HARNESS_DIR}/AGENTS.md`（已存在则跳过）；幂等，重跑只补缺失件。步骤 3、5、7、8 仍按需手工。 scaffold 遵循 `.mstarc` 的 `harness_dir` / `project_dir` 覆盖（写入解析后的目录）；解析出的 harness 目录名非 `.mstar` 时跳过 canonical gitignore snippet（自定义 harness 布局自行管理 ignore 规则）。
+
+**gitignore 归一化契约**：scaffold 对默认布局的根 `.gitignore` 仅做四类收敛——分区（用户针对性 `.mstar/…` 规则整体移到 fence 之后、相对顺序不变）、去重冗余宽规则、错位主宽规则前移至首个 canonical negation 之前（仅当跨越行全部为 scaffold 自有语义）、补齐 canonical negation 使其出现在最后一条宽规则之后。保证：① tracked 结果（AGENTS/knowledge/specs）不因错序 fence 被忽略；② 用户针对性规则的字面意图最后生效（`!x` 即 track `x`）。自我否定的规则序列（先 `!x` 后被宽规则压制）按字面意图解析；每次变更均在 scaffold 输出中报告。
+
+## Git 跟踪策略（进程 vs 结果）
+
+**原则**：进程留在本地；结果与团队共享。完整规则与 canonical `.gitignore` snippet → **`mstar-conventions` SKILL.md「Git 跟踪策略」**。
+
+| 类别 | 默认 tracked | 默认 gitignored |
+|------|--------------|-----------------|
+| 结果（跨 clone handoff） | `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**` | — |
+| 进程（本地会话 SSOT） | — | `plans/`、`iterations/`、`status.json`、`workflows/`、`projects/`、`sdd/`、`archived/` |
+
+跨 clone 须持久的 residual 或决策：经 **`mstar-compound`** 提升入 `{KNOWLEDGE_DIR}/`、写入 `{SPECS_DIR}/`，或记入 tracked `{HARNESS_DIR}/AGENTS.md` — **勿**默认 `git add` `status.json` / `plans/`。
+
+## 三层 `AGENTS.md` 职责切分
+
+### 根 `AGENTS.md`（项目层）
+
+- 放：仓库身份、技术边界、构建/测试接口、安全与分支策略、规格路由表。
+- 不放：动态状态、当前批次进展、R# 明细、QC 单次结论。
+
+### `{HARNESS_DIR}/AGENTS.md`（harness 层）
+
+- 放：`{HARNESS_DIR}`/`{PLAN_DIR}`/`{ITERATION_DIR}`/`{KNOWLEDGE_DIR}`/`{SPECS_DIR}` 契约、`docs/` 与 harness 子树内容边界、状态推进门禁、QC/QA 对齐规则、residual 生命周期。
+- 不放：语言/框架编码细节、业务模块实现约束。
+
+### `<subdir>/AGENTS.md`（边界层）
+
+- 放：该目录独有的边界、禁区、接口命令与升级触发。
+- 不放：根级通用规则复写、harness 全量规则拷贝。
+
+## 分目录 `AGENTS.md` 创建准入
+
+仅当满足任一条件时创建：
+
+- 目录具备独立风险模型（如链上合约 vs 网关服务）；
+- 目录有单独发布面或对外 API 面；
+- 目录有稳定且长期存在的专属约束（构建、依赖、数据/安全边界）。
+
+若仅是代码组织而无新增约束，不创建目录级 `AGENTS.md`。
+
+## 推荐模板骨架（目录级）
+
+```markdown
+# AGENTS.md — `<dir>/`
+
+## Source Priority
+1. Current user instruction
+2. Root `AGENTS.md`
+3. This file
+4. `{HARNESS_DIR}/AGENTS.md`
+
+## Boundary Rules
+- ...
+
+## Build & Test (interface)
+- ...
+
+## Escalation Triggers
+- ...
+```
+
+## 反模式与修正
+
+- 反模式：在根 `AGENTS.md` 维护当前计划进展与 commit 列表。  
+  修正：迁移到 workflow snapshot 的 `plans[].metadata` 与 `workflows/<id>/notes.jsonl`。
+
+- 反模式：每个子目录复制一份完整 harness 规则。  
+  修正：保留一行引用 `{HARNESS_DIR}/AGENTS.md`，仅写本目录增量约束。
+
+- 反模式：目录级规则未声明 Source Priority，冲突时不可裁决。  
+  修正：统一四级优先级模板并在每个目录级文件开头声明。

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

@@ -0,0 +1,142 @@
+---
+name: mstar-design-md
+description: DESIGN.md design system specification for Morning Star projects. Create, audit, and maintain project-level design tokens (Colors, Typography, Spacing, Elevation, Motion, Shapes, Components, Voice & Content) using Vercel Geist as reference template. Three-level completeness checklist (MVP/Standard/Production) with built-in upgrade placeholders. Supports light/dark dual-theme via DESIGN.md + DESIGN.dark.md sharing same token names with different values. Prepare 阶段由 @architect 主责创建，@product-manager 提供设计需求；@frontend-dev / @fullstack-dev 实现 UI 时消费；@qc-specialist / @qa-engineer 审查 UI 对齐 DESIGN.md。Read when PM assigns DESIGN.md creation in Prepare, initiating a new UI project, @architect defining a design system, implementing styled components, auditing UI against design spec, adding dark theme, or user mentions "DESIGN.md" / "design tokens" / "design system". Phase gate → **mstar-phase-gates**; paths → **mstar-conventions**.
+---
+
+## Load order
+
+**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md).** For Prepare phase integration and gate rules, read `mstar-phase-gates`. For plan directory paths (`{HARNESS_DIR}`, `{SPECS_DIR}`), read `mstar-conventions`. On conflict, **`mstar-harness-core` wins**.
+
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-phase-gates` | Prepare 阶段判定 gate、何时 DESIGN.md 必须就绪 |
+| `mstar-conventions` | `{HARNESS_DIR}` / `{SPECS_DIR}` 路径解析 |
+| `mstar-roles` | `@architect` / `@product-manager` / `@frontend-dev` / `@qc-specialist` / `@qa-engineer` 角色职责边界 |
+| `mstar-coding-behavior` | 实现角色消费 DESIGN.md 前的通用编码约束 |
+
+## Scope (DESIGN.md lifecycle)
+
+| Topic | See |
+|-------|-----|
+| 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 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 preview tooling outside the repo; frontend implementation that consumes DESIGN.md tokens (use `@frontend-dev` / `@fullstack-dev`); QC review verdict rules (→ **`mstar-review-qc`**).
+
+## Location
+
+- **Primary**: project root `DESIGN.md` (human + agent visible, aligns with `AGENTS.md`)
+- **Dark theme**: project root `DESIGN.dark.md` (same token names, different values)
+- `DESIGN.md` is a **project-level design contract**, not a harness internal artifact. It lives beside `README.md` and `AGENTS.md`.
+
+## Role lifecycle
+
+### Creator: `@architect` (primary) + `@product-manager` (requirements)
+
+`@architect` owns DESIGN.md content — token selection, naming, completeness level decisions. `@product-manager` provides design intent: brand identity, target audience, must-have UI patterns, accessibility requirements.
+
+### Orchestrator: `@project-manager`
+
+In Prepare phase, PM decides whether the project needs a DESIGN.md. If yes, dispatches to `@architect` with product requirements from `@product-manager`. PM checks DESIGN.md exists and meets the assigned completeness level before `plan(locked)`.
+
+### Consumers
+
+- `@frontend-dev` / `@fullstack-dev` — read DESIGN.md before implementing styled components; map tokens to CSS/theme variables
+- `@qc-specialist` — verify UI implementation aligns with DESIGN.md tokens
+- `@qa-engineer` — verify visual output matches design spec when **`QA gate: mandatory`**
+
+## Phase gate integration
+
+DESIGN.md is a **Prepare-stage artifact** (like spec). It must be created and reviewed before `plan(locked)` for any plan that includes UI work.
+
+1. PM includes "DESIGN.md creation/audit" in Prepare tracking checklist when the plan involves UI
+2. `@architect` creates or updates DESIGN.md; `@product-manager` reviews design intent alignment
+3. PM gates on: DESIGN.md exists, meets completeness level declared in plan, `@product-manager` signed off
+
+For **hotfix** or plans with no UI changes, DESIGN.md check may be skipped.
+
+## Completeness levels（Evidence）
+
+DESIGN.md supports three levels, each with built-in upgrade path:
+
+1. **Level 1 — MVP** (minimal, prevents guesswork): palette, base typography, spacing scale
+2. **Level 2 — Standard** (consistent components): full token scales, breakpoints, component tokens (Button, Input)
+3. **Level 3 — Production** (complete design system): dual theme, elevation, motion, shapes, component library, voice
+
+The template includes all levels; Level 2 and 3 sections are commented out with `<!-- LEVEL2_PLACEHOLDER: ... -->` markers that explain when to activate them. The audit workflow detects these placeholders and can recommend upgrade.
+
+Full checklist → `references/completeness-checklist.md`.
+
+## Workflows
+
+### Workflow 1: Create DESIGN.md (Prepare phase)
+
+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 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) — **parse the YAML frontmatter** for structured token values
+2. Load `references/completeness-checklist.md`
+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 (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 — last audited YYYY-MM-DD -->`) if changed
+
+### Workflow 3: Add dark theme
+
+1. Read existing `DESIGN.md` to extract token names
+2. Copy `templates/DESIGN.dark.md.template` to `{PROJECT_ROOT}/DESIGN.dark.md`
+3. For each token in DESIGN.md, define the dark-theme equivalent value
+4. Preserve same token names; only values change (see `references/design-md-spec.md` § Light/Dark rules)
+5. Audit with Workflow 2 to confirm Level 3 completeness
+
+### Workflow 4: Consume DESIGN.md (implementation roles)
+
+Before writing styled UI code:
+1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
+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
+
+Dual theme uses **same token names, different values** across two files:
+
+```
+DESIGN.md         DESIGN.dark.md
+-----------       --------------
+gray-100: #fff    gray-100: #111
+gray-1000: #000   gray-1000: #eee
+```
+
+- Token names are the **SSOT interface** — consumers reference tokens by name, not raw values
+- `references/design-md-spec.md` § Light/Dark rules defines the contract
+
+> **Engine check (when available):** run `mstar design-md validate <dir>` (or `import { validateDesignTokenFrontmatter, assertLightDarkParity, completenessLevel } from "@mstar-harness/engine"` in a host hook) to validate the token frontmatter schema above, the light/dark parity of `DESIGN.dark.md` (same token names, different values), and the achieved completeness level. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## References
+
+- `references/design-md-spec.md` — normative spec: section definitions, token naming conventions, light/dark contract
+- `references/completeness-checklist.md` — three-level audit checklist with detailed criteria per level
+- `references/vercel-example.md` — Vercel Geist DESIGN.md as annotated reference (read when creating from scratch or needing design inspiration)
+
+**Templates (this skill):**
+- `templates/DESIGN.md.template` — full template including all Level 1-3 sections with placeholder comments
+- `templates/DESIGN.dark.md.template` — dark theme template with same token names, different values

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

@@ -0,0 +1,181 @@
+# DESIGN.md Completeness Checklist
+
+Three-level progressive checklist for evaluating whether a `DESIGN.md` is sufficient to drive agent UI generation. Each level builds on the previous level's requirements.
+
+## How to use
+
+1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
+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 -->
+```
+
+## Level 1 — MVP (prevents guesswork)
+
+The minimum bar for an agent to produce UI without hallucinating colors and typography. Sufficient for early-stage projects, prototypes, and CLI tools with minimal UI.
+
+### Checklist
+
+- [ ] **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
+
+- Style a basic page with correct brand colors
+- Choose readable typography
+- Apply consistent spacing
+- Make a responsive layout that works on mobile and desktop
+- Signal errors with the correct color
+
+### What an agent CANNOT do at Level 1
+
+- Build a consistent component library (no component tokens)
+- Apply elevation/shadow correctly (will guess)
+- Use motion responsibly (will guess)
+- Generate dark mode (no DESIGN.dark.md)
+- Apply voice rules to copy text
+
+### Verdict
+
+- **All 13 items checked → Level 1 complete**
+- **Missing items → below Level 1 (insufficient for agent UI generation)**
+
+## Level 2 — Standard (consistent components)
+
+Sufficient for building a consistent, polished UI with reusable components. The expected level for production codebases with a frontend.
+
+Prerequisite: Level 1 complete.
+
+### Checklist
+
+- All Level 1 items complete
+- [ ] **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
+
+- Everything from Level 1
+- Build a consistent Button component with all states
+- Build a consistent Input component with all states
+- Use the full color scale for nuanced visual hierarchy
+- Apply correct typography to every text role
+- Use translucent overlays and borders (alpha scale)
+- Pick the right accent color for each semantic purpose
+
+### What an agent CANNOT do at Level 2
+
+- Generate dark mode (no DESIGN.dark.md)
+- Apply elevation/shadows with confidence (may guess)
+- Use motion consistently (may guess)
+- Enforce voice rules on copy text
+- Know the correct border radius for each component type
+
+### Verdict
+
+- **All 11 items checked (on top of Level 1) → Level 2 complete**
+- **1–3 items missing → Level 2 partial; useable but expect component inconsistencies**
+- **4+ items missing → below Level 2; recommend completing Level 1 only deploy**
+
+## Level 3 — Production (complete design system)
+
+Full design system ready for production at scale. Includes dual theme, motion, and voice.
+
+Prerequisite: Level 2 complete.
+
+### Checklist
+
+- All Level 1 and Level 2 items complete
+- [ ] **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
+
+- Everything from Levels 1 and 2
+- Generate dark-mode-compatible UI
+- Apply elevation correctly for every UI layer
+- Animate state changes consistently
+- Apply correct border radius per element type
+- Write correct microcopy (button labels, errors, toasts, empty states)
+- Build a full component library (Card, Modal, Tooltip, Menu)
+
+### Verdict
+
+- **All 9 items checked → Level 3 complete (production-ready)**
+- **DESIGN.dark.md missing but rest complete → Level 2+ (partial Level 3, no dark mode)**
+
+## Audit workflow
+
+### When auditing existing DESIGN.md
+
+1. Load the DESIGN.md file
+2. Start at Level 1 checklist — check each item against actual content
+3. If Level 1 complete, proceed to Level 2
+4. If Level 2 complete, proceed to Level 3
+5. Record the level as `<!-- COMPLETENESS_LEVEL: N -->` at top of DESIGN.md
+6. For each incomplete item, note what's missing and which level it belongs to
+7. Check for `LEVEL2_PLACEHOLDER` / `LEVEL3_PLACEHOLDER` markers — if present and the project is ready for upgrade, recommend activation
+
+### When creating new DESIGN.md
+
+1. Decide target level with PM/architect:
+   - Prototype / early project → Level 1
+   - Production frontend → Level 2
+   - Full design system → Level 3
+2. Copy the template from `templates/DESIGN.md.template`
+3. Fill all items in the target level
+4. Run this checklist to confirm
+5. Leave higher-level placeholders as-is
+
+### When upgrading DESIGN.md
+
+1. Read current DESIGN.md and note the level tag
+2. Identify which items in the next level are missing
+3. For each missing item, either:
+   - Fill with concrete values if known
+   - Leave the `LEVEL*_PLACEHOLDER` marker if deferred
+4. Re-audit and update the level tag
+
+## Upgrade trigger conditions
+
+Agents encountering a DESIGN.md with placeholders should evaluate these conditions:
+
+| Condition | Action |
+|-----------|--------|
+| `LEVEL2_PLACEHOLDER` found AND plan includes component work | Recommend completing the Level 2 sections |
+| `LEVEL3_PLACEHOLDER` found AND plan includes dark mode | Recommend creating DESIGN.dark.md |
+| `LEVEL3_PLACEHOLDER` found AND plan targets production release | Recommend completing Level 3 |
+| `COMPLETENESS_LEVEL: 1` AND project has >3 UI views | Recommend upgrading to Level 2 |
+| `COMPLETENESS_LEVEL: 2` AND project has dark mode requirement | Recommend upgrading to Level 3 |