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

package/bundled/skills/commands/docs.md

@@ -0,0 +1,59 @@
+---
+name: docs
+description: [UDS] Manage, guide, and generate documentation.
+argument-hint: "[generate|readme|api] [options]"
+---
+
+# /docs Command | /docs 命令
+
+Manage, write, and generate project documentation.
+
+管理、撰寫和生成專案文件。
+
+## Usage | 用法
+
+```bash
+/docs [subcommand] [options]
+```
+
+### Subcommands | 子命令
+
+| Subcommand | Description |
+|------------|-------------|
+| `generate` | Generate documentation artifacts (cheatsheets, reference) |
+| `readme` | Audit and update README.md |
+| `api` | Generate API documentation from code |
+| `structure` | Check documentation folder structure |
+| `(none)` | Show documentation guide/status |
+
+### Generate Options
+
+Used with `/docs generate`:
+
+| Option | Description |
+|--------|-------------|
+| `--lang <lang>` | Language (`en`, `zh-TW`, `zh-CN`) |
+| `--cheatsheet` | Generate cheatsheet only |
+| `--reference` | Generate feature reference only |
+| `--check` | Check if docs are out of sync |
+
+## Examples | 範例
+
+```bash
+# Generate all docs
+/docs generate
+
+# Generate Traditional Chinese docs
+/docs generate --lang zh-TW
+
+# Update README
+/docs readme
+
+# Check doc structure
+/docs structure
+```
+
+## References | 參考
+
+*   [Documentation Guide Skill](../documentation-guide/SKILL.md)
+*   [Core Standard](../../core/documentation-writing-standards.md)

package/bundled/skills/commands/guide.md

@@ -0,0 +1,44 @@
+---
+name: guide
+description: [UDS] Access Universal Development Standards guides and references.
+---
+
+# /guide Command
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/commands/guide.md)
+
+The `/guide` command is the central entry point for accessing all Universal Development Standards reference materials and guidelines.
+
+## Usage
+
+```bash
+/guide [topic]
+```
+
+## Available Topics
+
+| Topic | Description | Source |
+|-------|-------------|--------|
+| `git` | Git workflow & branching strategies | `skills/git-workflow-guide/` |
+| `testing` | Testing pyramid & strategy | `skills/testing-guide/` |
+| `errors` | Error code design standards | `skills/error-code-guide/` |
+| `logging` | Structured logging standards | `skills/logging-guide/` |
+| `structure` | Project structure conventions | `skills/project-structure-guide/` |
+| `ai-arch` | AI-friendly architecture | `skills/ai-friendly-architecture/` |
+| `ai-collab` | AI collaboration & anti-hallucination | `skills/ai-collaboration-standards/` |
+| `ai-instruct` | AI instruction file standards | `skills/ai-instruction-standards/` |
+
+## Examples
+
+- `/guide git` - Show Git branching and naming conventions
+- `/guide testing` - Show testing pyramid and best practices
+- `/guide structure` - Show recommended project folder structure
+- `/guide` - List all available guides
+
+## Implementation Note for AI
+
+When the user invokes `/guide [topic]`:
+1.  Identify the requested topic.
+2.  Read the corresponding standard/skill file (e.g., `skills/git-workflow-guide/SKILL.md`).
+3.  Summarize or present the key information from that file to the user.
+4.  If the topic is missing or invalid, list the available topics.

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

@@ -1,5 +1,5 @@
 ---
-description: Initialize development standards in current project
+description: [UDS] Initialize development standards in current project
 allowed-tools: Read, Bash(uds init:*), Bash(npx:*)
 argument-hint: "[--level N | --yes]"
 ---
@@ -283,6 +283,6 @@ See `uds init --help` for all options.
 ## Reference | 參考
 
 - CLI documentation: `uds init --help`
-- Adoption guide: [ADOPTION-GUIDE.md](../../../adoption/ADOPTION-GUIDE.md)
+- Adoption guide: [ADOPTION-GUIDE.md](../../adoption/ADOPTION-GUIDE.md)
 - Check command: [/check](./check.md)
 - Update command: [/update](./update.md)

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

