universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/skills/{claude-code/commands → commands}/README.md

@@ -1,7 +1,17 @@
 # Claude Code Custom Commands
 
+> **Note**: Since Claude Code v2.1.3+, Skills and Commands are merged.
+> SKILL.md files now include all command metadata (`allowed-tools`, `argument-hint`).
+> This directory is maintained for backward compatibility with AI agents that
+> use separate command directories (OpenCode, Copilot, Roo Code, Gemini CLI).
+> For new commands, create a SKILL.md in `skills/<name>/` instead.
+
 Custom slash commands for Universal Development Standards.
 
+> **Workflow Guide**: For a comprehensive overview of how methodology commands work together, see **[Command Family Overview](./COMMAND-FAMILY-OVERVIEW.md)**.
+>
+> **工作流程指南**：關於方法論指令如何協同運作的完整說明，請參閱 **[指令家族總覽](./COMMAND-FAMILY-OVERVIEW.md)**。
+
 ## Available Commands | 可用命令
 
 ### Standards Management | 標準管理
@@ -26,15 +36,15 @@ Commands for development workflow automation.
 | [`/release`](./release.md) | Guide through release process | 引導發布流程 |
 | [`/changelog`](./changelog.md) | Update CHANGELOG.md | 更新 CHANGELOG |
 | [`/requirement`](./requirement.md) | Write user stories and requirements | 撰寫需求文件 |
-| [`/spec`](./spec.md) | Create specification documents | 建立規格文件 |
+| [`/sdd`](./sdd.md) | Create specification documents | 建立規格文件 |
 | [`/docs`](./docs.md) | Create/update documentation | 建立/更新文件 |
 | [`/coverage`](./coverage.md) | Analyze test coverage | 分析測試覆蓋率 |
-| [`/reverse-spec`](./reverse-spec.md) | Reverse engineer code to SDD spec | 反向工程成 SDD 規格 |
+| [`/reverse-sdd`](./reverse-sdd.md) | Reverse engineer code to SDD spec | 反向工程成 SDD 規格 |
 | [`/reverse-bdd`](./reverse-bdd.md) | Transform SDD AC to BDD scenarios | SDD AC 轉換為 BDD 場景 |
 | [`/reverse-tdd`](./reverse-tdd.md) | Analyze BDD-TDD coverage | BDD-TDD 覆蓋率分析 |
 | [`/derive-bdd`](./derive-bdd.md) | Derive BDD scenarios from approved spec | 從規格推演 BDD 場景 |
 | [`/derive-tdd`](./derive-tdd.md) | Derive TDD test skeletons from spec | 從規格推演 TDD 骨架 |
-| [`/derive-atdd`](./derive-atdd.md) | Derive ATDD acceptance tests from spec | 從規格推演 ATDD 測試 |
+| [`/derive-atdd`](./derive-atdd.md) | (Optional) Derive ATDD acceptance tests | （可選）推演 ATDD 測試 |
 | [`/derive-all`](./derive-all.md) | Derive all test structures from spec | 從規格推演完整測試結構 |
 
 ### Methodology | 方法論

package/bundled/skills/{claude-code/commands → commands}/atdd.md

@@ -1,5 +1,5 @@
 ---
-description: Guide through Acceptance Test-Driven Development workflow
+description: [UDS] Guide through Acceptance Test-Driven Development workflow
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
 argument-hint: "[user story or feature to define | 要定義的使用者故事或功能]"
 status: experimental
@@ -157,7 +157,7 @@ ATDD Level (Business Acceptance)
 
 ## Reference | 參考
 
-- Core Standard: [acceptance-test-driven-development.md](../../../../core/acceptance-test-driven-development.md)
+- Core Standard: [acceptance-test-driven-development.md](../../core/acceptance-test-driven-development.md)
 - Skill: [atdd-assistant](../atdd-assistant/SKILL.md)
