Reorganize workspace and archive skill artifacts

skill-workbench/generated-skills/skills/essence/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: essence
+description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
+metadata:
+  version: "0.5.0"
+---
+
+# Essence: Extract Core Design Patterns
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
+
+**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
+
+## Mode Selection
+
+First, check whether an `/explore` result exists:
+
+- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
+- No `/explore` result → this is an independent launch, default to **Auto-detect**.
+
+Always confirm before proceeding:
+
+| Mode | When | Entry |
+|---|---|---|
+| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
+| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
+| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
+
+### Lens definitions
+
+| Lens | Core question | Guided behavior |
+|---|---|---|
+| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
+| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
+| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
+
+A lens shapes which sources to read and how to frame the output, but does not add separate phases.
+
+### Auto-detect signals
+
+A design is "essence" if it passes 2 or more of these signals:
+
+| Signal | Evidence |
+|---|---|
+| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
+| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
+| Heavily discussed in Issues/PRs | Design decisions debated by community |
+| Unique among similar projects | Competitors don't do it this way |
+| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
+| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
+| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
+| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
+
+**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
+
+If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
+
+## Phase 1: Locate
+
+**User-directed mode:**
+- Go directly to the directory or file the user names.
+- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
+
+**Auto-detect mode:**
+- Scan README, CLAUDE.md, and top-level docs for architecture claims.
+- Identify 1-2 standout design directions.
+- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
+- If user doesn't choose, pick the strongest one and state why.
+
+**Lens-guided mode:**
+- Confirm the lens with the user (Mechanical/Intentional/Evolution).
+- Frame the search in terms of the lens.
+- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
+
+**Output:** 1-2 design directions to analyze + lens confirmation.
+
+**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
+
+## Phase 2: Deep Dive
+
+Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
+
+**For each file:**
+- What role does it play in this design?
+- What interfaces does it expose?
+- How does it connect to other parts of the system?
+
+**Trace the call chain:**
+- Start from the entry point that uses this design.
+- Follow the flow until you understand the full pattern.
+- Stop when you hit boilerplate, config, or test files.
+
+**Output:** Core file list (≤10) + call chain + lens-specific annotations.
+
+**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
+
+## Phase 3: Extract Pattern
+
+Analyze the design at a higher level. Let the lens shape the analysis angle:
+- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
+- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
+- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
+
+**Universal analysis dimensions** (all lenses):
+
+- **Problem:** What specific problem does this design solve? What was the pain before?
+- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
+- **Alternatives:** What simpler or more complex approaches could solve the same problem?
+- **Tradeoffs:** Why did the author choose this? What does it give up?
+- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
+
+**Output:** Design pattern card (lens-framed).
+
+**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
+
+## Phase 4: Migrate
+
+Make the learning actionable. Let the lens tailor the output:
+- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
+- **Intentional** → decision framework (checklist for evaluating tradeoffs)
+- **Evolution** → migration path (step-by-step refactor plan)
+
+**Universal deliverables** (all lenses):
+
+- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
+- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
+- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
+
+**Output:** Migration example + pitfall list (lens-tailored).
+
+**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
+
+## Phase 5: Self-review
+
+Check the report is honest:
+
+**All modes:**
+- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
+- [ ] The analysis is deep enough that you could explain it out loud.
+- [ ] The migration example captures the core idea, not surface syntax.
+- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
+
+**Stall signals (any one → return to relevant phase):**
+- Cannot name a file that proves the pattern → back to Phase 2
+- Cannot explain why it's better than alternatives → back to Phase 3
+- Migration example is over 20 lines → simplify, back to Phase 4
+- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
+
+**Output:** Essence report with lens annotation.
+
+## Optional: HTML Card
+
+**Only when the user explicitly requests it.**
+
+Generate an HTML visualization card as a shareable deliverable.
+
+### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>{Project Name} - Essence Report</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+  <style>
+    /* Same glassmorphism styles as /explore */
+    :root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
+    [data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
+    .glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
+    .pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
+  </style>
+</head>
+<body class="p-8">
+  <nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
+    <span class="font-bold text-xl">💎 {Project Name} 精华</span>
+    <span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
+  </nav>
+  
+  <main class="max-w-4xl mx-auto mt-24 space-y-6">
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
+      <p>{one-line description}</p>
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
+      <!-- Lens-framed pattern card -->
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
+      <pre class="mermaid">{diagram}</pre>
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
+      <pre class="pattern-diagram"><code>{code_example}</code></pre>
+      <p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
+    </section>
+  </main>
+  
+  <script>mermaid.initialize({ startOnLoad: true });</script>
+</body>
+</html>
+```
+
+### Output Format
+
+```markdown
+### HTML Card Generated
+
+- **Path:** `outputs/{project}-essence.html`
+- **Theme:** {modern/ink}
+- **Accent Color:** Purple (essence = jewel)
+```
+
+**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
+
+---
+
+## Hard Rules
+
+- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
+- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
+- **Stop after the report.** Do not modify the user's project or the target project.
+- **HTML is optional.** Do not block analysis on HTML generation.
+
+## Gotchas
+
+| What happened | Rule |
+|---|---|
+| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
+| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
+| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
+| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
+| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
+| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
+| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
+| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
+| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
+
+## Outcome
+
+```
+Essence Report: {project name}
+Lens: mechanical / intentional / evolution
+Design analyzed: {one-line description}
+Files examined: {count}
+Pattern: {pattern name or custom description}
+Migration: {steal-it example, ≤20 lines}
+HTML generated: yes / no
+Status: complete
+```
+
+After the report, stop. No modifications. No follow-ups.

skill-workbench/generated-skills/skills/essence/references/essence-signals.md

@@ -0,0 +1,79 @@
+# Essence Detection Signals
+
+How to identify the standout design in a project when the user doesn't specify a direction.
+
+## Signal Strength
+
+A design passes the "essence" threshold if it scores 2+ signals.
+
+### Strong Signals (score = 1 each)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
+| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
+| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
+| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
+| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
+
+### Objective Signals (score = 1 each, no subjective judgment needed)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
+| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
+| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
+
+### Weak Signals (score = 0.5 each)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
+| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
+| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
+| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
+
+## Not Signals
+
+These do NOT count as essence:
+
+- "Clean code" or "well organized" — that's quality, not design
+- "Uses TypeScript" — that's a language choice, not architecture
+- "Has good tests" — that's engineering discipline, not design
+- "Many stars on the repo" — popularity ≠ design quality
+- "Uses the latest framework" — following trends ≠ standing out
+- Utility functions — even well-written ones are tools, not designs
+
+## Auto-detect Procedure
+
+When the user says "find the essence":
+
+1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
+2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
+3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
+4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
+5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
+6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
+
+### Example Output Format
+
+```
+Standout designs in {project}:
+
+A) {Design A name} — evidenced by {README claim / file / doc}
+   What it does: {one sentence}
+
+B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
+   What it does: {one sentence}
+
+Which should we dive into? (or I can pick the strongest)
+```
+
+## Failure Modes
+
+| Situation | Response |
+|---|---|
+| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
+| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
+| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
+| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |

skill-workbench/generated-skills/skills/explore/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: explore
+description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching.
+metadata:
+  version: "0.5.0"
+---
+
+# Explore: Project Understanding and Onboarding
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start.
+
+`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching.
+
+## Project Type Detection
+
+After the initial scan, classify the target before continuing:
+
+| Type | Signals | What changes |
+|---|---|---|
+| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases |
+| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) |
+| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal |
+
+State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type.
+
+## Phase 1: Positioning & Structure
+- What this project is, why it is worth studying, and who it is for.
+- Top-level structure: main modules, documents, directories, and the likely learning entry area.
+- Tradeoffs vs alternatives when evidence exists.
+
+## Phase 2: Flow
+**Code repositories only.**
+- Skip for non-code and template repositories.
+- Trace the main runtime or request flow.
+- Produce at least one architecture or core-flow diagram.
+- Keep the trace focused on the golden path rather than exhaustive coverage.
+
+## Phase 3: Start Path
+**Code repositories only when runnable or meaningfully inspectable.**
+- Provide the minimal path to start learning or running the project.
+- Give the first command or first inspection step.
+- Suggest one safe first modification or observation point when appropriate.
+
+## Phase 4: Core Designs
+- Summarize 2-3 core implementations or ideas.
+- Keep this at overview depth.
+- For each item, include what it is, where it lives, and why it matters.
+
+## Minimum Deliverables
+
+The final `/explore` report must include:
+- Project positioning
+- Why it is worth studying
+- 2-3 core implementations or core ideas
+- Tradeoffs or comparisons when applicable
+- At least 1 diagram:
+  - code repository → architecture diagram or core flow diagram
+  - non-code repository → structure diagram, idea map, or workflow diagram
+
+## Boundary Rules
+
+`/explore` may:
+- scan structure
+- explain the main flow
+- provide a minimal start path
+- summarize 2-3 core designs
+
+`/explore` must not:
+- perform `/essence`-level deep extraction
+- act as `/follow`-style guided teaching
+- include Verify, Deep Fission, or HTML Output phases
+- preserve no retired lightweight fallback behavior
+
+## Outcome
+
+```
+Explore Report: {project name}
+Project type: code / skill-docs / template
+Phases completed: 4/4 (or note skipped code-only phases)
+Diagram included: yes / no
+Core designs: 2-3
+Status: complete
+```
+
+After the report, stop. Do not proceed to `/essence` or `/follow` automatically.