@@ -1,5 +1,5 @@
 ---
-description: Manage development methodology workflow
+description: [UDS] Manage development methodology workflow
 allowed-tools: Read, Write, Glob, Grep, Bash(git:*)
 argument-hint: "[action] [argument]"
 status: experimental
@@ -7,7 +7,7 @@ status: experimental
 
 # Methodology Command | 方法論命令
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/commands/methodology.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/commands/methodology.md)
 
 > [!WARNING]
 > **Experimental Feature / 實驗性功能**
@@ -15,9 +15,16 @@ status: experimental
 > This feature is under active development and may change significantly in v4.0.
 > 此功能正在積極開發中，可能在 v4.0 中有重大變更。
 
-Manage the active development methodology for the current project. Supports TDD, BDD, SDD, ATDD, and custom methodologies.
+Manage the active development methodology for the current project.
 
-管理當前專案的開發方法論。支援 TDD、BDD、SDD、ATDD 和自訂方法論。
+管理當前專案的開發方法論。
+
+**Two Independent Systems / 兩個獨立系統：**
+- **System A: SDD** - Spec-Driven Development (AI-era, spec-first)
+- **System B: Double-Loop TDD** - BDD (outer) + TDD (inner) (traditional)
+
+**Optional Input / 可選輸入：**
+- **ATDD** - Acceptance Test-Driven Development (workshop method, feeds into either system)
 
 ---
 
@@ -151,18 +158,23 @@ Are you sure you want to skip?
 
 **Output:**
 ```
-📚 Available Methodologies
+📚 Available Methodology Systems
+
+System A: SDD (AI-Era)
+  └─ sdd    Spec-Driven Development
+            /sdd → Review → /derive-all → Implementation
+
+System B: Double-Loop TDD (Traditional)
+  ├─ bdd    BDD Outer Loop (Discovery → Formulation)
+  └─ tdd    TDD Inner Loop (Red → Green → Refactor)
 
-Built-in:
-  ├─ tdd    Test-Driven Development (Red → Green → Refactor)
-  ├─ bdd    Behavior-Driven Development (Given-When-Then)
-  ├─ sdd    Spec-Driven Development (Spec First, Code Second)
-  └─ atdd   Acceptance Test-Driven Development
+Optional Input (feeds into either system):
+  └─ atdd   ATDD Workshop (stakeholder collaboration)
 
 Custom (.standards/methodologies/):
   └─ my-team-workflow   Our Team's Development Process
 
-Active: tdd ✓
+Active: sdd (System A) ✓
 
 Use '/methodology switch <id>' to change.
 ```
@@ -245,11 +257,14 @@ You can also configure methodology settings using:
 
 ## Related Commands | 相關命令
 
-| Command | Description |
-|---------|-------------|
-| `/tdd` | Start TDD workflow (activates TDD methodology) |
-| `/spec` | Start SDD workflow (activates SDD methodology) |
-| `/config methodology` | Configure methodology settings |
+| Command | System | Description |
+|---------|--------|-------------|
+| `/sdd` | A: SDD | Start SDD spec proposal |
+| `/derive-all` | A: SDD | Generate tests from spec |
+| `/bdd` | B: Double-Loop TDD | Start BDD outer loop |
+| `/tdd` | B: Double-Loop TDD | Start TDD inner loop |
+| `/atdd` | Input (both) | Start ATDD workshop |
+| `/config methodology` | - | Configure methodology settings |
 
 ---
 
@@ -265,4 +280,5 @@ You can also configure methodology settings using:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-25 | Update to reflect two independent systems architecture |
 | 1.0.0 | 2026-01-12 | Initial /methodology command |

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

@@ -1,5 +1,5 @@
 ---
-description: Guide refactoring decisions and strategy selection
+description: [UDS] Guide refactoring decisions and strategy selection
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
 argument-hint: "[scope: tactical | strategic | legacy | decide | debt]"
 status: stable