-- Methodology: [atdd.methodology.yaml](../../../../methodologies/atdd.methodology.yaml)
+- Methodology: [atdd.methodology.yaml](../../methodologies/atdd.methodology.yaml)
 - Methodology System: [methodology-system](../methodology-system/SKILL.md)

package/bundled/skills/{claude-code/commands → commands}/bdd.md

@@ -1,5 +1,5 @@
 ---
-description: Guide through Behavior-Driven Development workflow
+description: [UDS] Guide through Behavior-Driven Development workflow
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
 argument-hint: "[behavior or scenario to implement | 要實作的行為或場景]"
 status: experimental
@@ -138,5 +138,5 @@ BDD works best with collaboration:
 
 ## Reference | 參考
 
-- Methodology: [bdd.methodology.yaml](../../../../methodologies/bdd.methodology.yaml)
+- Methodology: [bdd.methodology.yaml](../../methodologies/bdd.methodology.yaml)
 - Methodology System: [methodology-system](../methodology-system/SKILL.md)

package/bundled/skills/commands/changelog.md

@@ -0,0 +1,58 @@
+---
+name: changelog
+description: "[UDS] Generate and maintain CHANGELOG.md entries"
+---
+
+# Changelog Assistant | 變更日誌助手
+
+Generate and maintain CHANGELOG.md entries following the Keep a Changelog format.
+
+根據 Keep a Changelog 格式產生和維護 CHANGELOG.md 條目。
+
+## Usage | 用法
+
+```bash
+/changelog
+```
+
+## Workflow | 工作流程
+
+1. **Analyze git log** - Read commit history since last release using `git log`
+2. **Categorize changes** - Map commits to changelog categories
+3. **Generate entries** - Write user-friendly descriptions for each change
+4. **Update CHANGELOG.md** - Insert entries into the [Unreleased] or versioned section
+
+## Change Categories | 變更分類
+
+| Category | When to Use | 使用時機 | Commit Types |
+|----------|-------------|---------|-------------|
+| **Added** | New features | 新功能 | `feat` |
+| **Changed** | Modifications to existing features | 修改既有功能 | `perf`, `BREAKING CHANGE` |
+| **Deprecated** | Features to be removed | 即將移除的功能 | -- |
+| **Removed** | Removed features | 已移除的功能 | `BREAKING CHANGE` |
+| **Fixed** | Bug fixes | 錯誤修復 | `fix` |
+| **Security** | Security patches | 安全性修補 | `security` |
+
+## Entry Format | 條目格式
+
+```markdown
+## [Unreleased]
+
+### Added
+- Add user dashboard with customizable widgets (#123)
+
+### Fixed
+- Fix memory leak when processing large files (#456)
+```
+
+### Writing Guidelines | 撰寫指南
+
+- Write for **users**, not developers | 為使用者而非開發者撰寫
+- Focus on **impact**, not implementation | 聚焦影響而非實作
+- Include issue/PR references | 附上 issue/PR 編號
+- Mark breaking changes with **BREAKING** prefix | 用 **BREAKING** 標記破壞性變更
+
+## References | 參考
+
+*   [Changelog Guide Skill](../changelog-guide/SKILL.md)
+*   [Core Standard](../../core/changelog-standards.md)

package/bundled/skills/{claude-code/commands → commands}/check.md

@@ -1,5 +1,5 @@
 ---
-description: Verify standards adoption status
+description: [UDS] Verify standards adoption status
 allowed-tools: Read, Bash(uds check:*), Bash(npx:*), Bash(ls:*)
 argument-hint: "[--offline | --restore | --summary]"
 ---

package/bundled/skills/commands/checkin.md