skill-workbench/generated-skills/skills/explore/references/analysis-methods.md

@@ -0,0 +1,98 @@
+# Project Analysis Methods
+
+How to read and understand an unfamiliar code project.
+
+## 1. Identify the Entry Point
+
+Every project has a door. Find it first.
+
+### By Language
+
+| Language | Look for |
+|---|---|
+| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
+| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
+| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
+| **Rust** | `src/main.rs` or `src/bin/*.rs` |
+| **Java** | Class with `public static void main(String[] args)` |
+| **C/C++** | `main()` function, conventionally in `src/main.c` |
+| **Swift** | `main.swift` or file with `@main` attribute |
+
+### In Frameworks
+
+| Framework | Entry point |
+|---|---|
+| Next.js | `app/` or `pages/` directory, `next.config.js` |
+| React (Vite) | `src/main.tsx` or `src/main.jsx` |
+| Vue (Vite) | `src/main.ts` or `src/main.js` |
+| Express | File that calls `app.listen()` |
+| FastAPI | File that creates `FastAPI()` instance |
+| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
+| Flask | `app.py` or `app/__init__.py` |
+| Spring Boot | `*Application.java` with `@SpringBootApplication` |
+
+## 2. Judge Project Complexity
+
+Don't over-engineer simple projects. Don't under-analyze complex ones.
+
+### Simple (<50 files, single language)
+- Read every source file.
+- No need for flow diagrams beyond a simple sequence.
+- A light `/explore` pass is probably enough.
+
+### Standard (50-500 files, 1-2 languages)
+- Read entry point + core modules + 1-2 feature files.
+- Build 1-2 flow diagrams.
+- `/explore` is the right level.
+
+### Complex (>500 files, multi-language, monorepo)
+- Read entry point + architecture docs + one representative module.
+- Use `/essence` to find standout designs, or `/explore` for one package at a time.
+- Do NOT try to understand the whole project in one pass.
+
+## 3. Separate Core Code from Scaffolding
+
+Not all files are worth reading.
+
+### Ignore (scaffolding)
+- `*.config.js`, `*.config.ts` — configuration, not logic
+- `dist/`, `build/`, `out/` — generated output
+- `node_modules/`, `vendor/`, `.venv/` — dependencies
+- `*.lock`, `yarn.lock`, `go.sum` — lock files
+- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
+- `test/fixtures/`, `test/data/` — test data
+
+### Read (core)
+- Entry point file
+- Router/middleware/config handlers
+- Model/entity/schema definitions
+- Core algorithm or business logic files
+- Files referenced most in imports
+
+### Hint: Follow imports
+
+```
+entry file → import A → import B → core logic
+```
+
+Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
+
+## 4. Read Unfamiliar Framework Code
+
+You don't know every framework. That's fine.
+
+### Strategy
+
+1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
+
+2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
+
+3. **Identify the framework's conventions.** Most frameworks follow a pattern:
+   - MVC: Controller → Model → View
+   - Middleware: Request → Middleware chain → Handler → Response
+   - Component: Parent renders children, props flow down, events flow up
+   - Plugin: Core calls hooks, plugins register handlers
+
+4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
+
+5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.