@@ -168,6 +168,6 @@ This command integrates with:
 
 ## Reference | 參考
 
-- [Refactoring Standards](../../../core/refactoring-standards.md) - Core standard
+- [Refactoring Standards](../../core/refactoring-standards.md) - Core standard
 - [Refactoring Assistant Skill](../refactoring-assistant/SKILL.md) - Full skill
 - [TDD Assistant](../tdd-assistant/SKILL.md) - TDD workflow

package/bundled/skills/commands/release.md

@@ -0,0 +1,56 @@
+---
+name: release
+description: [UDS] Manage release process and changelogs.
+argument-hint: "[start|finish|changelog] <version>"
+---
+
+# /release Command | /release 命令
+
+Manage the release workflow and changelogs according to Semantic Versioning.
+
+根據語義化版本管理發布流程和變更日誌。
+
+## Usage | 用法
+
+```bash
+/release [subcommand] [version]
+```
+
+### Subcommands | 子命令
+
+| Subcommand | Description |
+|------------|-------------|
+| `start` | Start a release branch/process |
+| `finish` | Finalize release (tag, merge) |
+| `changelog` | Generate or update CHANGELOG.md |
+| `check` | Run pre-release checks |
+
+## Changelog Management
+
+```bash
+/release changelog [version]
+```
+
+Updates `CHANGELOG.md` by:
+1.  Moving "Unreleased" changes to the new `[version]` section.
+2.  Creating a new "Unreleased" section.
+3.  Updating comparison links at the bottom.
+
+## Examples | 範例
+
+```bash
+# Start release v1.2.0
+/release start 1.2.0
+
+# Update changelog for v1.2.0
+/release changelog 1.2.0
+
+# Finish release
+/release finish 1.2.0
+```
+
+## References | 參考
+
+*   [Release Standards Skill](../release-standards/SKILL.md)
+*   [Changelog Guide](../changelog-guide/SKILL.md)
+*   [Core Standard](../../core/versioning.md)

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

@@ -1,5 +1,5 @@
 ---
-description: Write user stories and requirements following INVEST criteria
+description: [UDS] Write user stories and requirements following INVEST criteria
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature name or description | 功能名稱或描述]"
 ---
@@ -50,5 +50,5 @@ So that [benefit].
 
 ## Reference | 參考
 
-- Full standard: [requirement-assistant](../../requirement-assistant/SKILL.md)
-- Core guide: [requirements-standards](../../../../core/requirements-standards.md)
+- Full standard: [requirement-assistant](../requirement-assistant/SKILL.md)
+- Core guide: [requirements-standards](../../core/requirement-engineering.md)

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

@@ -0,0 +1,47 @@
+---
+description: [UDS] Transform SDD acceptance criteria to BDD scenarios
+allowed-tools: Read, Grep, Glob, Write
+argument-hint: "[spec file or source directory | 規格檔案或原始碼目錄]"
+---
+
+# /reverse-bdd — Extract BDD Scenarios | 擷取 BDD 場景
+
+Transform existing code or SDD acceptance criteria into BDD Gherkin scenarios.
+
+將現有程式碼或 SDD 驗收條件轉換為 BDD Gherkin 場景。
+
+## Workflow | 工作流程
+
+```
+Source/Spec ──► Analyze Behaviors ──► Generate .feature ──► Review
+```
+
+1. **Analyze** source code or spec for behavioral patterns
+2. **Extract** implicit Given-When-Then flows
+3. **Generate** Gherkin `.feature` file
+4. **Tag** with certainty labels: `[Confirmed]`, `[Inferred]`
+
+## Output Format | 輸出格式
+
+```gherkin
+# [Source: src/auth/login.js:45]
+Feature: User Login [Inferred]
+
+  # [Confirmed] from test/auth.test.js:12
+  Scenario: Successful login
+    Given a registered user exists
+    When they submit valid credentials
+    Then they receive an auth token
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/reverse-bdd src/auth/` | Extract BDD from auth module | 從 auth 模組擷取 BDD |
+| `/reverse-bdd specs/SPEC-001.md` | Convert spec AC to BDD | 將規格 AC 轉為 BDD |
+
+## Reference | 參考
+
+- Parent command: [/reverse](../reverse-engineer/SKILL.md)
+- Core standard: [reverse-engineering-standards.md](../../core/reverse-engineering-standards.md)