@@ -0,0 +1,53 @@
+---
+name: checkin
+description: "[UDS] Pre-commit quality gates verification"
+---
+
+# Check-in Assistant | 簽入助手
+
+Verify pre-commit quality gates before committing code to ensure codebase stability.
+
+在提交程式碼前驗證品質關卡，確保程式碼庫的穩定性。
+
+## Usage | 用法
+
+```bash
+/checkin
+```
+
+## Workflow | 工作流程
+
+1. **Check git status** - Run `git status` and `git diff` to understand pending changes
+2. **Run tests** - Execute `npm test` (or project test command) to verify all tests pass
+3. **Run linting** - Execute `npm run lint` to check code style compliance
+4. **Verify quality gates** - Check each gate against the checklist below
+5. **Report results** - Present pass/fail summary and recommend next steps
+
+## Quality Gates | 品質關卡
+
+| Gate | Check | 檢查項目 |
+|------|-------|---------|
+| **Build** | Code compiles with zero errors | 編譯零錯誤 |
+| **Tests** | All existing tests pass (100%) | 所有測試通過 |
+| **Coverage** | Test coverage not decreased | 覆蓋率未下降 |
+| **Code Quality** | Follows coding standards, no code smells | 符合編碼規範 |
+| **Security** | No hardcoded secrets or vulnerabilities | 無硬編碼密鑰 |
+| **Documentation** | API docs and CHANGELOG updated if needed | 文件已更新 |
+| **Workflow** | Branch naming and commit message correct | 分支和提交格式正確 |
+
+## Never Commit When | 禁止提交的情況
+
+- Build has errors | 建置有錯誤
+- Tests are failing | 測試失敗
+- Feature is incomplete and would break functionality | 功能不完整會破壞現有功能
+- Contains debugging code (console.log, print) | 包含除錯程式碼
+- Contains commented-out code blocks | 包含被註解的程式碼區塊
+
+## Next Steps | 後續步驟
+
+After verification passes, proceed with `/commit` to create the commit message.
+
+## References | 參考
+
+*   [Check-in Assistant Skill](../checkin-assistant/SKILL.md)
+*   [Core Standard](../../core/checkin-standards.md)

package/bundled/skills/{claude-code/commands → commands}/commit.md

@@ -1,5 +1,5 @@
 ---
-description: Generate commit messages following Conventional Commits standard
+description: [UDS] Generate commit messages following Conventional Commits standard
 allowed-tools: Read, Grep, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git add:*), Bash(git commit:*)
 argument-hint: "[description of changes | 變更描述]"
 ---
@@ -44,5 +44,5 @@ Generate well-formatted commit messages following the Conventional Commits stand
 
 ## Reference | 參考
 
-- Full standard: [commit-standards](../../commit-standards/SKILL.md)
-- Core guide: [commit-message-guide](../../../../core/commit-message-guide.md)
+- Full standard: [commit-standards](../commit-standards/SKILL.md)
+- Core guide: [commit-message-guide](../../core/commit-message-guide.md)

package/bundled/skills/{claude-code/commands → commands}/config.md

@@ -1,5 +1,5 @@
 ---
-description: Configure project development standards
+description: [UDS] Configure project development standards
 allowed-tools: Read, Bash(uds config:*), Bash(uds configure:*), Bash(uds check:*)
 argument-hint: "[type] [--ai-tool <tool>]"
 ---

package/bundled/skills/{claude-code/commands → commands}/coverage.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze test coverage and provide recommendations
+description: [UDS] Analyze test coverage and provide recommendations
 allowed-tools: Read, Grep, Glob, Bash(npm run test:coverage:*), Bash(npx:*)
 argument-hint: "[file or module to analyze | 要分析的檔案或模組]"
 ---
@@ -19,7 +19,7 @@ Analyze test coverage across multiple dimensions and provide actionable recommen
 | **Function** | Functions called | 呼叫的函數 |
 | **Statement** | Statements executed | 執行的陳述式 |
 
-## 7-Dimension Framework | 七維度框架
+## 8-Dimension Framework | 八維度框架
 
 1. **Code Coverage** - Lines, branches, functions
 2. **Requirement Coverage** - All requirements tested
@@ -28,6 +28,7 @@ Analyze test coverage across multiple dimensions and provide actionable recommen
 5. **Edge Case Coverage** - Boundary conditions
 6. **Error Coverage** - Error handling paths
 7. **Permission Coverage** - Access control scenarios
