@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/brainstorming/spec-document-reviewer-prompt.md

@@ -0,0 +1,49 @@
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to docs/superpowers/specs/
+
+```
+Subagent (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for planning]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/skills/brainstorming/visual-companion.md

@@ -0,0 +1,298 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start AFTER the user approves the companion. --open auto-opens their browser on
+# the first screen; --project-dir persists mockups and enables same-port restart.
+scripts/start-server.sh --project-dir /path/to/project --open
+
+# Returns: {"type":"server-started","port":52341,
+#           "url":"http://localhost:52341/?key=ab12…",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
+
+**The URL contains a session key (`?key=…`).** The server rejects any request
+without it, so always give the user the **complete** URL from the `url` field —
+never strip the query string, and never hand out a bare `http://host:port`. The
+key gates HTTP and WebSocket access so a stray browser tab or another machine on
+the network can't read the screens or inject events. After the first load the
+browser remembers the key via a cookie, so reloads and `/files/*` assets work
+without repeating it.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code:**
+```bash
+# Default mode works — the script backgrounds the server itself.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Copilot CLI:**
+```bash
+# Use --foreground and start the server via the bash tool with mode: "async"
+# so the process survives across turns. Capture the returned shellId for
+# read_bash / stop_bash if you need to interact with it later.
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/skills/code-design-consistency-check/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: code-design-consistency-check
+description: 代码与设计一致性检查 | 触发条件：一致性检查、代码与设计一致性、跨文档对比、设计符合性 | 检查已开发代码与需求文档、技术设计文档的一致性，覆盖需求/API/数据模型/架构/安全/非功能/流程/前后端 8 大类，支持多轮迭代
+author: maohan
+source: project
+date_added: "2026-07-08"
+risk: low
+---
+
+# 代码与设计一致性检查
+
+本技能用于检查已开发代码与需求文档、技术设计文档的一致性，确保代码实现与设计意图相符。
+
+> ⚠️ **重要**：本技能强调**发散性思考**，不局限于下方列出的检查项。检查人员应根据实际项目和设计文档，自主识别更多一致性检查项。
+
+---
+
+## 使用方法
+
+1. 加载检查清单 `references/代码与设计一致性检查清单.md`（8 大类）
+2. 加载需求文档（任务 1 产出）
+3. 加载技术设计文档（任务 3 产出）
+4. 加载代码仓库（任务 5 产出）
+5. 按 8 大类逐项交叉对比
+6. 按模板 `references/代码与设计一致性检查报告模板.md` 输出报告
+7. **支持多轮迭代检查**（V1/V2/V3）
+
+---
+
+## 适用场景
+
+- 正式测试前的一致性检查
+- 版本发布前的回归检查
+- 跨团队交付前的对接检查
+- 代码重构后的一致性回归
+- 需求变更后的一致性检查
+
+## 不适用场景
+
+- 代码低级问题检查（使用 `code-low-level-check`）
+- 形式代码评审（使用 `development-code-review`）
+- 资深代码评审（使用 `development-expert-review`）
+
+---
+
+## 8 大类检查项
+
+> 以下仅作参考框架，**检查人员应发散性识别更多检查项**。
+
+| # | 类别 | 关键检查点 |
+|---|------|-----------|
+| 一 | 需求一致性 | 功能点、用户故事、业务约束、业务指标 |
+| 二 | API 一致性 | 端点、参数、响应、业务逻辑、设计规范 |
+| 三 | 数据模型一致性 | 表结构、字段、索引、约束、ER关系、数据字典 |
+| 四 | 架构一致性 | 模块划分、技术选型、部署架构、依赖管理 |
+| 五 | 安全一致性 | 认证、授权、数据安全、防护 |
+| 六 | 非功能一致性 | 性能、可靠性、可观测性、可维护性 |
+| 七 | 流程一致性 | 状态机、流程图、审批流 |
+| 八 | 前后端一致性 | 接口对接、数据结构、交互 |
+
+**合计 100+ 项一致性检查 + 20 项 Top 常见问题**
+
+---
+
+## 检查原则
+
+### 1. 跨文档对比
+
+- **需求 vs 代码**：实现是否覆盖需求
+- **设计 vs 代码**：实现是否符合设计
+- **前后端 vs 文档**：前后端是否一致
+- **错误码 vs 实现**：错误处理是否一致
+
+### 2. 双向核对
+
+- **正向**：设计文档要求 → 代码实现
+- **反向**：代码实现 → 设计文档要求
+- **多实现**：设计无要求但代码实现
+- **漏实现**：设计有要求但代码未实现
+
+### 3. 多轮迭代
+
+- **不能只检查一次**：每次代码修改都需要重新检查
+- **完整记录**：每次检查的问题和修复状态
+- **持续追踪**：跨轮次的持续未决问题
+
+---
+
+## 多轮迭代检查支持
+
+**场景**：代码与设计一致性检查发现问题后，开发人员修改代码；检查者再次检查，如此往复。
+
+**核心要求**：
+- 检查报告必须**完整记录每次检查的详细结果**
+- 每次检查的不一致项必须**追踪修复状态**
+- **不能只记录最后一次检查结果**，必须展示**完整迭代历史**
+- 最终结论必须基于**当前最新状态**
+
+### 迭代检查记录字段
+
+每次检查记录必须包含：
+
+| 字段 | 说明 |
+|------|------|
+| 检查轮次 | V1/V2/V3... |
+| 检查日期 | 检查发生日期 |
+| 代码版本 | 被检查的代码版本 |
+| 发现不一致数 | 本轮发现的不一致项总数 |
+| 已解决数 | 本轮前已解决的不一致项数（累计） |
+| 新增不一致数 | 本轮新发现的不一致项数 |
+| 待解决数 | 本轮结束时的待解决总数 |
+| 检查结论 | 通过/有保留通过/不通过 |
+
+### 修复状态追踪规则
+
+- **待修复**：本轮检查发现，尚未修复
+- **修复中**：开发人员正在修复
+- **已解决**：开发人员已修复完成（本轮或后续轮次需验证）
+- **未解决/遗留**：多轮检查后仍未解决，需升级处理
+
+### 历史问题追溯
+
+- **新增**：本轮第一次发现的不一致项
+- **回归**：之前已解决的项再次出现
+- **持续未决**：跨多轮检查仍未解决的项
+
+---
+
+## 输出格式
+
+根据模板 `references/代码与设计一致性检查报告模板.md` 生成检查报告，输出后保存到 `docs/代码与设计一致性检查报告-项目名-日期.md`
+
+---
+
+## 触发场景
+
+- "一致性检查"
+- "代码与设计一致性"
+- "跨文档对比"
+- "设计符合性"
+- "需求设计代码一致性"
+- "代码符合设计检查"