package/bundled/skills/commands/reverse-sdd.md

@@ -0,0 +1,51 @@
+---
+description: [UDS] Reverse engineer code into SDD specification document
+allowed-tools: Read, Grep, Glob, Write
+argument-hint: "[source file or directory | 原始檔案或目錄]"
+---
+
+# /reverse-sdd — Reverse Engineer to SDD Spec | 反向工程為 SDD 規格
+
+Reverse engineer existing code into a structured SDD specification document.
+
+將現有程式碼反向工程為結構化的 SDD 規格文件。
+
+## Workflow | 工作流程
+
+```
+Source Code ──► Analyze ──► Extract Requirements ──► Generate SPEC-XXX.md
+```
+
+1. **Scan** source code structure and dependencies
+2. **Extract** implicit requirements, API contracts, business rules
+3. **Classify** certainty of each finding: `[Confirmed]`, `[Inferred]`, `[Assumption]`
+4. **Generate** SDD-compliant specification document
+5. **Review** generated spec for accuracy
+
+## Output Format | 輸出格式
+
+```markdown
+# [SPEC-XXX] Feature: [Reverse-Engineered Name]
+
+## Overview
+[Inferred] Based on analysis of src/auth/...
+
+## Requirements
+- REQ-001: [Confirmed] User authentication via OAuth2
+- REQ-002: [Inferred] Session timeout after 30 minutes
+
+## Acceptance Criteria
+- AC-1: [Confirmed] Given valid credentials, when login, then session created
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/reverse-sdd src/auth/` | Reverse engineer auth module | 反向工程 auth 模組 |
+| `/reverse-sdd` | Interactive — ask for target | 互動式 — 詢問目標 |
+
+## Reference | 參考
+
+- Parent command: [/reverse](../reverse-engineer/SKILL.md)
+- Core standard: [reverse-engineering-standards.md](../../core/reverse-engineering-standards.md)

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