+8. **AI Generation Quality** - AI-generated test effectiveness
 
 ## Workflow | 工作流程
 
@@ -54,5 +55,5 @@ Analyze test coverage across multiple dimensions and provide actionable recommen
 
 ## Reference | 參考
 
-- Full standard: [test-coverage-assistant](../../test-coverage-assistant/SKILL.md)
-- Core guide: [testing-standards](../../../../core/testing-standards.md)
+- Full standard: [test-coverage-assistant](../test-coverage-assistant/SKILL.md)
+- Core guide: [testing-standards](../../core/testing-standards.md)

package/bundled/skills/commands/derive-all.md

@@ -0,0 +1,53 @@
+---
+description: [UDS] Derive all test structures (BDD, TDD, ATDD) from SDD specification
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[spec file path | 規格檔案路徑]"
+---
+
+# /derive-all — Full Forward Derivation | 完整正向推演
+
+Derive all test structures (BDD + TDD + optionally ATDD) from an approved SDD specification.
+
+從已核准的 SDD 規格推演所有測試結構（BDD + TDD + 可選 ATDD）。
+
+## Workflow | 工作流程
+
+```
+SPEC-XXX.md ──► /derive-bdd ──► /derive-tdd ──► [/derive-atdd] ──► Report
+```
+
+1. **Parse** the SDD spec and validate it is approved
+2. **Run** `/derive-bdd` to generate Gherkin scenarios
+3. **Run** `/derive-tdd` to generate test skeletons
+4. **Optionally** run `/derive-atdd` for acceptance test tables
+5. **Generate** `DERIVATION-REPORT.md` summarizing all outputs
+
+## Output Files | 輸出檔案
+
+| File | Content | 內容 |
+|------|---------|------|
+| `features/SPEC-XXX.feature` | BDD Gherkin scenarios | BDD Gherkin 場景 |
+| `tests/SPEC-XXX.test.ts` | TDD test skeletons | TDD 測試骨架 |
+| `DERIVATION-REPORT.md` | Summary with statistics | 摘要與統計 |
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/derive-all specs/SPEC-001.md` | Full derivation from spec | 從規格完整推演 |
+| `/derive-all` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
+
+## Typical SDD Workflow | 典型 SDD 工作流程
+
+```bash
+/sdd user-authentication          # Step 1: Create spec
+/sdd review specs/SPEC-001.md     # Step 2: Review
+/derive-all specs/SPEC-001.md     # Step 3: Derive tests
+# Step 4: Implement — fill [TODO] markers
+```
+
+## Reference | 參考
+
+- Parent command: [/derive](../forward-derivation/SKILL.md)
+- Core standard: [forward-derivation-standards.md](../../core/forward-derivation-standards.md)
+- Sub-commands: [/derive-bdd](./derive-bdd.md), [/derive-tdd](./derive-tdd.md), [/derive-atdd](./derive-atdd.md)

package/bundled/skills/commands/derive-atdd.md

@@ -0,0 +1,49 @@
+---
+description: [UDS] Derive ATDD acceptance tests from SDD specification
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[spec file path | 規格檔案路徑]"
+---
+
+# /derive-atdd — Derive ATDD Acceptance Tests | 推演 ATDD 驗收測試
+
+Derive ATDD acceptance test tables from an approved SDD specification document.
+
+從已核准的 SDD 規格文件推演 ATDD 驗收測試表格。
+
+## Workflow | 工作流程
+
+```
+SPEC-XXX.md ──► Parse AC ──► Generate acceptance.md ──► Review
+```
+
+1. **Read** the SDD spec and extract acceptance criteria
+2. **Map** each AC to an acceptance test table (Given-When-Then columns)
+3. **Generate** `acceptance.md` with test data and expected results
+4. **Output** derivation summary
+
+## Output Format | 輸出格式
+
+```markdown
+# Acceptance Tests: SPEC-001
+
+## AC-1: [Description]
+
+| # | Given | When | Then | Status |
+|---|-------|------|------|--------|
+| 1 | [precondition] | [action] | [expected] | ⬜ |
+| 2 | [precondition] | [action] | [expected] | ⬜ |
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/derive-atdd specs/SPEC-001.md` | Derive ATDD from specific spec | 從特定規格推演 ATDD |
+| `/derive-atdd` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
+
+> **Note**: BDD scenarios already serve as executable acceptance tests. `/derive-atdd` is for specialized manual testing workflows.
+
+## Reference | 參考
+
+- Parent command: [/derive](../forward-derivation/SKILL.md)
+- Core standard: [forward-derivation-standards.md](../../core/forward-derivation-standards.md)

package/bundled/skills/commands/derive-bdd.md

@@ -0,0 +1,47 @@
+---
+description: [UDS] Derive BDD Gherkin scenarios from SDD specification
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[spec file path | 規格檔案路徑]"
+---
+
+# /derive-bdd — Derive BDD Scenarios | 推演 BDD 場景
+
+Derive Gherkin `.feature` files from an approved SDD specification document.
+
+從已核准的 SDD 規格文件推演 Gherkin `.feature` 檔案。
+
+## Workflow | 工作流程
+
+```
+SPEC-XXX.md ──► Parse AC ──► Generate .feature ──► Review
+```
+
+1. **Read** the SDD spec and extract acceptance criteria
+2. **Map** each AC to a Gherkin Scenario (1:1)
+3. **Generate** `.feature` file with `@SPEC-XXX` and `@AC-N` tags
+4. **Output** derivation summary
+
+## Output Format | 輸出格式
+
+```gherkin
+@SPEC-001
+Feature: [Feature Name]
+
+  @AC-1
+  Scenario: [AC-1 description]
+    Given [context]
+    When [action]
+    Then [expected result]
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/derive-bdd specs/SPEC-001.md` | Derive BDD from specific spec | 從特定規格推演 BDD |
+| `/derive-bdd` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
+
+## Reference | 參考
+
+- Parent command: [/derive](../forward-derivation/SKILL.md)
+- Core standard: [forward-derivation-standards.md](../../core/forward-derivation-standards.md)

package/bundled/skills/commands/derive-tdd.md

@@ -0,0 +1,48 @@
+---
+description: [UDS] Derive TDD test skeletons from SDD specification
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[spec file path | 規格檔案路徑]"
+---
+
+# /derive-tdd — Derive TDD Skeletons | 推演 TDD 測試骨架
+
+Derive test skeleton files from an approved SDD specification document.
+
+從已核准的 SDD 規格文件推演測試骨架檔案。
+
+## Workflow | 工作流程
+
+```
+SPEC-XXX.md ──► Parse AC ──► Generate .test.ts ──► Review
+```
+
+1. **Read** the SDD spec and extract acceptance criteria
+2. **Map** each AC to a `describe`/`it` block with AAA pattern
+3. **Generate** test file with `[TODO]` markers for implementation
+4. **Output** derivation summary
+
+## Output Format | 輸出格式
+
+```typescript
+describe('SPEC-001: [Feature Name]', () => {
+  describe('AC-1: [AC description]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange — [TODO]
+      // Act — [TODO]
+      // Assert — [TODO]
+    });
+  });
+});
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/derive-tdd specs/SPEC-001.md` | Derive TDD from specific spec | 從特定規格推演 TDD |
+| `/derive-tdd` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
+
+## Reference | 參考
+
+- Parent command: [/derive](../forward-derivation/SKILL.md)
+- Core standard: [forward-derivation-standards.md](../../core/forward-derivation-standards.md)

package/bundled/skills/commands/derive.md

@@ -0,0 +1,72 @@
+---
+name: derive
+description: [UDS] Derive BDD scenarios, TDD skeletons, or ATDD tables from specifications.
+argument-hint: "[all|bdd|tdd|atdd] <spec-file> [--lang <lang>] [--framework <fw>] [--output-dir <dir>]"
+---
+
+# Derive Test Structures | 推演測試結構
+
+Generate derived artifacts (BDD scenarios, TDD skeletons, ATDD tables) from approved SDD specifications.
+
+從已批准的 SDD 規格生成衍生工件（BDD 場景、TDD 骨架、ATDD 表格）。
+
+## Usage | 用法
+
+```bash
+/derive [subcommand] <spec-file> [options]
+```
+
+### Subcommands | 子命令
+
+| Subcommand | Description | Output |
+|------------|-------------|--------|
+| `all` | Generate BDD + TDD (Default) | `.feature` + `.test.*` |
+| `bdd` | Generate BDD scenarios only | `.feature` |
+| `tdd` | Generate TDD skeletons only | `.test.*` |
+| `atdd` | Generate ATDD test tables | `.md` (Markdown tables) |
+
+### Options | 選項
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--lang` | Target language (ts, python, etc.) | Detected or `ts` |
+| `--framework` | Test framework (vitest, pytest, etc.) | Detected or `vitest` |
+| `--output-dir` | Output directory | `./generated` |
+| `--dry-run` | Preview output without writing | `false` |
+
+## Workflow | 工作流程
+
+1.  **Read Spec**: Analyze the input `SPEC-XXX.md` file.
+2.  **Extract AC**: Parse all Acceptance Criteria.
+3.  **Generate Artifacts**:
+    *   **BDD**: Convert AC to Gherkin `Scenario` format.
+    *   **TDD**: Create test file skeleton with `describe`/`it` blocks matching ACs.
+    *   **ATDD**: Create a Markdown table with inputs/outputs/pass-fail columns.
+4.  **Verify**: Ensure 1:1 mapping between ACs and generated items.
+
+## Anti-Hallucination | 防幻覺
+
+*   **1:1 Mapping**: Every AC must have exactly one corresponding test/scenario.
+*   **Traceability**: All generated artifacts must reference the Source Spec ID and AC ID.
+*   **No Invention**: Do not add scenarios not present in the spec.
+
+## Examples | 範例
+
+```bash
+# Derive everything (BDD + TDD)
+/derive all specs/SPEC-001.md
+
+# Derive BDD scenarios only
+/derive bdd specs/SPEC-001.md
+
+# Derive TDD for Python
+/derive tdd specs/SPEC-001.md --lang python --framework pytest
+
+# Derive ATDD tables for manual testing
+/derive atdd specs/SPEC-001.md
+```
+
+## References | 參考
+
+*   [Forward Derivation Standard](../forward-derivation/SKILL.md)
+*   [Core Standard](../../core/forward-derivation-standards.md)