skill-workbench/generated-skills/skills/explore/references/flow-patterns.md

@@ -0,0 +1,173 @@
+# Flow Pattern Library
+
+Common architecture patterns and how to identify them in code.
+
+## MVC / MVVM / MVX
+
+### What it is
+Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel).
+
+### File signatures
+| Pattern | Directories/Files |
+|---|---|
+| **MVC** | `controllers/`, `models/`, `views/` |
+| **MVVM** | `viewmodels/`, `views/`, `models/` |
+| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) |
+
+### Flow
+```
+Request → Controller → Model (data) → View (render) → Response
+```
+
+### Key question
+"Does the file handle data, display, or coordination?" If yes → MVC-family.
+
+---
+
+## Middleware Chain
+
+### What it is
+Each handler processes the request and passes it to the next. Like an assembly line.
+
+### File signatures
+| Framework | Indicator |
+|---|---|---|
+| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` |
+| **FastAPI** | `@app.middleware("http")`, `Depends()` |
+| **Next.js** | `middleware.ts` at root or in `app/` |
+| **Gin (Go)** | `router.Use(middleware1, middleware2)` |
+| **Koa** | `app.use(async (ctx, next) => { ... })` |
+
+### Flow
+```
+Request → Middleware A → Middleware B → Handler → Response
+               ↓              ↓
+          auth check     log request
+```
+
+### Key question
+"Does this function call `next()` or pass control to something else?" If yes → middleware.
+
+### Common middleware order
+```
+1. CORS / Security headers
+2. Logging / Request ID
+3. Authentication / Authorization
+4. Body parsing / Validation
+5. Rate limiting
+6. Route handler
+7. Error handler (catches everything above)
+```
+
+---
+
+## Plugin / Extension System
+
+### What it is
+Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins.
+
+### File signatures
+| Pattern | Indicator |
+|---|---|
+| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` |
+| **Interface-based** | Abstract class or interface that plugins implement |
+| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention |
+| **VSCode-style** | `contributes` in `package.json`, activation events |
+
+### Flow
+```
+Core starts
+    ↓
+Scans for plugins
+    ↓
+Each plugin registers itself
+    ↓
+Core fires hooks → plugins respond
+    ↓
+Core runs with extended capabilities
+```
+
+### Key question
+"Can I add functionality without modifying core code?" If yes → plugin architecture.
+
+---
+
+## Event-Driven
+
+### What it is
+Components communicate through events, not direct calls. Publishers emit, subscribers listen.
+
+### File signatures
+| Pattern | Indicator |
+|---|---|
+| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` |
+| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` |
+| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` |
+| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` |
+| **Signals (Python)** | `@signal.connect`, `signal.send()` |
+
+### Flow
+```
+Component A emits "user.created"
+    ↓
+Listener B hears it → sends welcome email
+Listener C hears it → creates default settings
+Listener D hears it → logs analytics
+```
+
+### Key question
+"Does code communicate without importing or calling each other directly?" If yes → event-driven.
+
+---
+
+## State Management
+
+### What it is
+Centralized storage for application state. Components read and update through defined interfaces.
+
+### File signatures
+| Pattern | Indicator |
+|---|---|
+| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` |
+| **Zustand** | `create((set) => ({ ... }))` |
+| **Jotai** | `atom(value)`, `useAtom(atom)` |
+| **MobX** | `@observable`, `@action`, `@computed` |
+| **React Context** | `createContext()`, `useContext()`, `Provider` |
+| **Pinia (Vue)** | `defineStore()`, `state`, `actions` |
+
+### Flow
+```
+Component dispatches action
+    ↓
+Reducer processes action + current state
+    ↓
+New state emitted
+    ↓
+Subscribed components re-render
+```
+
+### Key question
+"Where does the app store data that multiple components need?" If it's a single store → state management pattern.
+
+---
+
+## Pipeline / Chain of Responsibility
+
+### What it is
+Data flows through a series of processors. Each processor transforms the data and passes it on.
+
+### File signatures
+| Pattern | Indicator |
+|---|---|
+| **Stream processing** | `.pipe(transform1).pipe(transform2)` |
+| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate |
+| **Data pipeline** | `input → transform → validate → output` |
+| **Makefile** | Target depends on prerequisites, each is a step |
+
+### Flow
+```
+Raw input → Tokenizer → Parser → Transformer → Generator → Output
+```
+
+### Key question
+"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline.

skill-workbench/generated-skills/skills/explore/scripts/collect-structure.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Collect project structure for /explore analysis.
+# Usage: Run from project root, or pass project path as argument.
+# Output: Structured text with directory tree, file counts, language distribution.
+
+set -euo pipefail
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR"
+
+echo "=== PROJECT STRUCTURE ==="
+echo ""
+
+# Directory tree (depth 3, exclude common noise)
+echo "--- Directory Tree (depth 3) ---"
+if command -v tree &>/dev/null; then
+    tree -L 3 \
+        -I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \
+        --dirsfirst
+elif command -v find &>/dev/null; then
+    find . -maxdepth 3 \
+        -not -path "./.git/*" \
+        -not -path "./node_modules/*" \
+        -not -path "./vendor/*" \
+        -not -path "./dist/*" \
+        -not -path "./build/*" \
+        -not -path "./out/*" \
+        -not -path "./.venv/*" \
+        -not -path "*/__pycache__/*" \
+        -not -path "*/.egg-info/*" \
+        -not -path "*/coverage/*" \
+        -not -path "./.nyc_output/*" \
+        -print | head -100 | sort
+fi
+
+echo ""
+echo "=== FILE COUNTS ==="
+echo ""
+
+# Count files by extension (top 10)
+echo "--- Top 10 File Types ---"
+find . -type f \
+    -not -path "./.git/*" \
+    -not -path "./node_modules/*" \
+    -not -path "./vendor/*" \
+    -not -path "./dist/*" \
+    -not -path "./build/*" \
+    -not -path "./out/*" \
+    -not -path "./.venv/*" \
+    -not -path "*/__pycache__/*" \
+    -printf '%f\n' | \
+    sed 's/.*\.//' | \
+    grep -v '^\.[^/]*$' | \
+    sort | uniq -c | sort -rn | head -10
+
+echo ""
+echo "=== TOTAL FILE COUNT ==="
+echo ""
+
+# Total files (excluding noise)
+total=$(find . -type f \
+    -not -path "./.git/*" \
+    -not -path "./node_modules/*" \
+    -not -path "./vendor/*" \
+    -not -path "./dist/*" \
+    -not -path "./build/*" \
+    -not -path "./out/*" \
+    -not -path "./.venv/*" \
+    | wc -l)
+echo "Total source files: $total"
+
+echo ""
+echo "=== DEPENDENCY FILES ==="
+echo ""
+
+# List dependency declaration files found
+for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do
+    if [ -f "$dep_file" ]; then
+        echo "FOUND: $dep_file"
+    fi
+done
+
+# Check for workspace/monorepo configs
+echo ""
+echo "=== WORKSPACE / MONOREPO ==="
+echo ""
+
+for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do
+    if [ -f "$ws_file" ]; then
+        echo "FOUND: $ws_file"
+    fi
+done
+
+# Check Cargo.toml for workspace
+if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then
+    echo "FOUND: Cargo.toml [workspace]"
+fi
+
+echo ""
+echo "=== ENTRY POINTS ==="
+echo ""
+
+# Try to identify entry points
+if [ -f "package.json" ]; then
+    main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "")
+    bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "")
+    dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "")
+    [ -n "$main" ] && echo "package.json main: $main"
+    [ -n "$bin" ] && echo "package.json bin: $bin"
+    [ -n "$dev" ] && echo "package.json dev/start: $dev"
+fi
+
+for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do
+    if [ -f "$entry" ]; then
+        echo "FOUND: $entry"
+    fi
+done
+
+echo ""
+echo "=== COLLECTED ==="

skill-workbench/generated-skills/skills/follow/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: follow
+description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction.
+metadata:
+  version: "0.5.0"
+---
+
+# Follow: Guided Learning Session
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it.
+
+`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result.
+
+## Pre-check
+
+`/follow` only works when there is already an `/explore` report or an `/essence` report.
+
+- `/explore` report exists → use it as the main learning path
+- `/essence` report exists → use it for design-focused guided study
+- Neither exists → refuse clearly
+
+Refusal behavior:
+"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first."
+
+Load the existing report before continuing.
+
+## Mode Selection
+
+After the pre-check, select one mode based on the prerequisite report:
+
+- From `/explore` + code repository → default **Runnable**
+- From `/explore` + non-code repository → force **Reader**
+- From `/essence` → default **Reader** (user is in design-analysis state)
+
+| Mode | When | Entry |
+|---|---|---|
+| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution |
+| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading |
+
+State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide.
+
+## Teaching Interaction Rules
+
+`/follow` must teach by guidance, not by dumping answers:
+- explain the purpose of the current step first
+- give the user an observation point or action point
+- ask the user to predict, try, or explain before revealing the answer
+- then reveal, correct, or deepen the explanation
+- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to
+
+## Runnable Check
+
+Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project):
+- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable.
+- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why.
+- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists.
+- Do not introduce a third mode.
+
+## Runnable Mode Flow
+1. Confirm environment and prerequisites.
+2. Let the user run the project.
+3. Let the user make one safe change.
+4. Walk the main flow together.
+5. Give one small exercise.
+6. Review what they learned.
+
+## Reader Mode Flow
+1. Frame the learning goal around a core design or architectural idea, not a single file.
+2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff.
+3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?").
+4. Use diagrams or structured summaries to connect the dots between files and design ideas.
+5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere.
+6. Review what they learned.
+
+## Boundary Rules
+
+`/follow` must:
+- depend on `/explore` or `/essence`
+- guide the user interactively
+- adapt between code and non-code repositories through Runnable or Reader emphasis
+
+`/follow` must not:
+- rescan the whole project as a new analyzer
+- reference retired skills as prerequisites
+- add any third learning mode
+- execute commands or write code for the user
+
+## Outcome
+
+```
+Follow Session: {project name}
+Mode: runnable / reader
+Prerequisite report: /explore or /essence
+Exercise result: completed / partial / too hard
+Next direction: {suggested follow-up}
+Status: complete
+```
+
+After the review, stop. Ask whether the user wants another exercise or wants to end the session.

