@mstar-harness/dsh 2.1.1

package/harness-skills/mstar-compound/references/schema.yaml

@@ -0,0 +1,122 @@
+# Knowledge documentation schema for {KNOWLEDGE_DIR}
+# Canonical frontmatter contract. Two tracks: bug and knowledge.
+
+tracks:
+  bug:
+    description: "Defects, failures, and errors that were diagnosed and fixed"
+    problem_types:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - config_error
+  knowledge:
+    description: "Practices, patterns, conventions, decisions, and workflow improvements"
+    problem_types:
+      - best_practice
+      - documentation_gap
+      - workflow_issue
+      - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+      - api_design
+      - testing_pattern
+
+required_fields:
+  module:
+    type: string
+    description: "Module, component, or area affected"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date documented (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - config_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+      - api_design
+      - testing_pattern
+    description: "Primary category — determines track (bug vs knowledge)"
+
+  category:
+    type: string
+    description: "Directory name under {KNOWLEDGE_DIR} (see category-mapping.md)"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+track_rules:
+  bug:
+    required:
+      symptoms:
+        type: array
+        description: "Observable symptoms (errors, broken behavior)"
+      root_cause:
+        type: string
+        description: "Fundamental technical cause"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+        description: "Type of fix applied"
+  knowledge:
+    optional:
+      applies_when:
+        type: array
+        description: "Conditions or situations where this guidance applies"
+
+optional_fields:
+  plan_id:
+    type: string
+    description: "Link to status.json plans[].id"
+  tags:
+    type: array
+    max_items: 8
+    description: "Search keywords, lowercase, hyphen-separated"
+  last_updated:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date of last substantive update (added when updating an existing doc)"
+  related_components:
+    type: array
+    description: "Other components involved"

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

@@ -0,0 +1,140 @@
+---
+name: mstar-compound-refresh
+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（知识维护）
+
+## Load order
+
+**Read `mstar-harness-core` first.** Path symbols → **`mstar-plan-conventions`**. On conflict, **`mstar-harness-core` wins**.
+
+## Purpose
+
+Knowledge documents in `{KNOWLEDGE_DIR}` age. Code changes, conventions evolve, patterns become obsolete. `mstar-compound-refresh` audits the knowledge store against the current codebase and makes it trustworthy again.
+
+## 产物与操作路径
+
+**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。本 skill 仅操作 `{HARNESS_DIR}/knowledge/**/*.md` + `{HARNESS_DIR}/knowledge/README.md` + `<repo-root>/CONCEPTS.md` + `{HARNESS_DIR}/status.json`（引用更新）。**禁止**操作 `docs/`、`{PLAN_DIR}/`、`{ITERATION_DIR}/`、`{SPECS_DIR}/`。
+
+> **Engine check (when available):** run `mstar compound validate <doc-path> --knowledge-dir <dir>` (or `import { scopeGuard, compoundRefreshScope } from "@mstar-harness/engine"` in a host hook) to resolve the allowed scope above (`{HARNESS_DIR}/knowledge/**`, `knowledge/README.md`, `<repo-root>/CONCEPTS.md`, `{HARNESS_DIR}/status.json`) and guard every write against it. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## When to use
+
+| Trigger | Example |
+|---------|---------|
+| `mstar-compound` detected overlapping docs | "Two docs cover N+1 queries — consider refresh" |
+| 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
+
+For each candidate document, classify into one of five outcomes:
+
+| Outcome | Meaning | Default action |
+|---------|---------|----------------|
+| **Keep** | Still accurate and useful | No edit; report reviewed |
+| **Update** | Core solution correct, references drifted | In-place edits (paths, module names, code snippets) |
+| **Consolidate** | Two+ docs overlap heavily, both correct | Merge unique content into canonical doc, delete subsumed |
+| **Replace** | Old doc is misleading; known better replacement exists | Create trustworthy successor, then delete old |
+| **Delete** | No longer useful, applicable, or distinct | Delete — git history preserves it |
+
+## Core rules
+
+1. **Evidence over opinion.** Signals are inputs, not a scorecard. Use engineering judgment.
+2. **Prefer no-write Keep.** Do not update a doc just to leave a review breadcrumb.
+3. **Match docs to reality.** When code differs from doc, update the doc — not ask whether the code change was "intentional."
+4. **Be decisive.** When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
+5. **Avoid low-value churn.** Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
+6. **Delete, don't archive** — **except** formal **iteration-start** §1.6 corpus hygiene (`mstar-iteration/references/iteration-corpus-hygiene.md`), which **moves** superseded/redundant knowledge/specs to `{HARNESS_DIR}/archived/knowledge|specs/`. Outside that gate, git history is the archive; `git log --diff-filter=D -- <path>` finds deleted docs.
+7. **Evaluate document-set design.** Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.
+
+## Scope selection
+
+### Default: user-guided
+
+1. Ask PM for scope: "All knowledge docs, a specific category, or a keyword?"
+2. If category: narrow to `{KNOWLEDGE_DIR}/<category>/`.
+3. If keyword: search frontmatter (`module:`, `tags:`, `problem_type:`) and filenames.
+
+### PM-directed: specific scope
+
+PM provides a scope hint (directory name, filename, module name, or keyword). Match in this order:
+1. Directory match under `{KNOWLEDGE_DIR}/`
+2. Frontmatter field match
+3. Filename match
+4. Content search
+
+## Process
+
+### Phase 1: Inventory
+
+1. List all `.md` files under `{KNOWLEDGE_DIR}/` (excluding `README.md` and index files).
+2. Read frontmatter of each candidate.
+3. Group by `category` / `module` for impact clustering.
+
+### Phase 2: Assess per doc
+
+For each doc, check:
+
+1. **Referenced code still exists?** — grep for file paths, class names, function names mentioned.
+2. **Referenced conventions still match?** — check against current `AGENTS.md`, `CONCEPTS.md`, lint configs.
+3. **Solution still the recommended approach?** — has a newer pattern superseded it?
+4. **Overlap with other docs?** — search for same module/tags to find duplicates.
+
+### Phase 3: Classify and act
+
+Classify each doc → Keep / Update / Consolidate / Replace / Delete. Apply changes.
+
+### Phase 4: Update indexes
+
+1. Update `{KNOWLEDGE_DIR}/README.md` index table — update Status column, add/remove rows.
+2. If doc was linked from `status.json` metadata, update references.
+
+### Phase 5: Report
+
+Produce a maintenance report:
+- Docs reviewed (count)
+- Docs kept (count)
+- Docs updated (list with what changed)
+- Docs consolidated (list with which canonical doc merged into)
+- Docs replaced (list with successor path)
+- Docs deleted (list with reason)
+- Docs flagged for PM review (ambiguous cases)
+
+### Phase 6: CONCEPTS.md reconciliation
+
+If `CONCEPTS.md` exists, reconcile it with the refreshed knowledge:
+- Terms mentioned in updated/replaced docs may need updating in CONCEPTS.md
+- Terms no longer referenced may be candidates for removal
+
+If `CONCEPTS.md` doesn't exist but knowledge docs contain qualifying domain terms, propose bootstrapping it (full repo-wide seed). Use `references/concepts-vocabulary.md` from `mstar-compound` for rules (read on demand — cross-skill path resolution via skill directory).
+
+## Cross-skill coordination
+
+`mstar-compound-refresh` reads vocabulary rules from `mstar-compound`'s references. At runtime, resolve the path from the loaded skill directory:
+
+```
+The CONCEPTS.md vocabulary rules are in the mstar-compound skill at:
+references/concepts-vocabulary.md
+Read that file from the mstar-compound skill directory before Phase 6.
+```
+
+## NOT to do
+
+- Do not delete docs without checking for inbound links
+- Do not "archive" — delete instead
+- Do not ask PM about mechanical updates (path fixes, renamed modules)
+- Do not change code to match outdated docs — update docs to match code
+- Do not run without PM approval for destructive actions (Delete, Replace)

package/harness-skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md

@@ -0,0 +1,164 @@
+# 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.
+
+## Load order (bootstrap)
+
+1. `mstar-harness-core`
+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. This reference — **§ Core rules** in `mstar-compound-refresh/SKILL.md`（知识维护基线）
+
+## 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-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-plan-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-plan-conventions`. On conflict, **`mstar-harness-core` wins**.
+
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-phase-gates` | Prepare 阶段判定 gate、何时 DESIGN.md 必须就绪 |
+| `mstar-plan-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
+
+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