package/bundled/skills/commands/discover.md

@@ -0,0 +1,80 @@
+---
+name: discover
+description: "[UDS] Assess project health, architecture, and risks before adding features"
+argument-hint: "[feature area | 功能範圍]"
+---
+
+# Project Discovery | 專案現況評估
+
+Phase 0 assessment before adding features to existing codebases. Evaluate project health, architecture, and risks.
+
+在既有程式碼庫新增功能前的 Phase 0 評估。評估專案健康度、架構與風險。
+
+## Usage | 用法
+
+```bash
+/discover [feature area]
+```
+
+## Assessment Dimensions | 評估維度
+
+| Dimension | What to Check | 檢查項目 |
+|-----------|--------------|----------|
+| **Architecture** | Module structure, dependency graph, entry points | 模組結構、相依圖、進入點 |
+| **Dependencies** | Outdated packages, known vulnerabilities, license risks | 過時套件、已知漏洞、授權風險 |
+| **Test Coverage** | Existing test suite, coverage gaps, test quality | 現有測試、覆蓋率缺口、測試品質 |
+| **Security** | `npm audit` findings, hardcoded secrets, exposed endpoints | 安全稽核、硬編碼密鑰、暴露端點 |
+| **Technical Debt** | TODOs, code duplication, complexity hotspots | TODO 標記、程式碼重複、複雜度熱點 |
+
+## Workflow | 工作流程
+
+1. **Scan project** - Read package.json, directory structure, config files
+2. **Analyze architecture** - Map modules, dependencies, and data flow
+3. **Check dependencies** - Run `npm outdated`, `npm audit` for health signals
+4. **Assess risks** - Identify complexity hotspots, missing tests, security issues
+5. **Generate report** - Output health score with actionable recommendations
+6. **Decide next step** - GO / NO-GO / CONDITIONAL based on findings
+
+## Examples | 範例
+
+```bash
+/discover                # Full project health assessment
+/discover auth           # Focused assessment of auth-related modules
+/discover payments       # Assess risks before adding payment features
+```
+
+## Output Format | 輸出格式
+
+```
+Project Health Report
+=====================
+Overall Score: 7.2 / 10
+
+| Dimension       | Score | Status  | Key Finding            |
+|-----------------|-------|---------|------------------------|
+| Architecture    | 8/10  | Good    | Clean module boundaries |
+| Dependencies    | 6/10  | Warning | 5 outdated, 1 critical |
+| Test Coverage   | 7/10  | Fair    | 72% line coverage      |
+| Security        | 8/10  | Good    | No critical vulns      |
+| Technical Debt  | 6/10  | Warning | 23 TODOs, 3 hotspots   |
+
+Verdict: CONDITIONAL
+Recommendations:
+1. [HIGH] Update lodash to fix CVE-2024-XXXX
+2. [MED]  Add tests for src/payments/ (0% coverage)
+3. [LOW]  Resolve TODO backlog in src/utils/
+```
+
+## Next Steps | 後續步驟
+
+After discovery, the typical brownfield workflow is:
+
+1. `/discover` - Assess project health (this command)
+2. `/reverse spec` - Reverse engineer existing code to specs
+3. `/sdd` - Write specification for new features
+4. `/tdd` or `/bdd` - Implement with test protection
+
+## References | 參考
+
+*   [Project Discovery Skill](../project-discovery/SKILL.md)
+*   [Reverse Engineering Standards](../../core/reverse-engineering-standards.md)