@@ -0,0 +1,51 @@
+---
+description: [UDS] Analyze BDD-TDD coverage gaps
+allowed-tools: Read, Grep, Glob, Write
+argument-hint: "[feature file or test directory | Feature 檔案或測試目錄]"
+---
+
+# /reverse-tdd — Analyze BDD-TDD Coverage Gaps | 分析 BDD-TDD 覆蓋差距
+
+Analyze gaps between BDD scenarios and TDD test coverage.
+
+分析 BDD 場景與 TDD 測試覆蓋之間的差距。
+
+## Workflow | 工作流程
+
+```
+.feature + tests/ ──► Map Scenarios ──► Find Gaps ──► Report
+```
+
+1. **Parse** existing `.feature` files for scenarios
+2. **Scan** test files for corresponding unit tests
+3. **Map** BDD scenarios to TDD test coverage
+4. **Identify** coverage gaps (scenarios without unit tests)
+5. **Generate** gap report with recommendations
+
+## Output Format | 輸出格式
+
+```markdown
+# BDD-TDD Coverage Gap Analysis
+
+## Coverage Summary
+- Total BDD Scenarios: 12
+- Covered by TDD: 9 (75%)
+- Gaps Found: 3
+
+## Gaps
+| Scenario | Feature File | Missing TDD |
+|----------|-------------|-------------|
+| Password reset | auth.feature:15 | No unit test for token validation |
+```
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/reverse-tdd features/` | Analyze all feature files | 分析所有 feature 檔案 |
+| `/reverse-tdd features/auth.feature` | Analyze specific feature | 分析特定 feature |
+
+## Reference | 參考
+
+- Parent command: [/reverse](../reverse-engineer/SKILL.md)
+- Core standard: [reverse-engineering-standards.md](../../core/reverse-engineering-standards.md)

package/bundled/skills/commands/reverse.md

@@ -0,0 +1,63 @@
+---
+name: reverse
+description: [UDS] Reverse engineer code to Specs, BDD, or TDD coverage.
+argument-hint: "[spec|bdd|tdd] <input> [--output <file>]"
+---
+
+# Reverse Engineering | 反向工程
+
+Reverse engineer existing code or tests into specifications and scenarios.
+
+將現有代碼或測試反向工程為規格和場景。
+
+## Usage | 用法
+
+```bash
+/reverse [subcommand] <input> [options]
+```
+
+### Subcommands | 子命令
+
+| Subcommand | Input | Output | Description |
+|------------|-------|--------|-------------|
+| `spec` | Code files/dirs | `SPEC-XXX.md` | Create SDD Spec from code |
+| `bdd` | `SPEC-XXX.md` | `.feature` | Convert Spec ACs to Gherkin |
+| `tdd` | `.feature` | Coverage Report | Analyze TDD coverage of features |
+
+### Options | 選項
+
+| Option | Description |
+|--------|-------------|
+| `--output` | Output file path |
+| `--include-tests` | Include test files in analysis (for `spec`) |
+| `--review` | Trigger review after generation |
+
+## Workflows | 工作流程
+
+### 1. Code to Spec (Legacy Recovery)
+```bash
+/reverse spec src/auth/ --output specs/SPEC-AUTH.md
+```
+Analyzes code logic to create a functional specification.
+
+### 2. Spec to BDD (Scenario Generation)
+```bash
+/reverse bdd specs/SPEC-AUTH.md --output features/auth.feature
+```
+Converts Acceptance Criteria from the spec into Gherkin scenarios.
+
+### 3. BDD to TDD (Coverage Analysis)
+```bash
+/reverse tdd features/auth.feature
+```
+Checks if the scenarios in the feature file have corresponding unit tests.
+
+## Anti-Hallucination | 防幻覺
+
+*   **Certainty Tags**: Use `[Confirmed]`, `[Inferred]`, `[Unknown]` tags in output.
+*   **Source Attribution**: Cite `file:line` for all reversed logic.
+
+## References | 參考
+
+*   [Reverse Engineering Skill](../reverse-engineer/SKILL.md)
+*   [Core Standard](../../core/reverse-engineering-standards.md)

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

@@ -1,5 +1,5 @@
 ---
-description: Perform systematic code review with checklist
+description: [UDS] Perform systematic code review with checklist
 allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), Bash(git show:*)
 argument-hint: "[file path or branch | 檔案路徑或分支名稱]"
 ---
@@ -46,5 +46,5 @@ Perform systematic code review using standardized checklists and comment prefixe
 
 ## Reference | 參考
 
-- Full standard: [code-review-assistant](../../code-review-assistant/SKILL.md)
-- Core guide: [code-review-checklist](../../../../core/code-review-checklist.md)
+- Full standard: [code-review-assistant](../code-review-assistant/SKILL.md)
+- Core guide: [code-review-checklist](../../core/code-review-checklist.md)

package/bundled/skills/commands/sdd.md

@@ -0,0 +1,135 @@
+---
+description: [UDS] Create or review specification documents for Spec-Driven Development
+allowed-tools: Read, Write, Grep, Glob, Bash(git:*)
+argument-hint: "[spec name or feature | 規格名稱或功能]"
+---
+
+# Spec-Driven Development Assistant | 規格驅動開發助手
+
+Create, review, and manage specification documents for implementing features.
+
+建立、審查和管理規格文件，用於實作功能。
+
+## Enhanced Workflow | 增強工作流程
+
+### Phase 0: Scope Evaluation (NEW) | 範圍評估（新增）
+
+Before creating a spec, evaluate the change scope:
+
+在建立規格前，先評估變更範圍：
+
+**Q1: Scope | 範圍**
+- [ ] Project-specific (CLAUDE.md only) | 專案專用
+- [ ] Universal (Core Standard) | 通用規則
+
+**Q2: Interaction | 互動**
+- [ ] Needs AI interaction → Create Skill | 需要 AI 互動 → 建立 Skill
+- [ ] Static rule only | 靜態規則
+
+**Q3: Trigger | 觸發**
+- [ ] User-triggered → Create Command | 使用者觸發 → 建立命令
+- [ ] AI applies automatically | AI 自動應用
+
+**Record in spec metadata:**
+```yaml
+scope: universal|project|utility
+sync-to:
+  - core-standard: pending|complete|N/A
+  - skill: pending|complete|N/A
+  - command: pending|complete|N/A
+  - translations: pending|complete|N/A
+```
+
+### Phase 1-5: Standard Workflow | 標準流程
+
+1. **Create spec** - Write detailed specification document
+2. **Review spec** - Validate against requirements
+3. **Approve spec** - Get stakeholder sign-off
+4. **Implement** - Code follows the approved spec
+5. **Verify** - Ensure implementation matches spec
+
+### Phase 6: Sync Verification (NEW) | 同步驗證（新增）
+
+After implementation, verify all sync targets:
+
+實作後，驗證所有同步目標：
+
+- [ ] Core Standard created/updated (if universal)
+- [ ] Skill created/updated (if interactive)
+- [ ] Command created/updated (if user-triggered)
+- [ ] Translations synchronized
+
+## Spec Document Structure | 規格文件結構
+
+```markdown
+# Feature: [Feature Name]
+
+## Overview
+Brief description of the feature.
+
+## Requirements
+- REQ-001: [Requirement description]
+- REQ-002: [Requirement description]
+
+## Technical Design
+### Architecture
+[Design details]
+
+### API Changes
+[API specifications]
+
+### Database Changes
+[Schema changes]
+
+## Test Plan
+- [ ] Unit tests for [component]
+- [ ] Integration tests for [flow]
+
+## Rollout Plan
+[Deployment strategy]
+```
+
+## Spec States | 規格狀態
+
+| State | Description | 說明 |
+|-------|-------------|------|
+| Draft | Work in progress | 草稿中 |
+| Review | Under review | 審查中 |
+| Approved | Ready for implementation | 已核准 |
+| Implemented | Code complete | 已實作 |
+| Archived | Completed or deprecated | 已歸檔 |
+
+## Usage | 使用方式
+
+- `/sdd` - Interactive spec creation wizard (includes scope evaluation)
+- `/sdd auth-flow` - Create spec for specific feature
+- `/sdd review` - Review existing specs
+- `/sdd --evaluate` - Run scope evaluation only (without creating spec)
+- `/sdd --sync-check` - Check sync status of existing specs
+
+## Sync Checklist Template | 同步檢查清單範本
+
+Include in every spec:
+
+```markdown
+## Sync Checklist
+
+### From Core Standard
+- [ ] Skill created/updated?
+- [ ] Command created?
+- [ ] Translations synced?
+
+### From Skill
+- [ ] Core Standard exists? (or marked as [Scope: Utility])
+- [ ] Command created?
+- [ ] Translations synced?
+
+### From Command
+- [ ] Skill documentation updated?
+- [ ] Translations synced?
+```
+
+## Reference | 參考
+
+- Full standard: [spec-driven-dev](../spec-driven-dev/SKILL.md)
+- Core standard: [spec-driven-development.md](../../core/spec-driven-development.md)

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

@@ -1,5 +1,5 @@
 ---
-description: Guide through Test-Driven Development workflow
+description: [UDS] Guide through Test-Driven Development workflow
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
 argument-hint: "[feature or function to implement | 要實作的功能]"
 status: experimental
@@ -82,5 +82,5 @@ See [methodology-system](../methodology-system/SKILL.md) for full methodology tr
 
 ## Reference | 參考
 
-- Full standard: [tdd-assistant](../../tdd-assistant/SKILL.md)
-- Core guide: [testing-standards](../../../../core/testing-standards.md)
+- Full standard: [tdd-assistant](../tdd-assistant/SKILL.md)
+- Core guide: [testing-standards](../../core/testing-standards.md)