skill-workbench/generated-skills/skills/follow/references/env-detect.md

@@ -0,0 +1,113 @@
+# Environment Detection Rules
+
+How to detect the runtime environment and guide the user through setup in `/follow`.
+
+## Language Detection from Config
+
+Check these files in order. The first match is the primary language.
+
+| Config file | Language | Runtime check | Install command |
+|---|---|---|---|
+| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer |
+| `pyproject.toml` | Python | `python --version` | pyenv or python.org |
+| `go.mod` | Go | `go version` | golang.org/dl |
+| `Cargo.toml` | Rust | `rustc --version` | rustup |
+| `pom.xml` | Java | `java -version` | SDKMAN or official |
+| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN |
+| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv |
+| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK |
+| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager |
+| `swift package.json` | Swift | `swift --version` | Xcode or swift.org |
+
+## Dependency Installation
+
+Once language is detected, guide the user:
+
+### JavaScript/TypeScript
+```bash
+# Check which package manager is used
+if [ -f "yarn.lock" ]; then yarn install
+elif [ -f "pnpm-lock.yaml" ]; then pnpm install
+elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install
+else npm install
+fi
+```
+
+### Python
+```bash
+# Modern Python projects
+pip install -e .
+# Or with requirements
+pip install -r requirements.txt
+# Or with poetry
+poetry install
+# Or with uv
+uv pip install -r requirements.txt
+```
+
+### Go
+```bash
+go mod download
+```
+
+### Rust
+```bash
+cargo build
+```
+
+### Java (Maven)
+```bash
+mvn install
+```
+
+### Java (Gradle)
+```bash
+./gradlew build
+# or
+gradle build
+```
+
+## Run Command Detection
+
+How to start the project:
+
+| Source | Command |
+|---|---|
+| `package.json` → `scripts.dev` | `npm run dev` |
+| `package.json` → `scripts.start` | `npm start` |
+| `Makefile` → `dev` target | `make dev` |
+| `Makefile` → `run` target | `make run` |
+| `pyproject.toml` (Poetry) | `poetry run python main.py` |
+| `go.mod` → `package main` | `go run main.go` |
+| `Cargo.toml` → `[[bin]]` | `cargo run` |
+| `docker-compose.yml` exists | `docker-compose up` |
+| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` |
+
+## Common Environment Issues
+
+| Error | Cause | Fix |
+|---|---|---|
+| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) |
+| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` |
+| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo |
+| `ENOENT: no such file` | Wrong working directory | `cd` to project root first |
+| `port already in use` | Another process on same port | Kill the process or use different port |
+| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` |
+| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` |
+| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement |
+| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` |
+
+## Detection Script for /follow
+
+```bash
+# Quick environment check
+echo "=== Environment ==="
+node --version 2>/dev/null || echo "Node.js: not installed"
+python --version 2>/dev/null || echo "Python: not installed"
+go version 2>/dev/null || echo "Go: not installed"
+rustc --version 2>/dev/null || echo "Rust: not installed"
+java -version 2>/dev/null || echo "Java: not installed"
+echo "PWD: $(pwd)"
+```
+
+Run this at the start of `/follow` Step 1 to understand what's available.

skill-workbench/generated-skills/sm-flow/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: sm-flow
+description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
+---
+
+# SM Flow
+
+SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。
+
+## 角色定位
+
+你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。
+
+## 真理源分层
+
+- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
+- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
+- 代码是实现结果：只能在执行真理源足够明确后修改。
+- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+
+## 核心规则
+
+- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。
+- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
+- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
+- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
+- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
+- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
+- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
+- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
+- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
+- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
+- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
+- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
+- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
+
+## 首次加载
+
+执行前只读取当前任务需要的 reference 文件：
+
+- 需要逐阶段执行时，读取 `references/phase-contracts.md`。
+- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
+- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
+- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
+
+## 启动检查
+
+1. 判断启动模式：
+   - 完整模式：用户提供粗略想法或初始 PRD。
+   - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
+   - PRD 文件模式：用户提供已有 PRD 路径。
+   - 指定阶段模式：用户要求从某个 Phase 恢复。
+   - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
+2. 如果缺少 `devflow/`，初始化：
+   - `devflow/projects/`
+   - `devflow/glossary/CONTEXT.md`
+   - `devflow/compound/`
+   - `devflow/reference/`
+3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
+4. 检查 OpenSpec 和子 skill 是否可用：
+   - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
+   - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
+5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
+
+## 项目标识
+
+整个流程使用同一个 slug：
+
+- 优先使用 OpenSpec change name。
+- 如果还没有 change name，则从功能标题生成 kebab-case slug。
+- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
+- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
+
+## Devflow 产物分层
+
+devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
+
+**必须产物**：
+
+- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
+- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
+- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
+- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
+
+**按需产物**：
+
+- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
+- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
+- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
+- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
+- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
+- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
+
+**规模分档**：
+
+- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。
+- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。
+- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。
+
+## 阶段总览
+
+1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
+2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
+3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
+4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
+5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
+6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
+7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
+8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
+
+每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
+
+## 快速模式
+
+快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
+
+- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
+- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
+- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
+- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
+
+## 完成标准
+
+一次流程只有在满足以下条件时才算完成：
+
+- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
+- 实现或规划任务已经完成，且执行依据来自 OpenSpec。
+- 已运行验证，或明确记录未运行验证的原因。
+- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
+- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
+

skill-workbench/generated-skills/sm-flow/references/archive-rules.md

@@ -0,0 +1,106 @@
+# 归档规则
+
+Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
+
+## 目录规则
+
+项目档案路径：
+
+```text
+devflow/projects/YYYY-MM-DD-{slug}/
+```
+
+默认创建以下必要文件：
+
+- `brief.md`
+- `evidence.md`
+- `decisions.md`
+- `acceptance.md`
+
+按需创建以下扩展文件：
+
+- `prd.md`
+- `research.md`
+- `design.md`
+- `tasks.md`
+- `alignment.md`
+- `adr/*.md`
+
+不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。
+
+## 产物分档
+
+| 分档 | 适用场景 | 必须文件 | 扩展文件 |
+| --- | --- | --- | --- |
+| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` |
+| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound |
+| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` |
+
+## 提取映射
+
+| 来源 | 提取内容 | 写入位置 |
+| --- | --- | --- |
+| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
+| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
+| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
+| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
+| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
+| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
+| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
+| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
+| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+
+## 验收记录规则
+
+必须真实记录验证情况，并按类型分类：
+
+- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。
+- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。
+- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。
+- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。
+
+记录要求：
+
+- 如果验证通过，记录命令/步骤和覆盖范围。
+- 如果验证失败，记录失败摘要和是否阻塞验收。
+- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
+
+## ADR 规则
+
+同时满足以下条件时创建 ADR：
+
+1. 决策难以逆转。
+2. 缺少上下文会让未来维护者困惑。
+3. 决策来自真实权衡，而不是简单偏好。
+
+项目内 ADR 存放于：
+
+```text
+devflow/projects/YYYY-MM-DD-{slug}/adr/
+```
+
+跨项目可复用决策或经验存放于：
+
+```text
+devflow/compound/YYYY-MM-DD-decision-{slug}.md
+```
+
+## 归档确认
+
+OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
+
+- Phase 4 可以建议 archive，但必须先询问用户。
+- 在用户确认前，不要执行 archive。
+- 如果用户暂不归档，在 acceptance 中记录原因或状态。
+- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
+
+## 归档交接
+
+Phase 4 结束时告诉用户：
+
+- 创建或更新了哪些档案文件。
+- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
+- 还剩哪些风险或后续事项。
+- 明确询问：是否现在 archive OpenSpec change？
+
+

skill-workbench/generated-skills/sm-flow/references/fallbacks.md

@@ -0,0 +1,101 @@
+# Fallback 协议
+
+当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
+
+## OpenSpec 提案 fallback
+
+1. 创建或识别 `openspec/changes/{slug}/`。
+2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
+3. 写入 `proposal.md`，包含：
+   - 问题
+   - 建议方案
+   - 范围
+   - 非目标
+   - 来自 devflow 的上下文约束
+   - 风险
+4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
+5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
+6. 只为外部可见行为或发生变化的需求编写 specs。
+7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
+
+## OpenSpec 修正 fallback
+
+当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
+
+1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
+2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
+3. 向用户汇报冲突和推荐修正。
+4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
+5. 再同步更新 devflow 文档；不要只改 devflow。
+
+## OpenSpec 执行 fallback
+
+仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
+
+1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
+2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
+3. 修改前先检查现有代码。
+4. 一次实现一个 OpenSpec task 的纵向切片。
+5. 用最窄但有效的命令验证每个切片。
+6. 只有验证通过或明确记录原因后，才更新 task 状态。
+7. 如果失败原因不确定，停止并进入 diagnose。
+8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
+
+## PRD fallback
+
+优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
+
+规则：
+
+- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
+- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
+- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
+
+## 文档化追问 fallback
+
+1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
+2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
+3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
+4. 对 user-interview 问题，一次只问一个并等待用户确认。
+5. 术语确认后立即更新词汇表。
+6. 影响实现的澄清必须回写 OpenSpec。
+7. 只为难以逆转的真实权衡创建 ADR。
+
+快速模式的最小问题：
+
+- 术语：这个概念应该使用哪个领域术语？证据是什么？
+- 边界：哪些内容明确不在范围内？是否需要用户确认？
+- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
+
+## 架构审计 fallback
+
+产出一份短架构审计：
+
+1. 画出输入 → 处理 → 输出。
+2. 列出相关模块和调用方。
+3. 识别耦合、数据所有权和生命周期风险。
+4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
+5. 用不超过五句话总结最大风险。
+6. 如果影响实现，回写 OpenSpec design/tasks。
+
+## Diagnose fallback
+
+1. 复现问题，或捕获准确失败信息。
+2. 最小化失败案例。
+3. 生成 3-5 个假设，并按可能性和验证成本排序。
+4. 修改代码前，先添加仪器化或定向检查。
+5. 判断根因属于实现问题还是 OpenSpec 规格问题。
+6. 如果是实现问题，修复被证明的最小原因。
+7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
+8. 运行回归验证。
+
+## TDD fallback
+
+使用纵向切片，不要水平批量写测试：
+
+1. 从 OpenSpec specs 中选择一个外部可见行为。
+2. 写一个失败测试。
+3. 实现刚好让测试通过的最小代码。
+4. 只在测试通过时重构。
+5. 对下一个 OpenSpec 行为重复以上步骤。
+

skill-workbench/generated-skills/sm-flow/references/phase-contracts.md

@@ -0,0 +1,199 @@
+# 阶段契约
+
+本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
+
+## Phase 0 — 入口澄清
+
+**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
+
+**动作**：
+- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。
+- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
+- 如果输入过于模糊，最多追加三轮聚焦问题。
+- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
+
+**退出条件**：
+- 问题可以用 1-2 句话说清楚。
+- 期望结果可以用 1-2 句话说清楚。
+- 已列出已知影响代码或模块；如果未知，也明确标记。
+- 可以生成 OpenSpec change slug。
+
+**输出**：
+- 入口摘要。
+- 初步 slug。
+- devflow 规模分档：`micro` / `standard` / `complex`。
+
+## Phase 0.5 — Devflow 上下文收集
+
+**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
+
+**动作**：
+- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
+- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
+- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
+- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
+- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。
+
+**退出条件**：
+- 已形成“OpenSpec 输入上下文摘要”。
+- 已列出相关 ADR 和不能违反的历史决策。
+- 已列出需要写入或修正 OpenSpec 的上下文点。
+
+**输出**：
+- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。
+
+## Phase 1 — OpenSpec propose
+
+**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
+
+**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+
+**动作**：
+- 优先调用 `openspec-propose`。
+- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。
+- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
+  - proposal 写清为什么做、做什么、范围和非目标。
+  - design 写入上下文约束、历史 ADR、关键技术决策。
+  - specs 写成可验收的外部行为。
+  - tasks 写成可执行的纵向切片。
+- 在承诺设计细节前，先检查相关仓库代码。
+
+**退出条件**：
+- `openspec/changes/<slug>/proposal.md` 存在。
+- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
+- 关键假设已显式记录在 OpenSpec 或 research 中。
+
+**输出**：
+- OpenSpec proposal、design、specs 和 task list。
+
+**Human checkpoint**：
+- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
+- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
+
+## Phase 1.5 — PRD / OpenSpec 对齐
+
+**进入条件**：Phase 1 已有 OpenSpec 产物。
+
+**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。
+
+**动作**：
+- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
+- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
+- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
+  - OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
+  - OpenSpec 是否使用 glossary 中的正确术语。
+  - OpenSpec 是否遵守相关 ADR。
+  - specs 是否能表达可观察行为。
+  - tasks 是否能驱动实现，而不是泛泛描述。
+- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
+
+**退出条件**：
+- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
+- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
+- 所有已知冲突已修正或等待用户决策。
+
+**输出**：
+- `brief.md`，以及按需创建的 `prd.md`。
+- OpenSpec 对齐检查记录。
+- 必要的 OpenSpec 修正。
+
+## Phase 2 — Human-in-the-loop 澄清
+
+**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
+
+**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
+
+**动作**：
+- 优先使用 `grill-with-docs`。
+- 先声明本阶段采用的澄清模式，并逐项标记：
+  - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
+  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
+- 至少覆盖三个维度：术语、边界、验收。
+- 一次只问一个 `user-interview` 问题。
+- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
+- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
+- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
+
+**退出条件**：
+- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
+- 所有 evidence-driven 结论已向用户汇报。
+- 所有 user-interview 决策已获得用户确认。
+- 影响实现的结论已回写 OpenSpec。
+
+**输出**：
+- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
+- 更新后的 OpenSpec。
+- 更新后的词汇表和 ADR。
+
+## Phase 2.5 — 架构审计
+
+**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
+
+**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
+
+**动作**：
+- 画出输入 → 处理 → 输出的模块链路。
+- 识别跨模块依赖、数据所有权、生命周期和耦合风险。
+- 检查是否与既有架构、ADR、OpenSpec design 冲突。
+- 用不超过五句话写出架构风险评估。
+- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
+
+**退出条件**：
+- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
+- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
+
+**输出**：
+- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
+- 必要的 OpenSpec design/tasks 修正。
+
+**Human checkpoint**：
+- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
+- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+
+## Phase 3 — OpenSpec apply
+
+**进入条件**：
+- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
+- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- devflow 与 OpenSpec 没有未解决冲突。
+
+**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
+
+**动作**：
+- 优先调用 `openspec-apply-change`。
+- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
+- 按 OpenSpec tasks 的纵向切片实现。
+- 当用户要求、行为复杂或回归风险高时使用 TDD。
+- 当测试失败、行为意外或原因不确定时使用 diagnose。
+- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
+- 修改文件前遵守仓库指令，例如 `AGENTS.md`。
+
+**退出条件**：
+- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 已运行验证，或记录了未验证原因。
+- 已列出已知限制。
+
+**输出**：
+- 代码变更、必要测试和实现说明。
+- 更新后的 OpenSpec task 状态。
+
+## Phase 4 — 回填 Devflow
+
+**进入条件**：实现或规划工作已经达到可交接状态。
+
+**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
+
+**动作**：
+- 遵循 `references/archive-rules.md`。
+- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
+- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
+- 如果本次流程产生可复用经验，写入 compound knowledge。
+- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
+
+**退出条件**：
+- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- 用户已被询问是否 archive OpenSpec change。
+
+**输出**：
+- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。
+

skill-workbench/generated-skills/sm-flow/references/templates.md

@@ -0,0 +1,290 @@
+# 模板
+
+这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。
+
+## Brief 模板
+
+```markdown
+# {标题} Brief
+
+## 背景
+
+- 用户目标：{goal}
+- 当前问题：{problem}
+- 关联 OpenSpec：`openspec/changes/{slug}/`
+- devflow 分档：micro | standard | complex
+
+## 范围
+
+- 本次要做：{in scope}
+- 本次不做：{out of scope}
+- 影响区域：{modules/files if known}
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖 / 待修正 / 不适用
+- specs 覆盖状态：已覆盖 / 待修正 / 不适用
+- tasks 覆盖状态：已覆盖 / 待修正 / 不适用
+```
+
+## Evidence 模板
+
+```markdown
+# {标题} Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 |
+
+## Evidence-driven 结论
+
+- 结论：{conclusion}
+  - 证据：{evidence}
+  - 风险：{risk if any}
+  - 用户确认：需要 / 不需要 / 已确认
+```
+
+## Decisions 模板
+
+```markdown
+# {标题} Decisions
+
+## User-interview
+
+| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| --- | --- | --- | --- |
+| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 |
+
+## 关键取舍
+
+- 决策：{decision}
+  - 原因：{why}
+  - 影响：{impact}
+  - 风险接受：{accepted by whom/when}
+```
+
+## PRD 模板
+
+```markdown
+# {标题} PRD
+
+## 问题陈述
+
+用用户视角描述问题。
+
+## 解决方案
+
+用用户视角描述预期解决方案。
+
+## 用户故事
+
+1. 作为{角色}，我希望{能力}，以便{收益}。
+
+## 实现决策
+
+- 决策：{decision}
+  - 原因：{why}
+  - 影响：{affected modules or behavior}
+
+## 测试决策
+
+- 好测试应该通过{public interface}验证{observable behavior}。
+- 必须覆盖：{critical paths}
+- 不测试：{explicit exclusions}
+
+## 非目标
+
+- {excluded behavior}
+
+## 补充说明
+
+- {open question or useful context}
+```
+
+## 词汇表模板
+
+```markdown
+# 上下文词汇表
+
+## 术语
+
+### {术语}
+
+- 定义：{precise definition}
+- 使用场景：{feature/module/context}
+- 备注：{ambiguities, synonyms, or rejected meanings}
+
+## 业务规则
+
+- {rule}: {meaning and source}
+```
+
+## ADR 模板
+
+```markdown
+# ADR-{编号}: {决策标题}
+
+**状态**：提议中 | 已接受 | 已废弃  
+**日期**：YYYY-MM-DD
+
+## 背景
+
+是什么情况迫使我们做这个决策？
+
+## 决策
+
+我们选择了什么？
+
+## 替代方案
+
+| 方案 | 拒绝原因 |
+| --- | --- |
+| {option} | {reason} |
+
+## 后果
+
+### 正面
+
+- {benefit}
+
+### 负面
+
+- {cost or risk}
+```
+
+## 技术调研模板
+
+```markdown
+# {标题} 技术调研
+
+## 摘要
+
+- 变更原因：{reason}
+- 变更范围：{scope}
+- 主要技术方案：{approach}
+
+## 源产物
+
+- OpenSpec change: `openspec/changes/{slug}/`
+- 关联 PRD: `prd.md` 或 `brief.md`
+
+## 关键发现
+
+- {finding}
+
+## 假设
+
+- {assumption and validation status}
+```
+
+## 设计模板
+
+```markdown
+# {标题} 设计
+
+## 架构摘要
+
+描述输入 → 处理 → 输出。
+
+## 关键决策
+
+- {decision}: {reason}
+
+## 模块地图
+
+| 模块 | 职责 | 备注 |
+| --- | --- | --- |
+| {module} | {responsibility} | {notes} |
+
+## 架构审计
+
+- 风险：{risk}
+- 缓解：{mitigation}
+```
+
+## 任务模板
+
+```markdown
+# {标题} 任务
+
+## 需求追踪
+
+| 需求 | 状态 | 备注 |
+| --- | --- | --- |
+| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} |
+
+## 实现任务
+
+- [ ] {task}
+```
+
+## 验收模板
+
+```markdown
+# {标题} 验收
+
+## 结果
+
+已接受 / 部分接受 / 未接受。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`{command or check}`
+- 结果：{passed/failed/not run}
+- 备注：{important output or reason not run}
+
+### 脚本验证
+
+- 命令：`{command}`
+- 结果：{passed/failed/not run}
+- 备注：{important output or reason not run}
+
+### 浏览器/人工验证
+
+- 步骤：{manual steps}
+- 结果：{passed/failed/not run}
+- 备注：{observations or reason not run}
+
+## 已完成范围
+
+- {completed behavior}
+
+## 已知限制
+
+- {limitation}
+
+## Bug 修复和诊断
+
+- {bug}: {diagnosis summary and regression coverage}
+
+## 交接
+
+- 下一步：{archive, deploy, review, or follow-up}
+- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
+```
+
+## 复合知识模板
+
+```markdown
+# {标题}
+
+**类型**：learning | trick | decision | explore  
+**日期**：YYYY-MM-DD
+
+## 背景
+
+这条经验来自哪里？
+
+## 经验
+
+未来代理应该复用什么经验？
+
+## 适用性
+
+什么时候适用？什么时候不适用？
+```
+