package/bundled/skills/commands/docgen.md

@@ -0,0 +1,61 @@
+---
+name: docgen
+description: "[UDS] Generate usage documentation from project sources"
+argument-hint: "[config file | 設定檔]"
+---
+
+# Documentation Generator | 文件產生器
+
+Generate usage documentation (cheatsheets, references, guides) from project source files.
+
+從專案原始檔案產生使用文件（速查表、參考手冊、使用指南）。
+
+## Usage | 用法
+
+```bash
+/docgen [config file]
+```
+
+## Workflow | 工作流程
+
+1. **Read config** - Load `.usage-docs.yaml` (or specified config file)
+2. **Scan sources** - Read source files, commands, and skill definitions
+3. **Extract content** - Parse descriptions, options, examples from source
+4. **Generate docs** - Produce output in the configured format
+5. **Write output** - Save generated files to the configured output directory
+
+## Output Types | 輸出類型
+
+| Type | Description | 說明 |
+|------|-------------|------|
+| **cheatsheet** | Quick reference card with commands and shortcuts | 速查表，列出命令與快捷方式 |
+| **reference** | Comprehensive feature reference with all options | 完整功能參考手冊含所有選項 |
+| **usage-guide** | Step-by-step usage guide for new users | 新手入門的逐步使用指南 |
+
+## Examples | 範例
+
+```bash
+/docgen                          # Generate docs using default .usage-docs.yaml
+/docgen .usage-docs.yaml         # Generate docs from specified config file
+/docgen --format cheatsheet      # Generate cheatsheet only
+```
+
+## Config File Format | 設定檔格式
+
+```yaml
+# .usage-docs.yaml
+output_dir: docs/generated/
+formats:
+  - cheatsheet
+  - reference
+sources:
+  - path: skills/commands/
+    type: commands
+  - path: cli/src/commands/
+    type: cli
+language: [en, zh-TW]
+```
+
+## References | 參考
+
+*   [Docs Generator Skill](../docs-generator/SKILL.md)