Skills for development standards: commit messages, code review, testing, documentation, git workflow, release management, and more. Language-agnostic and framework-agnostic.

version
6.15.0
GitHub stars
85

Install

/plugin install universal-dev-standards@asia-ostrich

Run it inside Claude Code after adding the marketplace with /plugin marketplace add AsiaOstrich/universal-dev-standards.

Contents

Discovered from source

Commands 51

AC Coverage | AC 覆蓋率

Generate an Acceptance Criteria (AC) to test traceability matrix and coverage report from a specification file.

從規格檔案產生驗收條件(AC)與測試的追蹤矩陣及覆蓋率報告。

Usage | 用法

/ac-coverage specs/SPEC-001.md            # Analyze specific SPEC
/ac-coverage specs/SPEC-001.md --threshold 90   # Custom threshold
/ac-coverage specs/SPEC-001.md --test-dir tests/ # Specify test directory

Workflow | 工作流程

  1. Parse SPEC — Read the specification file and extract all AC definitions (AC-1, AC-2, ...)
  2. Scan tests — Search test files for @AC and @SPEC annotations
  3. Build matrix — Map each AC to its corresponding test references
  4. Classify status — ✅ covered | ⚠️ partial | ❌ uncovered
  5. Calculate coverage — Coverage % = (covered + partial × 0.5) / total × 100
  6. Generate report — Output standardized Markdown report

How This Differs from /coverage | 與 /coverage 的區別

/coverage/ac-coverage
LevelCode (line/branch/function)Requirements (AC-to-test)
Question"How much code is tested?""Which AC have tests?"
InputSource code + test runnerSPEC file + test annotations

Both are complementary — use /coverage for code quality, /ac-coverage for requirement verification.

兩者互補 — 使用 /coverage 確保程式碼品質,使用 /ac-coverage 確保需求驗證。

Quality Thresholds | 品質門檻

ContextDefault ThresholdConfigurable
Check-in80%--threshold N
Release100%--threshold N
Warning60%--threshold N

Output Format | 輸出格式

# AC Coverage Report

**Specification**: SPEC-001 — Feature Name
**Generated**: 2026-03-18
**Coverage**: 75% (6/8 AC)

## Summary

| Status | Count | Percentage |
|--------|-------|------------|
| ✅ Covered | 5 | 62.5% |
| ⚠️ Partial | 2 | 25.0% |
| ❌ Uncovered | 1 | 12.5% |

## Traceability Matrix

| AC-ID | Description | Status | Test Reference |
|-------|-------------|--------|----------------|
| AC-1 | ... | ✅ | test-file.ts:15 |

## Gaps
- **AC-8**: Blocked by external dependency

## Action Items
1. [ ] AC-8: Resolve blocker

Next Steps Guidance | 下一步引導

After /ac-coverage completes, the AI assistant should suggest:

AC 覆蓋率分析完成。建議下一步 / AC coverage analysis complete. Suggested next steps:

  • 覆蓋率達標 → 執行 /checkin 品質關卡 — Coverage meets threshold → Run /checkin quality gates
  • 有未覆蓋 AC → 執行 /derive-tdd 補齊測試 — Uncovered AC found → Run /derive-tdd to add tests
  • 有部分覆蓋 AC → 檢查缺少的邊界情況 — Partial AC → Review missing edge cases

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/ac-coverage列出可用的 spec 檔案供選擇
/ac-coverage <spec-file>直接分析指定 spec 的 AC 覆蓋率
/ac-coverage <spec-file> --threshold N使用自訂門檻

Interaction Script | 互動腳本

  1. 讀取 spec 檔案,擷取所有 AC
  2. 掃描測試檔案中的 @AC 和 @SPEC 註解
  3. 建立 AC → Test 追蹤矩陣
  4. 計算覆蓋率
  5. 生成報告

Decision: 覆蓋率結果

  • IF 覆蓋率 ≥ 門檻 → 標記 ✅,建議 /checkin
  • IF 有未覆蓋 AC → 列出並建議 /derive-tdd 補測試
  • IF 有部分覆蓋 AC → 建議檢查缺少的邊界情況

🛑 STOP: 報告展示後等待使用者決定下一步

Stop Points | 停止點

Stop Point等待內容
報告展示後使用者決定補測試或繼續

Error Handling | 錯誤處理

Error ConditionAI Action
Spec 檔案不存在列出可用的 spec 檔案
Spec 無 AC 定義告知並引導修改 spec
測試檔案無 @AC 註解嘗試以命名慣例匹配,標記 [Inferred]

References | 參考

API Design Assistant | API 設計助手

Guide API design following REST, GraphQL and gRPC best practices.

引導 API 設計,遵循 REST、GraphQL 和 gRPC 最佳實踐。

Workflow | 工作流程

DEFINE ──► DESIGN ──► VALIDATE ──► DOCUMENT
  1. Define — Gather requirements, identify resources and operations
  2. Design — Design endpoints, request/response schemas, error codes
  3. Validate — Check consistency, naming conventions, versioning
  4. Document — Generate API documentation

Usage | 使用方式

  • /api-design - Start interactive API design session
  • /api-design /users - Design API for specific resource
  • /api-design --graphql - Design using GraphQL approach

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/api-design詢問 API 需求和目標資源,進入 DEFINE 階段
/api-design <resource>以指定資源為目標,進入 DEFINE
/api-design --graphql使用 GraphQL 方法設計

Interaction Script | 互動腳本

DEFINE Phase
  1. 收集 API 需求(目標使用者、資源、操作)
  2. 確認 API 風格(REST / GraphQL / gRPC)

🛑 STOP: 需求確認後等待使用者確認進入 DESIGN

DESIGN Phase
  1. 設計端點/schema
  2. 定義 request/response 格式
  3. 設計錯誤碼和狀態碼
  4. 展示設計結果

🛑 STOP: 設計展示後等待使用者確認

VALIDATE Phase
  1. 檢查命名一致性、RESTful 慣例
  2. 驗證版本策略
  3. 展示驗證報告
DOCUMENT Phase
  1. 生成 API 文件(OpenAPI / GraphQL Schema)

🛑 STOP: 文件生成後等待使用者確認寫入

Stop Points | 停止點

PhaseStop Point等待內容
DEFINE需求確認後確認進入 DESIGN
DESIGN設計展示後確認設計方案
DOCUMENT文件生成後確認寫入

Error Handling | 錯誤處理

Error ConditionAI Action
無法判斷 API 風格列出選項(REST/GraphQL/gRPC),請使用者選擇
資源命名不符慣例建議修正,展示命名規則

Reference | 參考

ATDD Assistant | ATDD 助手

[!WARNING] Experimental Feature / 實驗性功能

This feature is under active development and may change significantly in v4.0. 此功能正在積極開發中,可能在 v4.0 中有重大變更。

Guide through the Acceptance Test-Driven Development (ATDD) workflow for defining and implementing user stories.

引導驗收測試驅動開發(ATDD)流程,用於定義和實作使用者故事。

Methodology Integration | 方法論整合

When /atdd is invoked:

  1. Automatically activate ATDD methodology if not already active
  2. Set current phase to SPECIFICATION-WORKSHOP (defining acceptance criteria)
  3. Track phase transitions as work progresses
  4. Show phase indicators in responses (🤝 Workshop, 🧪 Distillation, 💻 Development, 🎬 Demo, ✅ Done)

當調用 /atdd 時:

  1. 自動啟用 ATDD 方法論(如果尚未啟用)
  2. 將當前階段設為規格工作坊(定義驗收條件)
  3. 追蹤階段轉換隨著工作進展
  4. 在回應中顯示階段指示器(🤝 工作坊、🧪 提煉、💻 開發、🎬 展示、✅ 完成)

See methodology-system for full methodology tracking.

ATDD Cycle | ATDD 循環

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ┌──────────┐  ┌───────────┐  ┌───────────┐  ┌──────┐  ┌──────┐│
│  │ WORKSHOP │► │ DISTILL   │► │ DEVELOP   │► │ DEMO │► │ DONE ││
│  └──────────┘  └───────────┘  └───────────┘  └──────┘  └──────┘│
│       ▲                              │              │           │
│       │                              │              │           │
│       └──────────────────────────────┴──────────────┘           │
│                  (Refinement needed)                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Workflow | 工作流程

1. SPECIFICATION WORKSHOP - Define AC | 定義驗收條件

  • PO presents user story
  • Team asks clarifying questions
  • Define acceptance criteria together
  • Document out of scope items

2. DISTILLATION - Convert to Tests | 轉換為測試

  • Convert AC to executable test format
  • Remove ambiguity
  • Get PO sign-off

3. DEVELOPMENT - Implement | 實作

  • Run acceptance tests (should fail initially)
  • Use BDD/TDD for implementation
  • Iterate until all tests pass

4. DEMO - Present to Stakeholders | 向利害關係人展示

  • Show passing acceptance tests
  • Demonstrate working functionality
  • Get formal PO acceptance

5. DONE - Complete | 完成

  • PO accepted
  • Code merged
  • Story closed

User Story Template | 使用者故事模板

## User Story: [Title]

**As a** [role]
**I want** [feature]
**So that** [benefit]

## Acceptance Criteria

### AC-1: [Happy path]
**Given** [precondition]
**When** [action]
**Then** [expected result]

### AC-2: [Error scenario]
**Given** [precondition]
**When** [invalid action]
**Then** [error handling]

## Out of Scope
- [Things explicitly not included]

## Technical Notes
- [Implementation hints]

INVEST Criteria | INVEST 準則

CriteriaDescription描述
IndependentCan be developed independently可獨立開發
NegotiableDetails can be discussed細節可協商
ValuableDelivers business value提供商業價值
EstimableCan be estimated可估算
SmallFits in one sprint一個 Sprint 可完成
TestableClear acceptance criteria有明確驗收條件

Integration with BDD/TDD | 與 BDD/TDD 整合

ATDD Level (Business Acceptance)
  │
  └─▶ BDD Level (Behavior Specification)
         │
         └─▶ TDD Level (Unit Implementation)

Usage | 使用方式

  • /atdd - Start interactive ATDD session
  • /atdd "user can reset password" - ATDD for specific feature
  • /atdd US-123 - ATDD for existing user story

Phase Checklist | 階段檢查清單

Workshop Phase

  • PO present
  • User story explained
  • AC in Given-When-Then
  • Out of scope documented

Distillation Phase

  • AC converted to executable tests
  • Tests are unambiguous
  • PO signed off

Development Phase

  • Acceptance tests fail initially
  • BDD/TDD used for implementation
  • All acceptance tests pass

Demo Phase

  • Demo environment ready
  • Tests shown passing
  • PO formally accepts

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/atdd詢問使用者故事,進入 🤝 WORKSHOP
/atdd "user story"以指定故事為目標,進入 🤝 WORKSHOP
/atdd <story-id>載入現有故事,判斷進入哪個階段

Interaction Script | 互動腳本

🤝 WORKSHOP Phase
  1. 請使用者描述使用者故事(As a / I want / So that)
  2. 引導定義驗收條件(Given-When-Then)
  3. 記錄 Out of Scope 項目

Decision: PO 角色

  • IF 使用者是 PO → 直接收集 AC
  • IF 使用者是開發者 → AI 模擬 PO 視角提出質疑和補充
  • ELSE → 建議邀請 PO 參與,或由 AI 輔助

🛑 STOP: AC 定義完成後展示使用者故事文件,等待確認

🧪 DISTILLATION Phase
  1. 將 AC 轉換為可執行的測試格式
  2. 消除歧義
  3. 展示可執行測試

🛑 STOP: 展示測試後等待使用者(或 PO)簽核

💻 DEVELOPMENT Phase
  1. 執行驗收測試(預期失敗)
  2. 使用 BDD/TDD 實作功能
  3. 迭代直到所有測試通過

🛑 STOP: 所有測試通過後等待使用者確認進入 DEMO

🎬 DEMO Phase
  1. 展示通過的測試結果
  2. 展示可運作的功能
  3. 等待 PO 正式驗收

🛑 STOP: 等待使用者確認 PO 已驗收

Stop Points | 停止點

PhaseStop Point等待內容
WORKSHOPAC 定義後確認使用者故事
DISTILLATION測試轉換後PO 簽核
DEVELOPMENT所有測試通過後確認進入 DEMO
DEMO功能展示後PO 正式驗收

Error Handling | 錯誤處理

Error ConditionAI Action
使用者故事不符合 INVEST 準則指出哪些準則未滿足,建議修改
PO 不在場AI 模擬 PO 視角提問,標記 [Needs PO Confirmation]
驗收測試無法自動化建議手動測試替代方案,產出測試檢查清單
DEVELOPMENT 階段反覆失敗回到 WORKSHOP 重新審視 AC 是否合理

Reference | 參考

Audit Assistant | 審計助手

UDS health check and feedback system — diagnose installation integrity and detect development patterns.

UDS 健康檢查與回饋系統——診斷安裝完整性與偵測開發模式。

Workflow | 工作流程

DIAGNOSE ──► ANALYZE ──► REPORT

Usage | 使用方式

  • /audit - Run full audit
  • /audit --health - Installation health check
  • /audit --patterns - Detect development patterns
  • /audit --friction - Identify friction points
  • /audit --report - Generate comprehensive report

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/audit執行完整審計(health + patterns + friction)
/audit --health僅檢查 UDS 安裝完整性
/audit --patterns僅偵測開發模式
/audit --friction僅識別摩擦點
/audit --report生成完整報告(含建議)

Interaction Script | 互動腳本

  1. 依模式執行對應的診斷
  2. 收集分析結果
  3. 生成報告

Decision: 健康狀態

  • IF ERROR 級問題 → 建議執行 uds init 或 uds check --restore
  • IF WARNING 級問題 → 列出建議,使用者自行決定
  • IF 全部 OK → 展示健康摘要

🛑 STOP: 報告展示後等待使用者決定

Stop Points | 停止點

Stop Point等待內容
報告展示後使用者決定採取行動

Error Handling | 錯誤處理

Error ConditionAI Action
UDS 未安裝建議執行 uds init
.standards/ 目錄不存在告知 UDS 標準未安裝

Reference | 參考

BDD Assistant | BDD 助手

[!WARNING] Experimental Feature / 實驗性功能

This feature is under active development and may change significantly in v4.0. 此功能正在積極開發中,可能在 v4.0 中有重大變更。

Guide through the Behavior-Driven Development (BDD) workflow using Given-When-Then format.

引導行為驅動開發(BDD)流程,使用 Given-When-Then 格式。

Pre-Flight Checks | 前置檢查

Before executing BDD phases, the AI assistant MUST verify prerequisites. If a check fails, STOP and guide the user.

在執行 BDD 階段前,AI 助手必須驗證前置條件。如果檢查失敗,停止並引導使用者。

Phase Gate Matrix | 階段閘門矩陣

Target PhasePre-Flight CheckOn Failure
DISCOVERY1. Feature/behavior clearly identified→ Ask user to describe the desired behavior
2. If SDD project: spec exists→ Guide to /sdd
FORMULATION1. Discovery output exists (examples, edge cases)→ Guide back to DISCOVERY
2. At least one concrete example collected→ Collect examples first
AUTOMATION1. .feature file exists with scenarios→ Guide to FORMULATION
2. Scenarios follow Given-When-Then format→ Fix scenario format
LIVING DOCS1. Step definitions implemented→ Guide to AUTOMATION
2. All scenarios passing→ Fix failing scenarios first

Feature-Before-Step Enforcement | 功能檔優先強制

🔍 DISCOVERY: Collect examples → identify edge cases
   ↓ (only proceed with concrete examples)
📝 FORMULATION: Write .feature file → Given/When/Then
   ↓ (only proceed with valid Gherkin scenarios)
🤖 AUTOMATION: Implement step definitions → run
   ↓ (only proceed when all scenarios pass)
📚 LIVING DOCS: Maintain and share

Critical Rule: The AI MUST NOT write step definitions before .feature files with Gherkin scenarios exist. Discovery must produce concrete examples before formulation begins.

關鍵規則:AI 不得在 .feature 檔案存在前撰寫步驟定義。探索階段必須產出具體範例才能進入制定階段。


Methodology Integration | 方法論整合

When /bdd is invoked:

  1. Automatically activate BDD methodology if not already active
  2. Set current phase to DISCOVERY (exploring behavior)
  3. Track phase transitions as work progresses
  4. Show phase indicators in responses (🔍 Discovery, 📝 Formulation, 🤖 Automation, 📚 Living Docs)

當調用 /bdd 時:

  1. 自動啟用 BDD 方法論(如果尚未啟用)
  2. 將當前階段設為探索(探索行為)
  3. 追蹤階段轉換隨著工作進展
  4. 在回應中顯示階段指示器(🔍 探索、📝 制定、🤖 自動化、📚 活文件)

See methodology-system for full methodology tracking.

BDD Cycle | BDD 循環

┌───────────────────────────────────────────────────────┐
│                                                       │
│  ┌─────────┐   ┌───────────┐   ┌──────────┐   ┌────┐ │
│  │DISCOVERY│ ► │FORMULATION│ ► │AUTOMATION│ ► │DOCS│ │
│  └─────────┘   └───────────┘   └──────────┘   └────┘ │
│       ▲                                    │          │
│       └────────────────────────────────────┘          │
│                                                       │
└───────────────────────────────────────────────────────┘

Workflow | 工作流程

1. DISCOVERY - Explore Behavior | 探索行為

  • Discuss with stakeholders
  • Identify examples and edge cases
  • Understand the "why" behind features

2. FORMULATION - Write Scenarios | 制定場景

  • Write Gherkin scenarios (Given-When-Then)
  • Use ubiquitous language
  • Make scenarios concrete and specific

3. AUTOMATION - Implement Tests | 自動化測試

  • Implement step definitions
  • Write minimal code to pass
  • Follow the TDD cycle within automation

4. LIVING DOCUMENTATION - Maintain | 活文件維護

  • Keep scenarios up to date
  • Use as documentation
  • Share with stakeholders

Gherkin Format | Gherkin 格式

Feature: User Login
  As a registered user
  I want to log in to my account
  So that I can access my personal dashboard

  Scenario: Successful login with valid credentials
    Given I am on the login page
    And I have a registered account with email "user@example.com"
    When I enter my email "user@example.com"
    And I enter my password "correctpassword"
    And I click the login button
    Then I should be redirected to my dashboard
    And I should see a welcome message

  Scenario: Failed login with invalid password
    Given I am on the login page
    When I enter my email "user@example.com"
    And I enter my password "wrongpassword"
    And I click the login button
    Then I should see an error message "Invalid credentials"
    And I should remain on the login page

Three Amigos | 三劍客會議

BDD works best with collaboration:

RoleFocus角色關注點
BusinessWhat & Why業務什麼和為什麼
DevelopmentHow開發如何實現
TestingWhat if測試假設情況

Usage | 使用方式

  • /bdd - Start interactive BDD session
  • /bdd "user can reset password" - BDD for specific feature
  • /bdd login-feature.feature - Work with existing feature file

Phase Checklist | 階段檢查清單

Discovery Phase

  • Stakeholders identified
  • User stories discussed
  • Examples collected
  • Edge cases identified

Formulation Phase

  • Scenarios follow Given-When-Then
  • Language is ubiquitous (shared vocabulary)
  • Scenarios are specific and concrete
  • No implementation details in scenarios

Automation Phase

  • Step definitions implemented
  • Tests are executable
  • Code passes all scenarios
  • Refactoring complete

Living Documentation Phase

  • Scenarios are current
  • Documentation is accessible
  • Stakeholders can read and understand

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/bdd詢問要探索的行為,進入 🔍 DISCOVERY
/bdd "feature description"以指定功能為目標,進入 🔍 DISCOVERY
/bdd <feature-file>載入現有 .feature 檔案,判斷進入哪個階段

Interaction Script | 互動腳本

🔍 DISCOVERY Phase
  1. 與使用者討論功能行為
  2. 收集具體範例和邊界案例
  3. 以 Three Amigos 視角提問(Business / Dev / Testing)

🛑 STOP: 收集足夠範例後展示摘要,等待確認進入 FORMULATION

📝 FORMULATION Phase
  1. 將範例轉為 Gherkin 場景(Given-When-Then)
  2. 使用領域語言(ubiquitous language)
  3. 展示生成的 .feature 內容

Decision: 場景品質

  • IF 場景包含實作細節 → 自動抽離,改用業務語言
  • IF 場景過於模糊 → 要求更具體的範例

🛑 STOP: 展示 .feature 後等待使用者確認寫入

🤖 AUTOMATION Phase
  1. 為每個場景實作 step definitions
  2. 執行場景,確認結果
  3. 場景內部使用 TDD 循環實作

🛑 STOP: 所有場景通過後等待使用者確認

📚 LIVING DOCS Phase
  1. 確認所有場景是最新狀態
  2. 建議文件可分享給利害關係人

Stop Points | 停止點

PhaseStop Point等待內容
DISCOVERY範例收集完成後確認進入 FORMULATION
FORMULATION.feature 生成後確認寫入
AUTOMATION所有場景通過後確認進入 LIVING DOCS

Error Handling | 錯誤處理

Error ConditionAI Action
使用者要求跳過 DISCOVERY 直接寫場景提醒需要具體範例,但允許 override
.feature 語法無效自動修正 Gherkin 語法
Step definition 實作失敗報告哪個 step 失敗,嘗試修復,3 次後 STOP
無 BDD 測試框架(Cucumber 等)建議安裝,或改用 TDD 方式實作場景邏輯

Reference | 參考

Brainstorm Assistant | 腦力激盪助手

Structured ideation before specification writing. Transform vague ideas into actionable feature proposals through a persona-ensemble brainstorm.

在撰寫規格前進行結構化發想。透過 persona 集成式腦力激盪,將模糊構想轉化為可執行的功能提案。

Usage | 用法

/brainstorm [problem or feature idea]

Workflow | 工作流程

PRE-FLIGHT ──► FRAME ──► DIVERGE ──────────► CONVERGE ─────────► OUTPUT
  防錨定        定義問題    persona 集成+透鏡     多評審面板+硬角色反駁   輸出提案
PhaseGoalKey Techniques (v3) + BQS gate (v4)目標
PRE-FLIGHTPrevent AI anchoringUser writes 3 ideas first; no analogy seed; BQS Layer 0 intent (explore/exploit)防止錨定
FRAMEDefine problem clearly5 Whys, HMW, Stakeholder Map; D1 frame purity清楚定義問題
DIVERGEForce viewpoint diversityPersona ensemble + diversity lenses; BQS Layer 1 D1–D4, hard gate hides D5–D8逼出視角多樣性
CONVERGEBias-checked selectionMulti-critic panel + Devil's Advocate/Steelman; BQS Layer 2 D5–D8 on the Recommended Set (Agg. ≥ 3.5), D4 judge≠generator (two axes: independent context + declared model level)降偏誤選擇
OUTPUTActionable reportBrainstorm Report + Seeds + Contested Zone + Layer 3 Judgment Override可執行的報告

BQS v1 (XSPEC-296): v4 layers a four-layer × timeline quality contract on v3. Full oracles and structural rules are in the skill — see Brainstorm Assistant Skill.

BQS v1(XSPEC-296): v4 在 v3 上疊加四層 × 時間軸品質契約。完整 oracle 與結構規則見 skill:Brainstorm Assistant Skill。

Techniques | 技法

TechniqueBest For適用場景
Persona ensembleForced viewpoint diversity (v3 core)強制視角多樣性(v3 核心)
Diversity lensesAnalogical / reversal / morphological突破顯而易見區
Multi-critic panelBias-reduced scoring (v3 core)降偏誤評分(v3 核心)
Devil's Advocate + SteelmanHard-role rebuttal硬角色反駁
5 Whys / HMW / SCAMPER / Six HatsClassic framing & divergence經典框定與發散

Examples | 範例

/brainstorm                                          # Start interactive session
/brainstorm "user retention"                         # Brainstorm around a topic
/brainstorm --enhanced "user retention"              # Parallel persona ensemble (if host supports it)
/brainstorm --personas "designer,economist,skeptic"  # Custom personas
/brainstorm --lens analogical "onboarding"           # Force the analogical lens
/brainstorm --quick "reduce checkout friction"       # Fast 3-idea mode

Output Format | 輸出格式

# Brainstorm Report: [Topic]

## Problem Statement
[Refined problem from FRAME phase]

## Recommendations (Agg. Score ≥ 3.5 — uncapped)
1. **[Idea]** — Agg. X.X ✓ Passed rebuttal — Persona: [..] — [Why recommended]

## Diversity Note
[How many distinct personas/lenses the surviving ideas span]

## Next Steps
- [ ] Proceed to `/requirement` with top idea
- [ ] Proceed to `/sdd` if requirements are clear

Next Steps | 後續步驟

After brainstorming, the typical workflow is:

  1. /brainstorm - Structured ideation (this command)
  2. /requirement - Write user stories and requirements
  3. /sdd - Create specification documents
  4. /derive-all or /tdd - Implement with test protection

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/brainstorm啟動 PRE-FLIGHT,請使用者先寫 問題+3 想法+反向排除
/brainstorm "topic"以指定主題啟動 PRE-FLIGHT,再進入 FRAME
/brainstorm --personas "a,b,c"以自訂 persona 組進入 DIVERGE
/brainstorm --lens <name>以指定多樣性透鏡為主進入 DIVERGE
/brainstorm --enhanced若宿主支援子代理則平行跑 persona/評審,否則靜默退回 baseline;此模式滿足 BQS D4 的座位軸(獨立 context),pass 另需宣告模型層級(心智軸,見 skill D4)
/brainstorm --intent exploit以 exploit 意圖啟動(BQS Layer 0),D2 低覆蓋不扣分

Interaction Script | 互動腳本

PRE-FLIGHT Phase
  1. 請使用者先寫 問題(一句)+3 個初始想法+最不想要的解法類型
  2. 拒絕「像 X 但給 Y」種子,改寫為底層問題
  3. BQS Layer 0:宣告本次 explore/exploit 配比與賭注類型(未宣告預設偏 explore)

🛑 STOP: 收到三項輸入前不生成任何想法(--skip-preflight 例外,顯示錨定警告)

FRAME Phase
  1. 釐清問題陳述(5 Whys 找根因)
  2. 重構為 HMW 問題;識別利害關係人
  3. BQS D1 框架純度:問題不得內嵌特定方案或「像 X 給 Y」,須到根因

🛑 STOP: 問題定義後等待使用者確認

DIVERGE Phase (BQS Layer 1 — D1–D4 leading, visible)
  1. 逐一以預設 persona(領域專家/懷疑者/跨域類比者/成本約束者/使用者代言)思維鏈生成想法
  2. 分支隔離:生成各 persona 時不互相預覽,全部產完才一起呈現
  3. 至少套用一個多樣性透鏡(類比/假設反轉/形態矩陣)
  4. 以多樣性(覆蓋的 persona/透鏡數,D2/D3)而非數量為繼續門檻
  5. 硬序列閘:D5–D8 在最後一個 persona 產完前不得揭示或評分;CONVERGE critic 不得提前呼叫
  6. 模型層級(發散側):以 Standard 或更高層級執行——依 core/model-selection.md 的 MS-004/Criterion 2(引用,不複述;不是「最高層級」)
CONVERGE Phase (BQS Layer 2 — D5–D8 on the Recommended Set only)
  1. 以 3 個獨立評審(工程可行性/使用者影響/策略一致)各自評分後聚合;評審提示以「目標+約束」表達(判準,不是步驟清單——理由見 skill 引用的 core/model-selection.md MS-009),加權公式與逐準則指南為參考格式
  2. 對推薦集(Agg. Score ≥ 3.5,不限筆數)跑硬角色 Devil's Advocate(論證會失敗)+ Steelman;使用者以 (a)修改/(b)反駁/(c)移除 回應。D4 判官≠產生者,兩軸:(1) 評審在獨立 context(--enhanced)執行,且 (2) 宣告模型層級(core/model-selection.md 的廠商中立標籤;指名具體廠商模型即違規)——缺任一軸標 [degraded] 不得 pass
  3. 僅對推薦集套用 D5 接地(外部事實需 file:line/來源、跨級地板;假說免接地)、D6 淨值(解誰問題/真有嗎/不做代價+掛 lagging 欄)、D7 二態證偽(「需先做 X」轉 next-step、不算 fail)、D8 next-step 裁決——四者為判準、不限順序
  4. Meta 停止規則:維度全綠且再跑一輪推薦集集合成員不變→停;硬上限 2 輪

🛑 STOP: 展示 Brainstorm Report(含 Seeds/爭議區/Judgment Override)後等待使用者決定下一步

Stop Points | 停止點

Stop Point等待內容
PRE-FLIGHT 提交前收到使用者三項輸入
問題定義後確認問題正確
反駁輪每個反對理由使用者 (a)/(b)/(c) 回應
報告展示後決定進入 /requirement 或 /sdd

Error Handling | 錯誤處理

Error ConditionAI Action
主題太廣泛引導縮小範圍
使用「像 X 但給 Y」種子改寫為底層問題再繼續(反種子 guardrail)
指定的 persona/透鏡不存在列出可用選項供選擇
--enhanced 但宿主不支援子代理靜默退回 baseline,照常進行
推薦集全來自同一 persona/透鏡標示並在輸出前再跑一個透鏡
baseline 單 context 跑評審(無獨立 context)BQS D4 標 [degraded],不得標 pass
評審未宣告模型層級(或以具體廠商模型名宣告)BQS D4 標 [degraded] 不得 pass;模型名改為 core/model-selection.md 的層級標籤
外部事實宣稱無 file:line/來源D5 接地 fail,要求補來源或改標 [假說]

References | 參考

Changelog Assistant | 變更日誌助手

Generate and maintain CHANGELOG.md entries following the Keep a Changelog format.

根據 Keep a Changelog 格式產生和維護 CHANGELOG.md 條目。

Usage | 用法

/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 | 變更分類

CategoryWhen to Use使用時機Commit Types
AddedNew features新功能feat
ChangedModifications to existing features修改既有功能perf, BREAKING CHANGE
DeprecatedFeatures to be removed即將移除的功能--
RemovedRemoved features已移除的功能BREAKING CHANGE
FixedBug fixes錯誤修復fix
SecuritySecurity patches安全性修補security

Entry Format | 條目格式

## [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 標記破壞性變更

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/changelog分析 git log 自上次 release 以來的 commits,生成 changelog 條目

Interaction Script | 互動腳本

  1. 找到最近的 git tag(上次 release)
  2. 讀取從上次 tag 至今的所有 commits
  3. 依類型分類(Added / Changed / Fixed / Security 等)
  4. 轉寫為使用者導向的描述(非開發者語言)
  5. 展示生成的 changelog 條目

🛑 STOP: 展示條目後等待使用者確認更新 CHANGELOG.md

Stop Points | 停止點

Stop Point等待內容
Changelog 條目展示後確認內容正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
無 git tag(首次 release)分析所有 commits
CHANGELOG.md 不存在建立新檔案
Commit message 格式不規範盡力分類,標記 [Manual Review]

References | 參考

Check Standards | 檢查標準

Verify the adoption status of Universal Development Standards in the current project.

驗證當前專案的 Universal Development Standards 採用狀態。

Quick Start | 快速開始

# Basic check (with interactive mode for issues)
uds check

# Compact summary for quick status
uds check --summary

# Check without network access
uds check --offline

# Restore missing or modified files
uds check --restore

Output Modes | 輸出模式

Summary Mode (--summary) | 摘要模式

Shows compact status for quick overview:

顯示精簡狀態供快速瀏覽:

UDS Status Summary
──────────────────────────────────────────────────
  Version: 3.5.1-beta.16 → 3.5.1-beta.18 ⚠
  Level: 2 - Professional (專業)
  Files: 12 ✓
  Skills: Claude Code ✓ | OpenCode ○
  Commands: OpenCode ✓
──────────────────────────────────────────────────

Full Mode (Default) | 完整模式

Shows detailed information including:

  • Adoption status (level, version, install date)
  • File integrity (unchanged/modified/missing counts)
  • Skills integrity (if tracked in manifest)
  • Commands integrity (if tracked in manifest)
  • Integration blocks integrity
  • Reference sync status
  • AI tool integration files coverage
  • Coverage report

Interactive Mode | 互動模式

When issues are detected (modified/missing files), CLI automatically enters interactive mode:

當偵測到問題時,CLI 自動進入互動模式:

──────────────────────────────────────────────────
⚠ Modified: .standards/commit-message.ai.yaml

? What would you like to do?
❯ View diff
  Restore original
  Keep current (update hash)
  Skip

Available actions:

ActionDescription
View diffShow differences between current and original
Restore originalReplace with upstream version
Keep currentAccept modifications and update hash
SkipDo nothing for this file

For missing files:

ActionDescription
RestoreDownload and restore from upstream
Remove from trackingRemove from manifest
SkipDo nothing for this file

Options | 選項

OptionDescription說明
--summaryShow compact status summary顯示精簡狀態摘要
--offlineSkip npm registry check跳過 npm registry 檢查
--diffShow diff for modified files顯示修改檔案的差異
--restoreRestore all modified and missing files還原所有修改和遺失的檔案
--restore-missingRestore only missing files僅還原遺失的檔案
--migrateMigrate legacy manifest to hash-based tracking遷移舊版 manifest

Output Sections | 輸出區段

Adoption Status | 採用狀態

  • Adoption level (1-3)
  • Installation date
  • Installed version
  • Update availability

File Integrity | 檔案完整性

Shows status for each tracked file:

SymbolMeaning意義
✓ (green)Unchanged未變更
⚠ (yellow)Modified已修改
✗ (red)Missing遺失
? (gray)Exists but no hash存在但無 hash

Summary format: {unchanged} unchanged, {modified} modified, {missing} missing

Skills Integrity (v3.3.0+) | Skills 完整性

If skillHashes exist in manifest, checks:

  • File existence at expected paths
  • Hash comparison for modifications

Commands Integrity (v3.3.0+) | Commands 完整性

If commandHashes exist in manifest, checks:

  • File existence at expected paths
  • Hash comparison for modifications

Integration Blocks Integrity (v3.3.0+) | 整合區塊完整性

If integrationBlockHashes exist in manifest, checks:

  • UDS marker block presence
  • Block content hash (user customizations outside blocks are preserved)

Skills Status | Skills 狀態

Shows installation status for each configured AI tool:

Skills Status
  Claude Code:
    ✓ Skills installed:
      - User level: ~/.claude/skills/
        Version: 3.5.1
    ✓ Commands: 7 installed
      Path: .opencode/commands/

Status indicators:

  • ✓ installed (green) - Skills/Commands are installed
  • ○ not installed (gray) - Not installed

Coverage Summary | 覆蓋率摘要

Shows standards coverage:

  • Required standards for current level
  • Standards covered by Skills
  • Standards covered by reference documents

Status Indicators | 狀態指示

SymbolMeaning意義
✓ (green)All good一切正常
⚠ (yellow)Warning, action recommended警告,建議採取行動
✗ (red)Error, action required錯誤,需要採取行動
○ (gray)Not installed/configured未安裝/配置

Common Issues | 常見問題

"Standards not initialized"

  • Run /init to initialize standards

"Update available"

  • Run /update to get latest version

"Missing files"

  • Run /check --restore or /update to restore

"Modified files detected"

  • Run /check --diff to see changes
  • Run /check --restore to reset to original
  • Or use interactive mode to handle each file

"Skills not installed"

  • Run /update to install missing Skills
  • Or run /config skills to manage Skills

"Legacy manifest detected"

  • Run uds check --migrate to upgrade to hash-based tracking

Usage | 使用方式

/check                  # Full check with interactive mode
/check --summary        # Quick status overview
/check --offline        # Check without network access
/check --restore        # Restore modified/missing files
/check --diff           # Show file differences
/check --migrate        # Upgrade manifest format

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI ActionAI 行為
/check執行 uds check,偵測問題時進入互動修復模式Run full check, enter interactive mode on issues
/check --summary執行 uds check --summary,顯示精簡狀態Show compact status
/check --restore執行 uds check --restore,還原所有修改/遺失檔案Restore all files
/check --offline執行 uds check --offline,跳過 npm registry 檢查Skip network check
/check --migrate執行 uds check --migrate,升級 manifest 格式Migrate legacy manifest

Interaction Script | 互動腳本

  1. 執行 uds check 並解析輸出
  2. 展示狀態摘要(版本、層級、檔案、Skills、Commands)

Decision: 檢查結果

  • IF 全部正常 → 顯示綠色摘要,結束
  • IF 有修改/遺失檔案 → 進入互動修復迴圈
  1. 互動修復迴圈(每個問題檔案):

Decision: 檔案已修改

  • 使用者可選:View diff → Restore original → Keep current → Skip

Decision: 檔案遺失

  • 使用者可選:Restore → Remove from tracking → Skip

🛑 STOP: 每個問題檔案逐一詢問使用者處理方式

  1. 所有檔案處理完畢,顯示最終狀態

Stop Points | 停止點

Stop Point等待內容
每個問題檔案使用者選擇處理方式
restore 操作前確認還原(批次模式除外)

Error Handling | 錯誤處理

Error ConditionAI Action
標準未初始化提示執行 /init
npm registry 無法連線建議加 --offline 重試
manifest 格式過舊建議執行 --migrate
Skills 未安裝建議執行 /update 或 /config skills

Reference | 參考

  • CLI documentation: uds check --help
  • Init command: /init
  • Update command: /update
  • Config command: /config

Check-in Assistant | 簽入助手

Verify pre-commit quality gates before committing code to ensure codebase stability.

在提交程式碼前驗證品質關卡,確保程式碼庫的穩定性。

Usage | 用法

/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 | 品質關卡

GateCheck檢查項目
BuildCode compiles with zero errors編譯零錯誤
TestsAll existing tests pass (100%)所有測試通過
CoverageTest coverage not decreased覆蓋率未下降
AC CoverageAC-to-test coverage ≥ 80% (/ac-coverage)AC 覆蓋率 ≥ 80%
Code QualityFollows coding standards, no code smells符合編碼規範
SecurityNo hardcoded secrets or vulnerabilities無硬編碼密鑰
DocumentationAPI docs and CHANGELOG updated if needed文件已更新
WorkflowBranch 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.

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/checkin自動執行所有品質關卡檢查

Interaction Script | 互動腳本

  1. 執行 git status 確認有待提交的變更
  2. 依序檢查每個品質關卡:
    • Build → Tests → Coverage → Code Quality → Security → Documentation → Workflow
  3. 為每個關卡標記 ✅ PASS / ❌ FAIL
  4. 生成摘要報告

Decision: 測試指令偵測

  • IF 專案有 package.json → 使用 npm test
  • IF 專案有 pyproject.toml → 使用 pytest
  • IF 無法偵測 → 詢問使用者

Decision: 檢查結果

  • IF 全部通過 → 建議執行 /commit
  • IF 有 FAIL → 列出失敗項目和修復建議,不建議 commit

🛑 STOP: 報告展示後等待使用者決定(修復 or 強制 commit)

Stop Points | 停止點

Stop Point等待內容
品質報告展示後使用者決定修復或 commit

Error Handling | 錯誤處理

Error ConditionAI Action
無待提交變更告知無變更可檢查
測試指令執行失敗報告錯誤,建議檢查測試環境
lint 工具未安裝跳過該關卡,標記 ⚠️ SKIP

References | 參考

CI/CD Assistant | CI/CD 助手

Guide CI/CD pipeline design, configuration and optimization.

引導 CI/CD 管線設計、配置和優化。

Workflow | 工作流程

BUILD ──► TEST ──► ANALYZE ──► DEPLOY ──► VERIFY

Usage | 使用方式

  • /ci-cd - Start interactive pipeline design
  • /ci-cd github-actions - Design for specific platform
  • /ci-cd --optimize - Optimize existing pipeline
  • /ci-cd build - Focus on build stage

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/ci-cd偵測現有 CI 配置(.github/workflows/、.gitlab-ci.yml 等),展示狀態或開始設計
/ci-cd <platform>為指定平台設計管線
/ci-cd --optimize分析現有管線,提出優化建議
/ci-cd <stage>聚焦特定階段(build/test/deploy)

Interaction Script | 互動腳本

  1. 偵測專案技術棧和現有 CI 配置
  2. 依據需求設計或優化管線

Decision: 現有配置

  • IF 已有 CI 配置 → 分析現狀,建議優化
  • IF 無 CI 配置 → 引導從頭設計
  • IF --optimize → 直接進入優化分析
  1. 逐階段設計(BUILD→TEST→ANALYZE→DEPLOY→VERIFY)
  2. 展示完整管線配置

🛑 STOP: 配置展示後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
管線設計完成後確認配置正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
無法偵測 CI 平台列出支援的平台供選擇
現有配置語法錯誤報告錯誤位置,建議修正

Reference | 參考

Code Review Assistant | 程式碼審查助手

Perform systematic code review using standardized checklists and comment prefixes.

執行系統性的程式碼審查,使用標準化的檢查清單和評論前綴。

Workflow | 工作流程

  1. Identify changes - Get diff of files to review
  2. Apply checklist - Check each category systematically
  3. Generate report - Output findings with standard prefixes
  4. Summarize - Provide overall assessment

Review Categories | 審查類別

  1. Functionality - Does it work correctly?
  2. Design - Is the architecture appropriate?
  3. Quality - Is the code clean and maintainable?
  4. Readability - Is it easy to understand?
  5. Tests - Is there adequate test coverage?
  6. Security - Are there any vulnerabilities?
  7. Performance - Is it efficient?
  8. Error Handling - Are errors handled properly?

Comment Prefixes | 評論前綴

PrefixMeaningAction
BLOCKINGMust fix before mergeRequired
IMPORTANTShould fixRecommended
SUGGESTIONNice-to-haveOptional
QUESTIONNeed clarificationDiscuss
NOTEInformationalFYI

Usage | 使用方式

  • /code-review - Review all changes in current branch
  • /code-review src/auth.js - Review specific file
  • /code-review feature/login - Review specific branch

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/code-review執行 git diff 取得當前分支所有變更,開始審查
/code-review <file>僅審查指定檔案
/code-review <branch>審查指定分支相對於 main 的差異

Interaction Script | 互動腳本

  1. 取得變更內容(git diff / 讀取檔案)
  2. 逐一套用 8 個審查類別
  3. 為每個發現標記嚴重度前綴(BLOCKING / IMPORTANT / SUGGESTION / QUESTION / NOTE)
  4. 生成審查報告

Decision: 發現衝突

  • IF 多個發現互相矛盾(如效能 vs 可讀性) → 明確說明取捨,標記為 QUESTION 請使用者決定
  • ELSE → 依嚴重度排序呈現

🛑 STOP: 報告生成後展示結果,等待使用者決定處理方式

Stop Points | 停止點

Stop Point等待內容
審查報告展示後使用者決定是否修復 BLOCKING 項目

Error Handling | 錯誤處理

Error ConditionAI Action
無變更可審查告知無差異,建議先修改程式碼
檔案/分支不存在列出可用的檔案或分支
變更量過大(>500 行)建議分批審查,列出建議的分批方式

Reference | 參考

Commit Message Assistant | Commit Message 助手

Generate well-formatted commit messages following the Conventional Commits standard.

根據 staged 的變更,產生符合 Conventional Commits 格式的 commit message。

Pre-Flight Checks | 前置檢查

Before generating a commit, the AI assistant MUST run these checks:

在產生 commit 前,AI 助手必須執行以下檢查:

CheckCommandOn Failure
Staged changes existgit diff --cached --stat→ Guide user to git add
No merge conflictsgrep -r "<<<<<<< " --include="*.{js,ts,md,yaml}" .→ Resolve conflicts first
Tests pass (if feat/fix)cd cli && npm run test:unit (or project test cmd)→ Fix tests before committing
Spec reference (feat/fix)Check docs/specs/SPEC-*.md for active specs→ Suggest Refs: SPEC-XXX in footer
UDS upstream filesgit diff --cached --name-only | grep -E '^\.(standards|claude/skills)/'→ Suggest /audit --friction (advisory)

Spec Tracking Gate | Spec 追蹤閘門

For feat and fix type commits:

  1. Check: ls docs/specs/SPEC-*.md 2>/dev/null — any active specs?
  2. If specs exist: Suggest adding Refs: SPEC-XXX to commit footer
  3. If no specs and change is significant (>3 files or new API): Suggest creating a spec via /sdd
  4. Mode: This is advisory (non-blocking) — user can always proceed without a spec reference

對於 feat 和 fix 類型的提交:

  1. 檢查:是否有活躍的規格?
  2. 如果有規格:建議在 footer 加入 Refs: SPEC-XXX
  3. 如果沒有規格且變更顯著:建議透過 /sdd 建立規格
  4. 模式:這是建議性的(非阻斷)— 使用者可以不引用規格

Workflow | 工作流程

  1. Check status - Run git status and git diff --staged to understand changes
  2. Analyze changes - Determine the type (feat, fix, refactor, etc.) and scope
  3. Spec tracking assessment - Evaluate whether this change needs a spec (see below)
  4. Generate message - Create a commit message following the format:
    <type>(<scope>): <subject>
    
    <body>
    
    <footer>
    
  5. Confirm and commit - Ask user to confirm before executing git commit

Spec Tracking Assessment | Spec 追蹤評估

For feat/fix commits, evaluate whether a spec should be created or linked. Suggest a spec when: many files changed (>3), public API signatures modified, or significant new functionality. Skip for docs/style/chore/test types.

If a spec is linked, add Refs: SPEC-XXX to the commit footer. This is advisory — the user can always ignore.

Commit Types | 提交類型

TypeWhen to Use使用時機
featNew feature新功能
fixBug fix修復錯誤
refactorCode refactoring重構
docsDocumentation文件更新
styleFormatting格式調整
testTests測試相關
perfPerformance效能優化
choreMaintenance維護任務

Usage | 使用方式

  • /commit - Auto-analyze changes and suggest commit message
  • /commit fix login bug - Generate message based on provided description

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI ActionAI 行為
/commit執行 Pre-Flight Checks → 分析 staged 變更 → 產生 commit message → 等待確認Run checks, analyze, generate, confirm
/commit <description>以描述為基礎,結合 staged diff 產生 commit message → 等待確認Use description + diff to generate message

Interaction Script | 互動腳本

  1. 執行 git diff --cached --stat 確認有 staged 變更
  2. 執行 git status 和 git diff --staged 了解變更內容
  3. 判斷 commit 類型(feat/fix/refactor/docs/...)和範圍

Decision: Pre-Flight Check 結果

  • IF 無 staged 變更 → 引導使用者 git add,停止
  • IF 有合併衝突標記 → 提示先解決衝突,停止
  • IF 類型為 feat/fix → 執行測試 + Spec 追蹤評估
  1. 產生 commit message(subject + body + footer)
  2. 展示完整 message 供使用者確認

Decision: Spec 追蹤(僅 feat/fix)

  • IF 有活躍 spec → 建議在 footer 加 Refs: SPEC-XXX
  • IF 無 spec 且變更顯著(>3 檔案或新 API) → 建議 /sdd
  • 此為建議性(non-blocking),使用者可忽略

Decision: UDS 上游檔案偵測

  • IF staged 包含 .standards/ 或 .claude/skills/ → 顯示 ⚠️「偵測到 UDS 上游管理的檔案被修改,建議執行 /audit --friction 回報上游」
  • 此為建議性(non-blocking),使用者可忽略

🛑 STOP: 展示 commit message 後等待使用者確認或修改

  1. 使用者確認後執行 git commit

Stop Points | 停止點

Stop Point等待內容
Pre-Flight 失敗使用者修復問題後重新執行
Message 展示後確認 message 正確,或要求修改

Error Handling | 錯誤處理

Error ConditionAI Action
無 staged 變更顯示 git add 指引,不嘗試 commit
合併衝突存在提示解決衝突,列出衝突檔案
測試失敗(feat/fix)顯示失敗摘要,建議修復後再 commit
commit 執行失敗顯示 git 錯誤訊息,不重試

Reference | 參考

Config Standards | 設定標準

Configure Universal Development Standards settings for the current project.

配置當前專案的 Universal Development Standards 設定。

Interactive Mode (Default) | 互動模式(預設)

When invoked without a specific type, use AskUserQuestion to ask what to configure.

當不指定類型時,使用 AskUserQuestion 詢問要配置什麼。

Step 0: Show Current Status | 步驟 0:顯示目前狀態

First, run uds check --summary to show current installation status.

首先,執行 uds check --summary 顯示目前安裝狀態。

uds check --summary

This helps users understand what's currently configured before making changes.

這幫助用戶在修改前了解目前的配置。

Step 1: Ask Configuration Type | 步驟 1:詢問配置類型

Use AskUserQuestion with these options:

CategoryOptions
Basic OptionsFormat, Git Workflow, Merge Strategy, Commit Language, Test Levels
AI ToolsAdd or remove AI tool integrations
SkillsManage Skills installations (install/update/reinstall declined)
CommandsManage Commands installations
AdvancedAdoption Level, Content Mode
AllConfigure all options

Step 2: Execute Based on Selection | 步驟 2:根據選擇執行

If AI Tools selected:

uds configure --type ai_tools

If Skills selected:

uds configure --type skills

If Commands selected:

uds configure --type commands

If Adoption Level selected:

uds configure --type level

If Content Mode selected:

uds configure --type content_mode

Quick Mode | 快速模式

When invoked with a specific type, skip interactive questions:

/config ai_tools      # Directly configure AI tools
/config skills        # Directly manage Skills
/config commands      # Directly manage Commands
/config level         # Directly configure adoption level
/config content_mode  # Directly configure content mode

Non-Interactive Installation | 非互動式安裝

Use --ai-tool option to install Skills/Commands for a specific tool without prompts:

使用 --ai-tool 選項為特定工具安裝 Skills/Commands,無需提示:

# Install Skills for specific tool (project level, default)
uds configure --type skills --ai-tool opencode

# Install Skills for specific tool (user level)
uds configure --type skills --ai-tool opencode --skills-location user

# Install Skills for specific tool (project level, explicit)
uds configure --type skills --ai-tool claude-code --skills-location project

# Install Commands for specific tool
uds configure --type commands --ai-tool copilot

Skills location options | Skills 位置選項:

OptionPathDescription
project.claude/skills/, .opencode/skill/Project-specific (default)
user~/.claude/skills/, ~/.opencode/skill/Shared across all projects

Configuration Types | 設定類型

TypeDescription說明
ai_toolsAI tool integrationsAI 工具整合
skillsSkills installationsSkills 安裝管理
commandsCommands installationsCommands 安裝管理
levelAdoption level (1/2/3)採用等級
content_modeIntegration file content mode整合檔案內容模式
formatAI/Human documentation formatAI/人類文件格式
workflowGit workflow strategyGit 工作流程策略
merge_strategyMerge strategy合併策略
output_languageOutput language產出語言
test_levelsTest levels to include測試層級
methodologyDevelopment methodology (experimental, requires -E)開發方法論(實驗性)
allConfigure all options設定所有選項

Skills Configuration | Skills 配置

When selecting skills type, CLI shows:

  1. Current Status - Shows installed Skills for each AI tool
  2. Declined Status - Shows tools where user previously declined Skills
  3. Action Menu:
    • Install/Update Skills
    • Reinstall declined Skills
    • View status only
Current Skills status:
  ✓ Claude Code:
    - User: v3.5.1
  ○ OpenCode: Not installed
  ⊘ Copilot: Previously declined

? What would you like to do?
❯ Install/Update Skills
  Reinstall declined Skills
  View status only
  Cancel

Commands Configuration | Commands 配置

When selecting commands type, CLI shows:

  1. Current Status - Shows installed Commands for each supported tool
  2. Declined Status - Shows tools where user previously declined Commands
  3. Action Menu similar to Skills

Supported tools for Commands:

  • OpenCode (.opencode/commands/)
  • GitHub Copilot (.github/commands/)
  • Gemini CLI (.gemini/commands/)
  • Roo Code (.roo-code/commands/)

Content Mode Options | 內容模式選項

ModeDescription說明
standardSummary + task mapping, AI knows when to read which standard (Recommended)摘要 + 任務映射(推薦)
minimalOnly core rules embedded僅內嵌核心規則

Effects of Configuration Changes | 設定變更的影響

ConfigurationEffect影響
AI Tools (add)Generates new integration files產生新的整合檔案
AI Tools (remove)Deletes integration files刪除整合檔案
SkillsInstalls/updates Skills to configured paths安裝/更新 Skills
CommandsInstalls/updates Commands to configured paths安裝/更新 Commands
LevelUpdates standards, regenerates integrations更新標準,重新產生整合
Content ModeRegenerates all integration files重新產生所有整合檔案

Declined Features | 拒絕的功能

The CLI tracks declined Skills/Commands in manifest.declinedFeatures:

CLI 在 manifest.declinedFeatures 中追蹤拒絕的 Skills/Commands:

  • Previously declined tools won't appear in /update prompts
  • Use /config skills or /config commands to reinstall declined features
  • Select "Reinstall declined Skills/Commands" from the menu

之前拒絕的工具不會在 /update 提示中出現。使用 /config skills 或 /config commands 重新安裝。

Options Reference | 選項參考

OptionDescription說明
--type <type>Configuration type配置類型
--ai-tool <tool>Specific AI tool (non-interactive)特定 AI 工具(非互動式)
--skills-location <loc>Skills install location: project, userSkills 安裝位置
--yes, -ySkip confirmation prompt跳過確認提示
-E, --experimentalEnable experimental features啟用實驗性功能

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI ActionAI 行為
/config顯示目前狀態 → 詢問配置類型 → 執行Show status, ask type, execute
/config <type>直接執行指定類型配置(如 skills、ai_tools)Execute specific config type
/config --ai-tool <tool>非互動式為特定工具安裝 Skills/CommandsNon-interactive install for tool

Interaction Script | 互動腳本

  1. 執行 uds check --summary 顯示目前狀態

Decision: 有無指定 type

  • IF 指定了 type → 直接執行 uds configure --type <type>
  • IF 指定了 --ai-tool → 非互動式執行安裝
  • ELSE → 進入互動流程
  1. 詢問配置類型(AskUserQuestion):

    • Basic Options / AI Tools / Skills / Commands / Advanced / All
  2. 根據選擇執行對應 CLI 命令

Decision: Skills/Commands 配置

  • IF 選擇 Skills → 顯示安裝狀態 + 拒絕狀態 → 動作選單
  • IF 選擇 Commands → 同上流程

🛑 STOP: 顯示目前狀態後等待使用者選擇配置類型

Stop Points | 停止點

Stop Point等待內容
狀態顯示後使用者選擇要配置的類型
Skills/Commands 動作選單使用者選擇安裝/更新/重新安裝

Error Handling | 錯誤處理

Error ConditionAI Action
標準未初始化提示先執行 /init
無效的 config type列出可用類型供選擇
指定的 AI tool 不支援列出支援的工具清單
之前拒絕的 Skills/Commands提示可透過此命令重新安裝

Reference | 參考

  • CLI documentation: uds configure --help
  • Init command: /init
  • Check command: /check
  • Update command: /update

Test Coverage Assistant | 測試覆蓋率助手

Analyze test coverage across multiple dimensions and provide actionable recommendations.

多維度分析測試覆蓋率並提供可執行的建議。

Coverage Dimensions | 覆蓋率維度

DimensionWhat it Measures測量內容
LineLines executed執行的行數
BranchDecision paths決策路徑
FunctionFunctions called呼叫的函數
StatementStatements executed執行的陳述式

8-Dimension Framework | 八維度框架

  1. Code Coverage - Lines, branches, functions
  2. Requirement Coverage - All requirements tested
  3. Risk Coverage - High-risk areas tested
  4. Integration Coverage - Component interactions
  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 | 工作流程

  1. Run coverage tool - Generate coverage report
  2. Analyze gaps - Identify untested areas
  3. Prioritize - Rank by risk and importance
  4. Recommend tests - Suggest specific tests to add
  5. Track progress - Monitor coverage over time

Coverage Targets | 覆蓋率目標

LevelCoverageUse Case
Minimum60%Legacy code
Standard80%Most projects
High90%Critical systems
Critical95%+Safety-critical

Usage | 使用方式

  • /coverage - Run full coverage analysis
  • /coverage src/auth - Analyze specific module
  • /coverage --recommend - Get test recommendations

AC Coverage (Requirement-Level) | AC 覆蓋率(需求層級)

This command (/coverage) analyzes code-level coverage (line/branch/function). For requirement-level coverage — tracking which Acceptance Criteria have corresponding tests — use /ac-coverage.

本命令(/coverage)分析程式碼層級覆蓋率。若需需求層級覆蓋率 — 追蹤哪些 AC 有對應測試 — 請使用 /ac-coverage。

/coverage/ac-coverage
LevelCode (line/branch/function)Requirements (AC-to-test)
Question"How much code is tested?""Which AC have tests?"

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/coverage偵測測試框架,執行全專案覆蓋率分析
/coverage <path>僅分析指定模組/路徑
/coverage --recommend分析後重點輸出測試建議

Interaction Script | 互動腳本

  1. 偵測專案測試框架和覆蓋率工具
  2. 執行覆蓋率報告
  3. 解析結果,識別低覆蓋率區域
  4. 依風險和重要性排序
  5. 提出具體測試建議

Decision: 覆蓋率結果

  • IF 覆蓋率 ≥ 目標 → 展示摘要,標記 ✅
  • IF 覆蓋率 < 目標但 ≥ 60% → 展示差距,建議優先補測試的區域
  • IF 覆蓋率 < 60% → 警告,建議系統性補強計畫

🛑 STOP: 報告展示後等待使用者決定是否補寫測試

Stop Points | 停止點

Stop Point等待內容
覆蓋率報告展示後使用者決定是否補測試

Error Handling | 錯誤處理

Error ConditionAI Action
無測試框架詢問使用者選擇框架
覆蓋率工具執行失敗報告錯誤,建議手動檢查配置
指定路徑不存在列出可用路徑

Reference | 參考

Database Assistant | 資料庫助手

Guide database design, migration planning and query optimization.

引導資料庫設計、遷移規劃和查詢最佳化。

Workflow | 工作流程

PLAN ──► WRITE ──► TEST ──► DEPLOY ──► VERIFY

Usage | 使用方式

  • /database - Start interactive database design
  • /database schema - Review or design schema
  • /database --migration - Plan migration

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/database詢問任務類型(schema 設計 / 遷移規劃 / 查詢優化)
/database schema進入 schema 設計/審查模式
/database --migration進入遷移規劃模式

Interaction Script | 互動腳本

  1. 確認任務類型和目標
  2. 分析現有 schema 或遷移檔案

Decision: 任務類型

  • IF schema 設計 → 引導正規化、索引設計、關聯定義
  • IF 遷移規劃 → 評估風險、產生遷移腳本、規劃回滾
  • IF 查詢優化 → 分析慢查詢、建議索引
  1. 展示設計/計畫結果

🛑 STOP: 結果展示後等待使用者確認

🛑 STOP: 遷移腳本寫入前等待使用者確認

Stop Points | 停止點

Stop Point等待內容
設計/計畫展示後確認方案
遷移腳本生成後確認寫入

Error Handling | 錯誤處理

Error ConditionAI Action
無法偵測資料庫類型詢問使用者(PostgreSQL/MySQL/MongoDB 等)
遷移存在資料遺失風險明確警告,要求使用者確認

Reference | 參考

/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 | 輸出檔案

FileContent內容
features/SPEC-XXX.featureBDD Gherkin scenariosBDD Gherkin 場景
tests/SPEC-XXX.test.tsTDD test skeletonsTDD 測試骨架
DERIVATION-REPORT.mdSummary with statistics摘要與統計

Usage | 使用方式

CommandPurpose用途
/derive-all specs/SPEC-001.mdFull derivation from spec從規格完整推演
/derive-allInteractive — ask for spec file互動式 — 詢問規格檔案

Typical SDD Workflow | 典型 SDD 工作流程

/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

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/derive-all列出 status=Approved 的 spec 供選擇
/derive-all <spec-file>直接對指定 spec 執行完整推演

Interaction Script | 互動腳本

  1. 讀取並驗證 spec(status = Approved)
  2. 依序執行:/derive-bdd → /derive-tdd → 詢問是否需要 /derive-atdd

Decision: ATDD 推演

  • IF 使用者要求 → 執行 /derive-atdd
  • ELSE → 跳過 ATDD

🛑 STOP: BDD + TDD 推演完成後,詢問是否需要 ATDD 推演

  1. 生成 DERIVATION-REPORT.md 彙總所有輸出
  2. 展示報告摘要

🛑 STOP: 展示所有生成檔案清單後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
所有推演完成後確認寫入所有檔案

Error Handling | 錯誤處理

Error ConditionAI Action
Spec status ≠ Approved引導到 /sdd approve
子命令推演失敗報告哪個推演失敗,已成功的仍保留,詢問是否繼續

Reference | 參考

/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 | 輸出格式

# Acceptance Tests: SPEC-001

## AC-1: [Description]

| # | Given | When | Then | Status |
|---|-------|------|------|--------|
| 1 | [precondition] | [action] | [expected] | ⬜ |
| 2 | [precondition] | [action] | [expected] | ⬜ |

Usage | 使用方式

CommandPurpose用途
/derive-atdd specs/SPEC-001.mdDerive ATDD from specific spec從特定規格推演 ATDD
/derive-atddInteractive — ask for spec file互動式 — 詢問規格檔案

Note: BDD scenarios already serve as executable acceptance tests. /derive-atdd is for specialized manual testing workflows.

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/derive-atdd列出 status=Approved 的 spec 供選擇
/derive-atdd <spec-file>直接從指定 spec 推演 ATDD 表格

Interaction Script | 互動腳本

  1. 讀取 spec,擷取所有 AC
  2. 將每個 AC 映射為驗收測試表格(Given-When-Then 欄位)
  3. 為每個 AC 生成多筆測試資料(正向 + 反向 + 邊界值)
  4. 展示生成的 acceptance.md 內容

🛑 STOP: 展示表格後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
驗收測試表格生成後確認內容正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
AC 缺乏具體的輸入/輸出描述標記 [TODO: needs test data],繼續其餘 AC
Spec 無 AC告知並引導修改 spec

Reference | 參考

/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 | 輸出格式

Feature: [Feature Name]

  @SPEC-001 @AC-1
  Scenario: [AC-1 description]
    Given [context]
    When [action]
    Then [expected result]

Usage | 使用方式

CommandPurpose用途
/derive-bdd specs/SPEC-001.mdDerive BDD from specific spec從特定規格推演 BDD
/derive-bddInteractive — ask for spec file互動式 — 詢問規格檔案

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/derive-bdd列出 status=Approved 的 spec 供選擇
/derive-bdd <spec-file>直接從指定 spec 推演 BDD 場景

Interaction Script | 互動腳本

  1. 讀取 spec,擷取所有 AC
  2. 將每個 AC 映射為一個 Gherkin Scenario(1:1)
  3. 加入 @SPEC-XXX 和 @AC-N tags
  4. 展示生成的 .feature 內容

Decision: 輸出位置

  • IF 專案有 tests/features/ 目錄 → 輸出到該目錄
  • IF 專案有 features/ 目錄 → 輸出到該目錄
  • ELSE → 詢問使用者輸出位置

🛑 STOP: 展示 .feature 內容後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
.feature 生成後確認內容正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
AC 非 GWT 格式嘗試轉換並標記 [Derived],展示供確認
Spec 無 AC告知並引導修改 spec
生成的 Gherkin 語法無效自動修正語法,標記修正處

Reference | 參考

/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 | 輸出格式

describe('SPEC-001: [Feature Name]', () => {
  describe('AC-1: [AC description]', () => {
    it('should [expected behavior]', () => {
      // Arrange — [TODO]
      // Act — [TODO]
      // Assert — [TODO]
    });
  });
});

Usage | 使用方式

CommandPurpose用途
/derive-tdd specs/SPEC-001.mdDerive TDD from specific spec從特定規格推演 TDD
/derive-tddInteractive — ask for spec file互動式 — 詢問規格檔案

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/derive-tdd列出 status=Approved 的 spec 供選擇
/derive-tdd <spec-file>直接從指定 spec 推演 TDD 骨架

Interaction Script | 互動腳本

  1. 讀取 spec,擷取所有 AC
  2. 偵測專案語言和測試框架

Decision: 語言/框架偵測

  • IF 找到 vitest.config / jest.config → 使用對應框架
  • IF 找到 pytest.ini / pyproject.toml → 使用 pytest
  • IF 無法偵測 → 詢問使用者
  1. 將每個 AC 映射為 describe/it block(含 AAA 註解和 [TODO] 標記)
  2. 展示生成的測試檔案內容

🛑 STOP: 展示測試骨架後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
測試骨架生成後確認內容正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
AC 過於抽象無法轉為測試標記 [TODO: AC needs refinement],繼續其餘 AC
無法偵測語言/框架詢問使用者指定
Spec 無 AC告知並引導修改 spec

Reference | 參考

Derive Test Structures | 推演測試結構

Generate derived artifacts (BDD scenarios, TDD skeletons, ATDD tables) from approved SDD specifications.

從已批准的 SDD 規格生成衍生工件(BDD 場景、TDD 骨架、ATDD 表格)。

Usage | 用法

/derive [subcommand] <spec-file> [options]

Subcommands | 子命令

SubcommandDescriptionOutput
allFull derivation pipeline (BDD + TDD + IT + E2E + ATDD + Contracts)All formats
bddGenerate BDD scenarios only.feature
tddGenerate TDD skeletons only.test.*
itGenerate Integration test skeletons.it.test.*
e2eGenerate E2E test skeletons.e2e.test.*
atddGenerate ATDD test tables.md (Markdown tables)

Options | 選項

OptionDescriptionDefault
--langTarget language (ts, python, etc.)Detected or ts
--frameworkTest framework (vitest, pytest, etc.)Detected or vitest
--output-dirOutput directory./generated
--dry-runPreview output without writingfalse

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 | 範例

# Full derivation pipeline (BDD + TDD + IT + E2E + ATDD + Contracts)
/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 Integration test skeletons
/derive it specs/SPEC-001.md

# Derive E2E test skeletons
/derive e2e specs/SPEC-001.md

# Derive ATDD tables for manual testing
/derive atdd specs/SPEC-001.md

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/derive列出 docs/specs/ 中 status=Approved 的 spec,問使用者選擇 spec 和子命令
/derive <subcommand> <spec-file>直接對指定 spec 執行指定子命令
/derive <subcommand>執行指定子命令,列出可用 spec 供選擇
/derive <spec-file>對指定 spec 執行 all(預設子命令)

Interaction Script | 互動腳本

  1. 讀取 spec 檔案,驗證 status = Approved
  2. 擷取所有 AC,確認使用 GWT 格式

Decision: AC 格式

  • IF AC 使用 GWT 格式 → 直接推演
  • IF AC 不是 GWT 格式 → 嘗試轉換,標記 [Derived],展示轉換結果
  • IF AC 無法轉換 → 🛑 STOP,請使用者先修改 spec 中的 AC 格式

🛑 STOP: AC 格式轉換後展示結果,等待使用者確認轉換正確再繼續

  1. 依子命令分派到 /derive-bdd、/derive-tdd、/derive-it、/derive-e2e、/derive-atdd
  2. 驗證 1:1 對應(每個 AC 恰好一個測試/場景)
  3. 展示推演摘要

🛑 STOP: 展示生成的測試工件後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
AC 格式轉換後確認轉換結果
測試工件生成後確認寫入檔案

Error Handling | 錯誤處理

Error ConditionAI Action
Spec status ≠ Approved告知當前 status,引導到 /sdd approve
Spec 檔案不存在列出可用 spec,或引導到 /sdd create
AC 數量為 0告知 spec 無 AC,引導修改 spec
1:1 對應驗證失敗列出不對應項目,停止並報告

References | 參考

Development Workflow Guide | 開發工作流程指南

Map your current development phase to UDS commands. Get guidance on which tools to use at each stage.

將你目前的開發階段對應到 UDS 指令。了解在每個階段應該使用哪些工具。

Context-Aware Start | 情境感知啟動

When /dev-workflow is invoked, the AI assistant MUST first check the project's workflow state:

當調用 /dev-workflow 時,AI 助手必須先檢查專案的工作流程狀態:

Step 1: Check Active Workflows | 檢查進行中的工作流程

ls .workflow-state/*.yaml .workflow-state/*.json 2>/dev/null

If active workflows found | 如果有進行中的工作流程:

  1. Display active workflow summary (name, phase, progress)
  2. Suggest resuming: "You have an active {workflow} at phase {phase}. Resume with /{command}?"
  3. Show the appropriate next command based on current phase

Phase → Next Command Mapping | 階段 → 下一步指令對應:

WorkflowCurrent PhaseSuggested Next Command
SDDdiscuss/sdd create
SDDcreate/sdd review
SDDreview/sdd approve
SDDapprove/sdd implement
SDDimplement/sdd verify
TDDredWrite failing test, then run tests
TDDgreenWrite minimal code to pass
TDDrefactorClean up, then /tdd for next cycle
BDDdiscovery/bdd to formulate scenarios
BDDformulationWrite .feature file
BDDautomationImplement step definitions

If no active workflows | 如果沒有進行中的工作流程:

Proceed to show the standard phase overview below.

Step 2: Check for Active Specs | 檢查活躍規格

ls docs/specs/SPEC-*.md 2>/dev/null

If active specs exist, highlight them and suggest the appropriate workflow phase.


Usage | 用法

/dev-workflow                    # Show full phase overview
/dev-workflow planning           # Phase I: Planning & Design
/dev-workflow testing            # Phase II: Test-Driven Development
/dev-workflow implementation     # Phase III: Implementation
/dev-workflow quality            # Phase IV: Quality Gates
/dev-workflow release            # Phase V: Release & Commit
/dev-workflow docs               # Phase VI: Documentation
/dev-workflow standards          # Phase VII: Tools & Standards
/dev-workflow advanced           # Phase VIII: Advanced Analysis
/dev-workflow new-feature        # Scenario: New feature workflow
/dev-workflow bug-fix            # Scenario: Bug fix workflow
/dev-workflow refactoring        # Scenario: Refactoring workflow

Quick Reference | 快速對照表

PhaseUDS Commands用途
I. Planning/brainstorm /requirement /sdd /reverse /api-design /database需求、規格、API/DB 設計
II. Testing/bdd /atdd /tdd /coverage /derive /ac-coverage先寫測試再寫程式
III. Implementation/refactor /reverse /migrate /durable撰寫、改善與遷移程式碼
IV. Quality/checkin /code-review /security /scan /incident品質、安全、事故回應
V. Release/commit /changelog /release /pr /ci-cd版本、提交、PR、CI/CD
VI. Docs/docs /docgen文件與專案結構
VII. Standards/discover /guide /metrics /audit參考指南、指標、審計
VIII. Advanced/methodology跨方法論工作流程

Common Scenarios | 常見場景

New Feature | 新功能

/brainstorm → /requirement → /sdd → /derive → /tdd → /checkin → /commit

Bug Fix | 修復錯誤

/discover → /reverse → /tdd → /checkin → /commit

Refactoring | 重構

/discover → /reverse → /coverage → /refactor → /checkin → /commit

Security Review | 安全審查

/scan → /security → /checkin → /commit

API Design | API 設計

/brainstorm → /api-design → /sdd → /derive → /tdd → /pr

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/dev-workflow先檢查 .workflow-state/,有活躍工作流程則顯示狀態,否則展示全階段總覽
/dev-workflow <phase>展示指定階段的詳細指令和說明
/dev-workflow <scenario>展示指定場景的推薦工作流程(new-feature / bug-fix / refactoring)

Interaction Script | 互動腳本

  1. 檢查 .workflow-state/ 和 docs/specs/ 的活躍狀態
  2. 依據結果決定展示內容

Decision: 活躍工作流程

  • IF 有進行中的 workflow → 顯示狀態摘要,建議 resume 命令
  • IF 有活躍 spec → 提示 spec 進度,建議下一步
  • ELSE → 展示完整階段總覽或指定內容

Decision: 場景模式

  • IF 指定場景(new-feature / bug-fix / refactoring) → 展示該場景的推薦命令序列
  • ELSE → 展示總覽表

Stop Points | 停止點

此命令為純查詢/導引,無需停止點。

Error Handling | 錯誤處理

Error ConditionAI Action
指定的 phase/scenario 不存在列出可用的 phase 和 scenario
.workflow-state/ 目錄不存在跳過活躍工作流程檢查,直接展示總覽

References | 參考

Project Discovery | 專案現況評估

Phase 0 assessment before adding features to existing codebases. Evaluate project health, architecture, and risks.

在既有程式碼庫新增功能前的 Phase 0 評估。評估專案健康度、架構與風險。

Usage | 用法

/discover [feature area]

Assessment Dimensions | 評估維度

DimensionWhat to Check檢查項目
ArchitectureModule structure, dependency graph, entry points模組結構、相依圖、進入點
DependenciesOutdated packages, known vulnerabilities, license risks過時套件、已知漏洞、授權風險
Test CoverageExisting test suite, coverage gaps, test quality現有測試、覆蓋率缺口、測試品質
Securitynpm audit findings, hardcoded secrets, exposed endpoints安全稽核、硬編碼密鑰、暴露端點
Technical DebtTODOs, code duplication, complexity hotspotsTODO 標記、程式碼重複、複雜度熱點

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 | 範例

/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

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/discover執行全專案健康評估(所有 5 個維度)
/discover <area>聚焦評估指定功能區域的相關模組

Interaction Script | 互動腳本

  1. 掃描專案結構(package.json、目錄結構、配置檔)
  2. 逐維度分析(Architecture → Dependencies → Test Coverage → Security → Technical Debt)
  3. 計算各維度分數和整體分數
  4. 生成健康報告

Decision: 整體評估

  • IF 有 Critical 級問題 → 判定 NO-GO,列出必須修復項目
  • IF 有 Warning 級問題 → 判定 CONDITIONAL,列出建議修復項目
  • IF 全部 Good → 判定 GO,建議進入下一步

🛑 STOP: 報告展示後等待使用者決定(GO / NO-GO / CONDITIONAL)

Stop Points | 停止點

Stop Point等待內容
健康報告展示後使用者決定是否繼續開發

Error Handling | 錯誤處理

Error ConditionAI Action
無 package.json 或專案配置仍執行可用的維度分析,標記不可用的維度為 N/A
指定的功能區域不存在列出可用的模組/目錄供選擇
npm audit 無法執行跳過相依安全檢查,標記為 SKIP

References | 參考

Documentation Generator | 文件產生器

Generate usage documentation (cheatsheets, references, guides) from project source files.

從專案原始檔案產生使用文件(速查表、參考手冊、使用指南)。

Usage | 用法

/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 | 輸出類型

TypeDescription說明
cheatsheetQuick reference card with commands and shortcuts速查表,列出命令與快捷方式
referenceComprehensive feature reference with all options完整功能參考手冊含所有選項
usage-guideStep-by-step usage guide for new users新手入門的逐步使用指南

Examples | 範例

/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 | 設定檔格式

# .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]

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/docgen尋找預設配置檔 .usage-docs.yaml,找到則使用,否則詢問
/docgen <config>使用指定配置檔
/docgen --format <type>僅生成指定格式(cheatsheet / reference / usage-guide)

Interaction Script | 互動腳本

  1. 載入配置檔,解析來源和輸出設定
  2. 掃描來源檔案,擷取描述、選項、範例
  3. 依配置格式生成文件
  4. 展示生成的檔案清單和預覽

🛑 STOP: 展示生成結果後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
文件生成後確認內容正確並寫入

Error Handling | 錯誤處理

Error ConditionAI Action
配置檔不存在建議建立 .usage-docs.yaml,提供模板
來源目錄為空告知無內容可擷取,列出已掃描的路徑
輸出目錄不存在自動建立目錄

References | 參考

/docs Command | /docs 命令

Manage, write, and generate project documentation.

管理、撰寫和生成專案文件。

Usage | 用法

/docs [subcommand] [options]

Subcommands | 子命令

SubcommandDescription說明
impactAnalyze documentation impact of recent code changes分析程式碼變更對文件的影響
translateCheck translation status or translate documents檢查翻譯狀態或翻譯文件
generateGenerate documentation artifacts (cheatsheets, reference)產生文件工件
readmeAudit and update README.md審計並更新 README.md
apiGenerate API documentation from code從程式碼產生 API 文件
structureCheck documentation folder structure檢查文件目錄結構
(none)Show documentation guide/status展示文件狀態總覽

Impact Options

Used with /docs impact:

OptionDescription
--stagedOnly analyze staged (git add) changes
--commit <ref>Analyze changes from a specific commit or range
(default)Analyze all uncommitted changes

Translate Options

Used with /docs translate:

OptionDescription
<file>Translate a specific source file
--lang <lang>Target language (zh-TW, zh-CN)
--checkCheck translation sync status only (no changes)
--allTranslate all outdated files
(default)Show translation status summary

Generate Options

Used with /docs generate:

OptionDescription
--lang <lang>Language (en, zh-TW, zh-CN)
--cheatsheetGenerate cheatsheet only
--referenceGenerate feature reference only
--checkCheck if docs are out of sync

Examples | 範例

# Analyze doc impact of current changes
/docs impact

# Analyze doc impact of staged changes only
/docs impact --staged

# Check translation sync status
/docs translate --check

# Translate a specific file to zh-TW
/docs translate docs/CLI-INIT-OPTIONS.md --lang zh-TW

# Translate all outdated files
/docs translate --all --lang zh-TW

# Generate all docs
/docs generate

# Update README
/docs readme

# Check doc structure
/docs structure

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/docs展示專案文件狀態總覽(哪些文件存在、是否過時)
/docs impact分析未提交的程式碼變更對文件的影響,列出受影響文件和建議命令
/docs impact --staged只分析已 stage 的變更
/docs impact --commit <ref>分析指定 commit 的變更影響
/docs translate展示翻譯狀態摘要(哪些翻譯過時、缺失)
/docs translate <file>翻譯指定文件,根據 output_language 設定和 locales/ 結構
/docs translate --check只檢查翻譯狀態,不做修改(等同 check-translation-sync.sh)
/docs translate --all翻譯所有過時的檔案
/docs generate生成文件工件(速查表、參考手冊)
/docs generate --lang <lang>生成指定語言的文件
/docs readme審計並更新 README.md
/docs api從程式碼生成 API 文件
/docs structure檢查文件目錄結構是否符合規範

Interaction Script | 互動腳本

Decision: 子命令分派

  • IF impact → 執行文件影響分析(見下方 Impact 流程)
  • IF translate → 執行翻譯流程(見下方 Translate 流程)
  • IF generate → 執行 /docgen 的生成流程
  • IF readme → 分析 README 完整性,建議更新
  • IF api → 掃描程式碼,生成 API 文件
  • IF structure → 檢查目錄結構,報告缺失
  • IF 無子命令 → 展示文件狀態總覽
Impact 流程
  1. 取得變更清單(git diff 或 git diff --staged 或 git diff <ref>)
  2. 對每個變更的檔案,掃描哪些文件引用了它
  3. 輸出影響報告,格式:
📋 Documentation Impact Analysis
─────────────────────────────────
Modified: cli/src/commands/init.js, cli/src/prompts/init.js

Affected documents:
  README.md — describes CLI init options
    → /docs readme
  docs/CLI-INIT-OPTIONS.md — references promptOutputLanguage()
    → manual update or /docs generate
  locales/zh-TW/docs/CLI-INIT-OPTIONS.md — translation outdated
    → /docs translate docs/CLI-INIT-OPTIONS.md --lang zh-TW

No impact: ARCHITECTURE.md, API.md (not referenced)

🛑 STOP: 展示報告後等待使用者選擇要執行哪些更新

Translate 流程
  1. IF --check 或無參數 → 掃描 locales/ 目錄,比對源檔版本
  2. 輸出翻譯狀態表:
📋 Translation Status (zh-TW)
─────────────────────────────
✅ current     core/commit-message-guide.md (v1.3.0)
⚠️  outdated   docs/CLI-INIT-OPTIONS.md (source v1.5.0, translation v1.4.0)
❌ missing     core/documentation-writing-standards.md (new sections added)
  1. IF 指定 <file> 或 --all → 讀取源檔和現有翻譯,產生更新的翻譯內容
  2. 根據 output_language 設定決定翻譯語言和風格

🛑 STOP: 展示翻譯結果後等待使用者確認寫入

Stop Points | 停止點

Stop Point等待內容
impact 報告展示後選擇要執行哪些更新
translate 結果展示後確認翻譯內容寫入
generate/readme/api 結果展示後確認寫入

Error Handling | 錯誤處理

Error ConditionAI Action
子命令無效列出可用子命令
目標目錄不存在自動建立或詢問使用者
無程式碼可分析(api 子命令)告知並建議檢查路徑
無 git 歷史(impact 子命令)告知需要 git 初始化
locales/ 目錄不存在(translate 子命令)告知專案未設定翻譯結構
源檔未變更(translate 子命令)告知翻譯已是最新

References | 參考

Durable Execution Assistant | 持久執行助手

Guide workflow failure recovery with checkpoints, retries and rollback strategies.

引導工作流程故障恢復,包含檢查點、重試與回滾策略。

Workflow | 工作流程

DETECT ──► DIAGNOSE ──► RECOVER ──► VERIFY ──► CONTINUE

Usage | 使用方式

  • /durable - Start interactive failure recovery
  • /durable --checkpoint - Design checkpoint strategy
  • /durable --retry - Design retry policy
  • /durable --rollback - Plan rollback strategy
  • /durable <workflow> - Analyze specific workflow

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/durable詢問工作流程或失敗情境,進入 DETECT
/durable --checkpoint直接進入檢查點策略設計
/durable --retry直接進入重試策略設計
/durable --rollback直接進入回滾策略規劃
/durable <workflow>分析指定工作流程

Interaction Script | 互動腳本

DETECT / DIAGNOSE
  1. 分析工作流程結構和失敗點
  2. 識別需要持久化的狀態

Decision: 故障類型

  • IF 暫時性故障(網路、超時) → 建議重試策略(exponential backoff)
  • IF 資料不一致 → 建議檢查點 + 補償交易
  • IF 不可逆失敗 → 建議回滾策略

🛑 STOP: 診斷結果展示後等待使用者確認策略方向

RECOVER
  1. 設計選定的恢復策略
  2. 展示策略細節和程式碼建議

🛑 STOP: 策略設計後等待使用者確認

VERIFY
  1. 建議驗證步驟確認恢復成功

Stop Points | 停止點

PhaseStop Point等待內容
DIAGNOSE診斷結果後確認策略方向
RECOVER策略設計後確認實施

Error Handling | 錯誤處理

Error ConditionAI Action
無法識別工作流程模式詢問使用者描述工作流程步驟
多種故障類型並存逐一分析,建議組合策略

Reference | 參考

E2E Assistant | E2E 助手

[!WARNING] Experimental Feature / 實驗性功能

This feature is under active development and may change significantly in v4.0. 此功能正在積極開發中,可能在 v4.0 中有重大變更。

Generate E2E test skeletons from BDD .feature scenarios. Detects project framework, analyzes existing test patterns, and produces framework-specific skeletons with [TODO] markers.

從 BDD .feature 場景生成 E2E 測試骨架。偵測專案框架、分析既有測試模式,並產出框架適配的骨架與 [TODO] 標記。

Usage | 用法

/e2e <feature-file>            # 從 BDD 場景生成 E2E 骨架(預設模式)
/e2e <spec-file>               # 從 SDD 規格委派 /derive e2e
/e2e --analyze                 # 掃描所有 feature 的 E2E 覆蓋差距
/e2e --analyze <feature-file>  # 分析特定 feature 的 AC 適用性

Options | 選項

OptionDescription說明
<feature-file>Path to .feature file.feature 檔案路徑
<spec-file>Path to SPEC-XXX.md file (delegates to /derive e2e)SDD 規格路徑(委派)
--analyzeRun coverage gap analysis mode執行覆蓋差距分析模式

Workflow | 工作流程

Generation Mode (Default) | 生成模式

1. Parse .feature file → extract scenarios
2. Classify each scenario → e2e / integration / unit suitable
3. Detect E2E framework → Playwright / Cypress / Vitest
4. Analyze existing E2E patterns → imports, helpers, conventions
5. Generate framework-specific skeleton → with [TODO] markers
6. Show result → wait for user confirmation to write

Analysis Mode (--analyze) | 分析模式

1. Scan features directory → list all .feature files
2. Scan E2E tests directory → list all E2E test files
3. Compare coverage → identify missing E2E tests
4. Generate report → suggest /ac-coverage-assistant for details

Anti-Hallucination | 防幻覺

  • MUST read the actual .feature file before classifying — never guess scenario content
  • MUST detect framework from package.json or existing test files — never assume a framework
  • MUST use utility functions from cli/src/utils/e2e-analyzer.js and cli/src/utils/e2e-detector.js as reference for classification logic
  • MUST NOT fabricate test helpers or import paths that don't exist in the project

Examples | 範例

Generate E2E from feature file

/e2e tests/features/SPEC-AUTH-001-login.feature

Output:

📊 AC 適用性分析結果:
┌──────────────────────────────┬──────────────────┬───────────────────────────────┐
│ Scenario                     │ Category         │ Reason                        │
├──────────────────────────────┼──────────────────┼───────────────────────────────┤
│ Successful login             │ e2e-suitable     │ Multi-step user flow          │
│ Failed login                 │ e2e-suitable     │ UI interaction detected       │
│ Password validation          │ unit-suitable    │ Pure validation logic         │
└──────────────────────────────┴──────────────────┴───────────────────────────────┘

🔍 框架偵測:Playwright (auto-detected from package.json)
📁 既有模式:3 E2E tests found, using @playwright/test

✅ 已生成 E2E 骨架(2 scenarios, 1 skipped)

Analyze coverage gaps

/e2e --analyze

Output:

📊 E2E 覆蓋差距報告:
┌──────────────────────────────┬──────────┬───────────────────┐
│ Feature File                 │ E2E Test │ Status            │
├──────────────────────────────┼──────────┼───────────────────┤
│ login.feature                │ ✅       │ Covered           │
│ checkout.feature             │ ❌       │ Missing           │
│ registration.feature         │ ❌       │ Missing           │
└──────────────────────────────┴──────────┴───────────────────┘

覆蓋率:1/3 (33%)
建議:執行 /ac-coverage-assistant 取得 AC 層級追蹤。

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/e2e列出 tests/features/ 中的 .feature 檔案,詢問使用者選擇
/e2e <feature-file>直接進入生成模式,解析指定 .feature 檔案
/e2e <spec-file>偵測到 SPEC-XXX.md 格式,委派至 /derive e2e
/e2e --analyze進入分析模式,掃描覆蓋差距
/e2e --analyze <feature>分析指定 feature 的 AC 適用性

Interaction Script | 互動腳本

Phase 1: AC 適用性分析
  1. 讀取 .feature 檔案,解析所有 Scenario
  2. 使用分類邏輯(E2E/Integration/Unit keywords + step count)分類每個 Scenario
  3. 以表格展示分類結果

Decision: 無 E2E 適合的場景

  • IF 所有場景都非 e2e-suitable → 通知使用者,建議使用 /tdd 或 /bdd 替代
  • IF 部分適合 → 僅處理 e2e-suitable 場景,列出跳過的場景及原因

🛑 STOP: 展示分類結果後等待使用者確認繼續

Phase 2: 框架偵測與模式分析
  1. 偵測專案使用的 E2E 框架(package.json dependencies)
  2. 掃描既有 E2E 測試目錄,提取 import、helper、編碼慣例

Decision: 多框架偵測

  • IF 偵測到多個框架 → 列出選項,詢問使用者選擇
  • IF 未偵測到框架 → 詢問使用者指定,或預設使用 Vitest
Phase 3: 骨架生成
  1. 使用框架模板生成 E2E 測試骨架
  2. 包含 [TODO] 標記、traceability tags(@SPEC-XXX @AC-N)
  3. 包含 fixture/setup 引導(beforeAll/beforeEach)
  4. 展示生成的程式碼

🛑 STOP: 展示生成的骨架後等待使用者確認寫入

Phase 4: 完成與下一步
  1. 寫入檔案(經使用者確認)
  2. 建議下一步操作

Stop Points | 停止點

PhaseStop Point等待內容
AC 分析分類結果展示後確認繼續生成
骨架生成程式碼展示後確認寫入檔案

Error Handling | 錯誤處理

Error ConditionAI Action
.feature 檔案不存在列出目錄中可用的 .feature 檔案
.feature 無 Scenario通知使用者,建議先使用 /bdd 撰寫場景
輸入為 SPEC-XXX.md辨識後委派至 /derive e2e,說明原因
框架未偵測到詢問使用者選擇框架(Playwright/Cypress/Vitest)
既有 E2E 目錄不存在使用預設模板,不進行模式分析

Reference | 參考

/guide Command

Language: English | 繁體中文

The /guide command is the central entry point for accessing all Universal Development Standards reference materials and guidelines.

Usage

/guide [topic]

Available Topics

TopicDescriptionSource
gitGit workflow & branching strategiesskills/git-workflow-guide/
testingTesting pyramid & strategyskills/testing-guide/
errorsError code design standardsskills/error-code-guide/
loggingStructured logging standardsskills/logging-guide/
structureProject structure conventionsskills/project-structure-guide/
ai-archAI-friendly architectureskills/ai-friendly-architecture/
ai-collabAI collaboration & anti-hallucinationskills/ai-collaboration-standards/
ai-instructAI instruction file standardsskills/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.

Incident Response Assistant | 事故回應助手

Guide incident response, root cause analysis and post-mortem documentation.

引導事故回應、根因分析和事後檢討文件撰寫。

Workflow | 工作流程

DETECT ──► TRIAGE ──► MITIGATE ──► RESOLVE ──► POST-MORTEM

Usage | 使用方式

  • /incident - Start interactive incident response
  • /incident "API 500 errors" - Respond to specific incident
  • /incident --post-mortem - Write post-mortem for resolved incident
  • /incident --sev1 - Start SEV1 response protocol

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/incident詢問事故描述和嚴重程度,進入 DETECT
/incident "description"以描述為起點,進入 TRIAGE
/incident --post-mortem直接進入 POST-MORTEM 階段
/incident --sev1啟動 SEV1 緊急回應協議

Interaction Script | 互動腳本

DETECT / TRIAGE
  1. 收集事故症狀和影響範圍
  2. 評估嚴重程度(SEV1-4)

Decision: 嚴重程度

  • IF SEV1/SEV2 → 立即列出緊急行動清單,建議通知相關人員
  • IF SEV3/SEV4 → 按標準流程排查

🛑 STOP: 嚴重程度評估後等待使用者確認

MITIGATE
  1. 建議即時緩解措施
  2. 追蹤緩解狀態
RESOLVE
  1. 引導根因分析(5 Whys)
  2. 建議修復方案

🛑 STOP: 修復方案確認後等待使用者確認實施

POST-MORTEM
  1. 收集時間線、根因、影響
  2. 生成事後檢討文件

🛑 STOP: 文件生成後等待使用者確認寫入

Stop Points | 停止點

PhaseStop Point等待內容
TRIAGE嚴重程度評估後確認分級
RESOLVE修復方案提出後確認實施
POST-MORTEM文件生成後確認寫入

Error Handling | 錯誤處理

Error ConditionAI Action
無法判斷嚴重程度列出分級標準,請使用者選擇
缺乏足夠症狀資訊引導收集更多資訊(日誌、監控、錯誤訊息)

Reference | 參考

Initialize Standards | 初始化標準

Initialize Universal Development Standards in the current project.

在當前專案初始化 Universal Development Standards。

Interactive Mode (Default) | 互動模式(預設)

When invoked without --yes, use AskUserQuestion to gather user preferences before executing.

當不帶 --yes 執行時,使用 AskUserQuestion 詢問用戶偏好後再執行。

Step 1: Detect Project | 步驟 1:偵測專案

First, CLI automatically detects project characteristics:

  • Languages (JavaScript, TypeScript, Python, Go, etc.)
  • Frameworks (React, Vue, Express, etc.)
  • AI Tools (Claude Code, Cursor, Copilot, etc.)

首先,CLI 會自動偵測專案特性。

Step 2: Ask AI Tools Selection | 步驟 2:詢問 AI 工具選擇

Use AskUserQuestion with multiSelect to ask which AI tools to configure:

使用 AskUserQuestion(多選)詢問要配置哪些 AI 工具:

AI ToolIntegration FileSkills SupportCommands Support
Claude CodeCLAUDE.md✅❌
Cursor.cursorrules✅❌
Windsurf.windsurfrules✅❌
Cline.clinerules✅❌
GitHub Copilot.github/copilot-instructions.md✅✅
OpenCodeAGENTS.md✅✅
Gemini CLIGEMINI.md✅✅
CodexAGENTS.md✅❌
Antigravity.agents/AGENTS.md✅❌

Pre-select tools detected in the environment. Note: Codex and OpenCode share AGENTS.md.

預選環境中偵測到的工具。注意:Codex 和 OpenCode 共用 AGENTS.md。

Step 3: Ask Skills Installation | 步驟 3:詢問 Skills 安裝

For tools that support Skills, use Smart Grouping strategy based on tool count.

對於支援 Skills 的工具,根據工具數量使用智能分組策略。

IMPORTANT: AskUserQuestion has a 4-option limit. Use smart grouping to handle this.

重要:AskUserQuestion 最多只能有 4 個選項。 使用智能分組來處理。

Strategy A: 1-2 Tools → Combined Question | 策略 A:1-2 個工具 → 合併詢問

Example (Claude Code only):

Question: "Skills 要安裝到哪裡?"
Options:
1. Plugin Marketplace (建議) - 自動更新,易於管理
2. User Level (~/.claude/skills/) - 所有專案共用
3. Project Level (.claude/skills/) - 僅此專案
4. 跳過 - 不安裝 Skills

Example (Claude Code + OpenCode):

Question: "Skills 要安裝到哪裡?"
Options:
1. Plugin Marketplace + OpenCode Project Level (建議)
2. 全部 User Level - 所有專案共用
3. 全部 Project Level - 僅此專案
4. 跳過 - 不安裝 Skills
Strategy B: 3+ Tools → Two-Stage Question | 策略 B:3+ 個工具 → 兩階段詢問

Stage 1: Ask unified or individual

Question: "您選擇了 3 個以上的 AI 工具,Skills 安裝層級要如何設定?"
Options:
1. 統一層級 (建議) - 所有工具使用相同層級
2. 個別設定 - 為每個工具分別選擇層級
3. 跳過 - 不安裝 Skills

Stage 2a: If unified → ask level once

Question: "所有 Skills 要安裝到哪個層級?"
Options:
1. User Level - 所有專案共用
2. Project Level (建議) - 僅此專案

Note: Claude Code uses Plugin Marketplace by default; only other tools use selected level.

Stage 2b: If individual → per-tool questions Ask each tool separately (see Strategy A examples).

Step 4: Ask Commands Installation | 步驟 4:詢問 Commands 安裝

For tools that support Commands (OpenCode, Copilot, Gemini CLI), use Smart Grouping strategy.

對於支援 Commands 的工具,使用智能分組策略。

IMPORTANT: AskUserQuestion has a 4-option limit. Use smart grouping to handle this.

重要:AskUserQuestion 最多只能有 4 個選項。 使用智能分組來處理。

Strategy A: 1-2 Tools → Combined Question | 策略 A:1-2 個工具 → 合併詢問

Example (OpenCode only):

Question: "Commands 要安裝到哪裡?"
Options:
1. User Level (~/.config/opencode/command/) - 所有專案共用
2. Project Level (.opencode/command/) - 僅此專案 (建議)
3. 跳過 - 使用 Skills 即可

Example (OpenCode + Copilot):

Question: "Commands 要安裝到哪裡?"
Options:
1. 全部 User Level - 所有專案共用
2. 全部 Project Level (建議) - 僅此專案
3. 跳過 - 使用 Skills 即可
Strategy B: 3+ Tools → Two-Stage Question | 策略 B:3+ 個工具 → 兩階段詢問

Stage 1: Ask unified or individual

Question: "您選擇了多個支援 Commands 的 AI 工具,安裝層級要如何設定?"
Options:
1. 統一層級 (建議) - 所有工具使用相同層級
2. 個別設定 - 為每個工具分別選擇層級
3. 跳過 - 不安裝 Commands

Stage 2a: If unified → ask level once

Question: "所有 Commands 要安裝到哪個層級?"
Options:
1. User Level - 所有專案共用
2. Project Level (建議) - 僅此專案

Stage 2b: If individual → per-tool questions Ask each tool separately (see Strategy A examples).

Step 5: Ask Standards Scope | 步驟 5:詢問標準範圍

Use AskUserQuestion (only shown if Skills are installed):

使用 AskUserQuestion(僅在安裝 Skills 時顯示):

OptionDescription
Lean (Recommended)Reference docs only, Skills provide real-time task guidance
CompleteInstall all standard files, independent of Skills

Step 6: Ask Adoption Level | 步驟 6:詢問採用層級

Use AskUserQuestion:

使用 AskUserQuestion:

OptionDescription
Level 1: Starter6 core standards: commit, anti-hallucination, checkin, etc.
Level 2: Professional (Recommended)Adds testing, Git workflow, error handling - 12 total
Level 3: CompleteIncludes versioning, logging, SDD - all 16 standards

Step 7: Ask Standards Format | 步驟 7:詢問標準格式

Use AskUserQuestion:

OptionDescription
AI (Compact)Optimized for AI consumption (Recommended)
Human (Detailed)Readable format for humans
BothGenerate both formats

Step 8: Ask Standard Options | 步驟 8:詢問標準選項

Based on adoption level, ask for:

  • Git Workflow: github-flow, gitflow, trunk-based
  • Merge Strategy: squash, merge, rebase
  • Commit Language: english, traditional-chinese, bilingual
  • Test Levels: unit-testing, integration-testing, e2e-testing

Step 9: Ask Language Extensions | 步驟 9:詢問語言擴展

If languages detected, ask whether to include language-specific standards:

  • C# Style Guide
  • PHP Style Guide
  • etc.

Step 10: Ask Framework Extensions | 步驟 10:詢問框架擴展

If frameworks detected, ask whether to include framework-specific patterns:

  • Fat-Free Patterns
  • etc.

Step 11: Ask Locale | 步驟 11:詢問地區設定

Use AskUserQuestion:

OptionDescription
English (Default)English documentation
Traditional Chinese繁體中文文件

Step 12: Ask Content Mode | 步驟 12:詢問內容模式

Use AskUserQuestion for integration file content:

使用 AskUserQuestion 設定整合檔案內容:

OptionDescription
Standard (Recommended)Summary + task mapping, AI knows when to read which standard
MinimalFile references only, best with Skills

Step 13: Confirm and Execute | 步驟 13:確認並執行

Show configuration summary and confirm before executing.

After confirmation, CLI executes all installations in one operation:

  • Copies standards to .standards/
  • Generates integration files
  • Installs Skills (if selected)
  • Installs Commands (if selected)
  • Creates manifest.json

Quick Mode | 快速模式

When invoked with --yes or specific options, skip interactive questions:

/init --yes                    # Use all defaults
/init --level 2 --yes          # Specific level with defaults
/init --skills-location none   # No Skills installation
/init --content-mode standard  # Specific content mode

Options Reference | 選項參考

OptionDescription說明
--yes, -yNon-interactive mode非互動模式
--level NAdoption level (1, 2, or 3)採用層級
--skills-locationmarketplace, user, project, or noneSkills 位置
--content-modestandard, full, or minimal內容模式
--formatai, human, or both格式
-E, --experimentalEnable experimental features (methodology)啟用實驗性功能

See uds init --help for all options.

Adoption Levels | 採用層級

LevelNameStandards CountDescription說明
1Starter6Core standards for small projects核心標準(小型專案)
2Professional12Adds testing, Git workflow, error handling團隊專業品質標準
3Complete16All 16 standards including SDD完整的 16 項標準

What Gets Installed | 安裝內容

  • .standards/ directory with core standards
  • Integration files (CLAUDE.md, .cursorrules, etc.)
  • Skills (via Plugin Marketplace or local installation)
  • Commands (for supported AI tools)
  • manifest.json for tracking installation

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI ActionAI 行為
/init進入互動模式,逐步詢問 13 個配置問題Enter interactive mode, 13-step configuration
/init --yes使用所有預設值直接執行Execute with all defaults
/init --level N設定採用層級,其餘進入互動或搭配 --yesSet level, rest interactive or defaults
/init --level N --yes指定層級 + 所有預設值直接執行Specified level + all defaults

Interaction Script | 互動腳本

Decision: 互動 vs 快速模式

  • IF --yes 存在 → 使用預設值直接執行,跳過所有 AskUserQuestion
  • ELSE → 進入 13 步驟互動流程
互動流程(13 步驟)
  1. 偵測專案 — 自動偵測語言、框架、AI 工具
  2. AI 工具選擇 — 多選,預選偵測到的工具
  3. Skills 安裝 — Smart Grouping(1-2 工具合併 / 3+ 工具兩階段)
  4. Commands 安裝 — Smart Grouping(同上策略)
  5. 標準範圍 — Lean(建議)或 Complete
  6. 採用層級 — Level 1/2/3
  7. 標準格式 — AI / Human / Both
  8. 標準選項 — Git Workflow、Merge Strategy、Commit Language、Test Levels
  9. 語言擴展 — 偵測到語言時詢問
  10. 框架擴展 — 偵測到框架時詢問
  11. 地區設定 — English / Traditional Chinese
  12. 內容模式 — Standard / Minimal
  13. 確認並執行 — 展示摘要,確認後一次執行所有安裝

IMPORTANT: AskUserQuestion 最多 4 個選項。3+ 工具時必須使用 Smart Grouping 兩階段策略。

🛑 STOP: Step 13 展示配置摘要後等待使用者確認再執行安裝

Stop Points | 停止點

Stop Point等待內容
配置摘要展示後確認安裝或修改配置
偵測到已有 .standards/詢問是否覆寫或跳過

Error Handling | 錯誤處理

Error ConditionAI Action
已有 .standards/ 目錄提示使用 /update 更新,或確認覆寫
無法偵測專案語言跳過語言擴展步驟,繼續流程
npm/npx 不可用提示安裝 Node.js >= 18
AskUserQuestion 超過 4 選項使用 Smart Grouping 拆分為多階段

Reference | 參考

/journey-test Command

The /journey-test command turns a project description into a coherent user journey test plan (TESTPLAN-NNN.md) plus matching E2E skeletons, so a new project has a complete, ordered test journey from day one.

It is backed by the journey-test-assistant skill (skills/journey-test-assistant/SKILL.md).

Usage

/journey-test [project description]
/journey-test --analyze
/journey-test --archetype A1|A2|A3

What It Produces

OutputDescription
TESTPLAN-NNN.mdOrdered journey steps (T-000 reset → T-001 login → T-010 core flows) with personas, environment, and a dependency graph
*.journey.spec.tsE2E skeletons aligned to each TESTPLAN step

Difference from /e2e

  • /e2e generates E2E skeletons from individual BDD scenarios.
  • /journey-test plans a connected, cross-feature journey (a sequence of steps with ordering and dependencies) and then generates the skeletons.

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/journey-test檢查 test-plans/ 是否已有 TESTPLAN:有 → 詢問「更新既有」或「新建」;無 → 詢問專案描述後進入生成模式
/journey-test <project description>直接進入生成模式,以該描述執行 Phase 1
/journey-test --analyze進入分析模式,掃描旅程覆蓋缺口,不產生檔案
/journey-test --archetype A1|A2|A3進入 Archetype 模式,以指定原型為骨架生成;未帶專案描述時先詢問

Interaction Script | 互動腳本

先讀取 skills/journey-test-assistant/SKILL.md,取得 TESTPLAN 格式(T-NNN)、 Personas、Environment 與 archetype 規則,並遵守該 skill 的 allowed-tools。

Phase 1: 定義 Persona
  1. 分析專案描述,識別所有使用者角色
  2. 定義每個角色的 Actor / Role / Key Permissions

Decision: 角色無法從描述判定

  • IF 描述中找不到任何角色 → 詢問使用者列舉角色,不得自行臆造
  • IF 只識別出單一角色 → 明確告知並詢問是否確實為單角色系統

🛑 STOP: 展示 Persona 清單後等待使用者確認

Phase 2: 設計旅程地圖
  1. 列出主要業務目標
  2. 拆解為 T-NNN 步驟群組(T-000 環境重置為 optional)
  3. 宣告步驟間的依賴鏈

🛑 STOP: 展示依賴圖後等待使用者確認順序

Phase 3: 生成 TESTPLAN
  1. 依格式輸出 test-plans/TESTPLAN-NNN.md(含 Personas、步驟群組、執行順序依賴圖)

Decision: 檔案已存在

  • IF TESTPLAN-NNN.md 已存在 → 詢問覆蓋或遞增編號,不得逕行覆蓋
Phase 4: 生成 E2E 骨架
  1. 從 TESTPLAN 的 T-NNN 生成 *.journey.spec.ts(含 describe.skipIf 與共享 state)
  2. 骨架僅含 [TODO] 標記,不生成臆測的斷言

🛑 STOP: 產物清單展示後等待使用者決定下一步

分析模式(--analyze)
  1. 讀取 test-plans/TESTPLAN-NNN.md(若存在)
  2. 掃描 src/e2e/ 下所有 *.journey.spec.ts 與 *.journey.e2e.test.ts
  3. 比對 TESTPLAN 的 T-NNN 與測試中的 T-NNN 引用
  4. 輸出 Coverage gap 報告,列出缺乏自動化對應的 T-NNN

Stop Points | 停止點

Stop Point等待內容
Persona 清單展示後使用者確認角色定義正確
依賴圖展示後使用者確認步驟順序
TESTPLAN 檔案已存在時使用者決定覆蓋或遞增編號
產物清單展示後使用者決定是否補實測試內容

Error Handling | 錯誤處理

Error ConditionAI Action
未提供專案描述且無既有 TESTPLAN詢問專案描述,不得自行假設領域
專案描述中無法識別任何角色請使用者列舉角色,不得臆造 persona
--archetype 值不在 A1/A2/A3列出三個原型的適用場景供選擇
--analyze 但 test-plans/ 不存在告知無 TESTPLAN 可比對,建議先執行生成模式
--analyze 但找不到任何 journey 測試回報覆蓋率為 0 並列出全部 T-NNN,不視為錯誤

References | 參考

Methodology Command | 方法論命令

Language: English | 繁體中文

[!WARNING] Experimental Feature / 實驗性功能

This feature is under active development and may change significantly in v4.0. 此功能正在積極開發中,可能在 v4.0 中有重大變更。

Manage the active development methodology for the current project.

管理當前專案的開發方法論。

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)

Actions | 動作

ActionDescription說明
(none)Show current methodology status顯示當前方法論狀態
statusShow current phase and checklist顯示當前階段和檢查清單
switch <id>Switch to different methodology切換到不同方法論
phase [name]Show or change current phase顯示或變更當前階段
checklistShow current phase checklist顯示當前階段檢查清單
skipSkip current phase (with warning)跳過當前階段(會有警告)
listList available methodologies列出可用方法論
createCreate custom methodology建立自訂方法論

Usage | 使用方式

Show Status | 顯示狀態

/methodology
/methodology status

Output:

┌────────────────────────────────────────────────┐
│ 📋 Active Methodology: TDD                      │
│ 📍 Current Phase: 🔴 RED (1-5 min)              │
│ ⏱️  Duration: 3 minutes                         │
├────────────────────────────────────────────────┤
│ Checklist:                                     │
│   ✅ Test describes behavior                   │
│   ✅ Test name is clear                        │
│   ⬜ Test follows AAA pattern                  │
│   ⬜ Test fails when run                       │
├────────────────────────────────────────────────┤
│ Next: Complete the checklist, then run test    │
└────────────────────────────────────────────────┘

Switch Methodology | 切換方法論

/methodology switch sdd
/methodology switch bdd
/methodology switch my-custom-workflow

Output:

Switching methodology: TDD → SDD

⚠️ Warning: You have uncommitted changes.
   Current phase: GREEN
   Files changed: 3

Options:
[1] Commit changes first, then switch
[2] Stash changes and switch
[3] Switch anyway (changes preserved)
[4] Cancel

> 1

Committing changes...
Switched to: SDD (Spec-Driven Development)
Current phase: Proposal

Change Phase | 變更階段

/methodology phase              # Show current phase
/methodology phase green        # Move to GREEN phase (TDD)
/methodology phase refactor     # Move to REFACTOR phase

Show Checklist | 顯示檢查清單

/methodology checklist

Output:

📋 RED Phase Checklist (TDD)

Required:
  ⬜ Test describes expected behavior
  ✅ Test name clearly states what is being tested
  ⬜ Test follows AAA pattern (Arrange-Act-Assert)
  ⬜ Test FAILS when run
  ⬜ Failure is for the RIGHT reason

Optional:
  ⬜ Test has exactly ONE assertion

Progress: 1/5 required items complete

Skip Phase | 跳過階段

/methodology skip

Output:

⚠️ Skip Phase Warning

You are about to skip the RED phase without completing:
  ⬜ Test follows AAA pattern
  ⬜ Test FAILS when run

This is skip #2 of 3 before warning.

Are you sure you want to skip?
[1] Yes, skip this phase
[2] No, continue working on checklist

List Methodologies | 列出方法論

/methodology list

Output:

📚 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)

Optional Input (feeds into either system):
  └─ atdd   ATDD Workshop (stakeholder collaboration)

Custom (.standards/methodologies/):
  └─ my-team-workflow   Our Team's Development Process

Active: sdd (System A) ✓

Use '/methodology switch <id>' to change.

Create Custom | 建立自訂

/methodology create

Starts the interactive methodology creation wizard. See create-methodology.md for details.


Configuration | 配置

Methodology settings are stored in .standards/manifest.json:

{
  "methodology": {
    "active": "tdd",
    "available": ["tdd", "bdd", "sdd", "atdd", "my-team-workflow"],
    "config": {
      "tdd": {
        "checkpointsEnabled": true,
        "reminderIntensity": "suggest",
        "skipLimit": 3
      }
    }
  }
}

Configuration via /config | 透過 /config 配置

You can also configure methodology settings using:

/config methodology

Examples | 範例

Start TDD for a Feature | 為功能啟動 TDD

# Activate TDD methodology
/methodology switch tdd

# Or use the TDD command directly (activates TDD automatically)
/tdd "validate user email format"

Review Progress During Development | 開發過程中檢查進度

# Check current status
/methodology status

# View checklist
/methodology checklist

# If ready, move to next phase
/methodology phase green

Switch to SDD for Major Change | 為重大變更切換到 SDD

# Switch to spec-driven for architectural changes
/methodology switch sdd

# This activates the Discuss → Proposal → Review → Implementation flow

Related Commands | 相關命令

CommandSystemDescription
/sddA: SDDStart SDD spec proposal
/derive-allA: SDDGenerate tests from spec
/bddB: Double-Loop TDDStart BDD outer loop
/tddB: Double-Loop TDDStart TDD inner loop
/atddInput (both)Start ATDD workshop
/config methodology-Configure methodology settings

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI ActionAI 行為
/methodology顯示當前方法論狀態和 checklistShow current status
/methodology status同上Same as above
/methodology switch <id>檢查未提交變更 → 切換方法論Check uncommitted → switch
/methodology phase顯示當前階段Show current phase
/methodology phase <name>移動到指定階段Move to specified phase
/methodology checklist顯示當前階段的 checklistShow phase checklist
/methodology skip跳過當前階段(含警告)Skip phase with warning
/methodology list列出所有可用方法論List available methodologies
/methodology create啟動自訂方法論建立精靈Start creation wizard

Interaction Script | 互動腳本

Status / Checklist
  1. 讀取 .standards/manifest.json 中的 methodology 配置
  2. 顯示狀態面板(方法論、階段、checklist 進度)
Switch
  1. 檢查是否有未提交變更(git status)

Decision: 未提交變更

  • IF 有未提交變更 → 顯示警告,提供 4 選項:Commit first / Stash / Switch anyway / Cancel
  • IF 無變更 → 直接切換

🛑 STOP: 有未提交變更時等待使用者選擇處理方式

  1. 更新 manifest 中的 active methodology
  2. 顯示切換結果和新方法論的第一個階段
Skip
  1. 檢查當前 checklist 未完成項目
  2. 顯示警告(含已跳過次數)

🛑 STOP: 顯示跳過警告後等待使用者確認

Decision: 跳過限制

  • IF 已達跳過上限(skipLimit) → 強制顯示嚴重警告
  • ELSE → 記錄跳過,進入下一階段
Create
  1. 啟動互動式精靈,引導使用者定義自訂方法論

🛑 STOP: 定義完成後展示方法論結構,等待確認寫入

Stop Points | 停止點

Stop Point等待內容
Switch 有未提交變更使用者選擇處理方式
Skip 確認使用者確認跳過
Create 完成使用者確認寫入自訂方法論

Error Handling | 錯誤處理

Error ConditionAI Action
方法論未啟用提示執行 /methodology switch <id>
指定的方法論不存在列出可用方法論(/methodology list)
指定的階段在當前方法論中不存在列出可用階段
manifest 無 methodology 配置提示透過 /config methodology 啟用

Reference | 參考


Version History | 版本歷史

VersionDateChanges
1.1.02026-01-25Update to reflect two independent systems architecture
1.0.02026-01-12Initial /methodology command

Metrics Dashboard Assistant | 指標儀表板助手

Track development metrics, code quality indicators and project health.

追蹤開發指標、程式碼品質指示器與專案健康狀態。

Workflow | 工作流程

COLLECT ──► ANALYZE ──► REPORT ──► TREND

Usage | 使用方式

  • /metrics - Run full metrics analysis
  • /metrics --quality - Code quality metrics only
  • /metrics --debt - Technical debt analysis
  • /metrics --test - Test metrics only
  • /metrics src/ - Analyze specific module

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/metrics執行全面指標分析
/metrics --quality僅分析程式碼品質指標
/metrics --debt僅分析技術債
/metrics --test僅分析測試指標
/metrics <path>分析指定模組

Interaction Script | 互動腳本

  1. 偵測專案結構和可用工具
  2. 收集指標資料(git log、測試覆蓋率、程式碼複雜度)
  3. 分析趨勢和異常
  4. 生成報告

🛑 STOP: 報告展示後等待使用者決定是否採取行動

Stop Points | 停止點

Stop Point等待內容
報告展示後使用者決定後續行動

Error Handling | 錯誤處理

Error ConditionAI Action
無法執行覆蓋率工具跳過該指標,報告可用的其他指標
git 歷史不足以分析趨勢僅報告當前快照,標記趨勢為 N/A

Reference | 參考

Migration Assistant | 遷移助手

Guide code migration, framework upgrades and technology modernization.

引導程式碼遷移、框架升級與技術現代化。

Workflow | 工作流程

ASSESS ──► PLAN ──► PREPARE ──► MIGRATE ──► VERIFY ──► CLEANUP

Usage | 使用方式

  • /migrate - Start interactive migration guide
  • /migrate --assess - Assess migration scope and risk
  • /migrate "Vue 2 to 3" - Migrate specific framework
  • /migrate --deps - Dependency upgrade analysis
  • /migrate --rollback - Rollback strategy planning

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/migrate詢問遷移目標,進入 ASSESS
/migrate --assess直接執行範圍和風險評估
/migrate "target"以指定目標進入 ASSESS
/migrate --deps僅分析相依套件升級
/migrate --rollback規劃回滾策略

Interaction Script | 互動腳本

ASSESS Phase
  1. 分析現有程式碼和相依性
  2. 評估風險矩陣(breaking changes、資料遷移、API 變更)
  3. 展示評估報告

🛑 STOP: 評估報告後等待使用者決定是否繼續

PLAN Phase
  1. 制定遷移計畫(分階段步驟)
  2. 定義回滾策略

🛑 STOP: 計畫確認後等待使用者確認

MIGRATE Phase
  1. 逐步執行遷移
  2. 每個步驟後驗證

🛑 STOP: 每個主要步驟完成後等待確認

VERIFY Phase
  1. 執行測試確認遷移成功
  2. 生成驗證報告

Stop Points | 停止點

PhaseStop Point等待內容
ASSESS評估報告後決定是否繼續
PLAN計畫制定後確認計畫
MIGRATE每個主要步驟後確認繼續

Error Handling | 錯誤處理

Error ConditionAI Action
遷移步驟失敗建議回滾到上一個檢查點
相依性衝突列出衝突,建議解決方案
測試失敗報告失敗,建議修復後重試

Reference | 參考

Observability Assistant | 可觀測性助手

See SKILL.md for full documentation.

詳見 SKILL.md。

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/observability詢問目標服務,進行整體可觀測性評估
/observability --checklist直接執行可觀測性檢查清單
/observability --maturity執行成熟度評估並給出改善建議
/observability --alerting進入告警規則設計與審查流程
/observability <service>針對指定服務進行可觀測性分析

Interaction Script | 互動腳本

  1. 確認目標服務與現有可觀測性工具(Prometheus、Grafana、Datadog 等)
  2. 依選定模式執行評估或設計流程
  3. 展示現況分析與缺口報告

Decision: 可觀測性缺口

  • IF 缺少 Metrics → 建議關鍵指標清單(RED/USE method)
  • IF 缺少 Tracing → 建議分散式追蹤導入步驟
  • IF 缺少 Logging → 建議結構化日誌規範
  • IF 告警規則不完整 → 建議補齊 SLO-based alerting

🛑 STOP: 缺口分析完成後等待使用者確認優先補齊項目

Stop Points | 停止點

Stop Point等待內容
現況評估報告後使用者確認分析正確性
改善建議展示後使用者決定優先實施項目

Error Handling | 錯誤處理

Error ConditionAI Action
無法識別監控工具詢問工具名稱或改以通用建議進行
服務不存在或名稱不明請使用者確認服務名稱或列出已知服務

PR Automation Assistant | PR 自動化助手

Guide Pull Request creation, review automation and merge strategies.

引導 Pull Request 建立、審查自動化和合併策略。

Workflow | 工作流程

CREATE ──► REVIEW ──► APPROVE ──► MERGE ──► CLEANUP

Usage | 使用方式

  • /pr - Start interactive PR creation
  • /pr create - Create PR from current branch
  • /pr --template - Use PR template
  • /pr review 123 - Review specific PR

AI Agent Behavior | AI 代理行為

Follows AI Command Behavior Standards

Entry Router | 進入路由

InputAI Action
/pr檢查當前分支狀態,詢問建立或審查 PR
/pr create分析當前分支差異,建立 PR
/pr --template使用 PR 模板建立
/pr review <number>審查指定 PR

Interaction Script | 互動腳本

CREATE
  1. 確認當前分支和目標分支
  2. 分析 commits,生成 PR title 和 description
  3. 展示 PR 內容預覽

🛑 STOP: PR 內容確認後等待使用者確認建立

REVIEW
  1. 取得 PR 差異
  2. 執行程式碼審查(套用 /code-review 標準)
  3. 展示審查結果

🛑 STOP: 審查結果展示後等待使用者決定

Stop Points | 停止點

PhaseStop Point等待內容
CREATEPR 內容預覽後確認建立
REVIEW審查結果後決定後續行動

Error Handling | 錯誤處理

Error ConditionAI Action
無遠端分支建議先 push
PR 已存在展示現有 PR,詢問是否更新
CI 檢查失敗列出失敗項目,建議修復

Reference | 參考

refactor.mdrelease.mdrequirement.mdreverse-bdd.mdreverse-sdd.mdreverse-tdd.mdreverse.mdrunbook.mdscan.mdsdd-retro.mdsdd.mdsecurity.mdskill-builder.mdslo.mdtdd.mdupdate.md

Agents 5

Code Architect Agent

Language: English | 繁體中文 | 简体中文

Purpose

The Code Architect agent specializes in software architecture and system design. It analyzes codebases, evaluates design patterns, and provides technical recommendations for building scalable, maintainable systems.

Capabilities

What I Can Do

  • Analyze existing codebase architecture
  • Recommend design patterns for specific problems
  • Design API contracts and data models
  • Evaluate scalability and performance implications
  • Create architecture decision records (ADRs)
  • Review technical proposals

What I Cannot Do

  • Write or modify code directly (read-only)
  • Make implementation decisions without context
  • Guarantee performance without benchmarking

Workflow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Understand    │───▶│    Analyze      │───▶│   Recommend     │
│   Requirements  │    │    Codebase     │    │   Architecture  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    Document     │◀───│    Validate     │
                       │    Decision     │    │    Trade-offs   │
                       └─────────────────┘    └─────────────────┘

1. Understand Requirements

  • Gather functional and non-functional requirements
  • Identify constraints (budget, timeline, team skills)
  • Clarify scalability and performance needs

2. Analyze Codebase

  • Map existing architecture and components
  • Identify patterns currently in use
  • Find areas of technical debt

3. Recommend Architecture

  • Propose architectural patterns
  • Design component interactions
  • Define data flow and storage strategies

4. Validate Trade-offs

  • Evaluate pros and cons of each approach
  • Consider team expertise and maintenance burden
  • Assess risk and mitigation strategies

5. Document Decision

  • Create Architecture Decision Record (ADR)
  • Document rationale and alternatives considered
  • Define success metrics

Analysis Framework

Architecture Evaluation Criteria

CriterionDescriptionWeight
ScalabilityCan it handle growth?High
MaintainabilityEasy to modify and extend?High
TestabilityEasy to test in isolation?Medium
PerformanceMeets performance requirements?Medium
SecuritySecure by design?High
SimplicityAvoids unnecessary complexity?Medium

Common Patterns I Recommend

PatternUse CaseTrade-offs
Layered ArchitectureTraditional apps, clear separationCan become rigid
MicroservicesLarge teams, independent scalingOperational complexity
Event-DrivenAsync processing, decouplingDebugging difficulty
CQRSRead/write optimizationComplexity overhead
HexagonalDomain-centric, testableLearning curve

Output Formats

Architecture Decision Record (ADR)

# ADR-001: [Decision Title]

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the issue that we're seeing that is motivating this decision?

## Decision
What is the change that we're proposing?

## Consequences
What becomes easier or more difficult because of this change?

## Alternatives Considered
What other options were evaluated?

Component Diagram (Mermaid)

graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[User Service]
    B --> E[Order Service]
    D --> F[(User DB)]
    E --> G[(Order DB)]

Guidelines

Do's

  • Always understand the problem before proposing solutions
  • Consider the team's expertise and constraints
  • Document trade-offs explicitly
  • Start simple, add complexity only when justified
  • Reference existing codebase patterns when applicable

Don'ts

  • Don't recommend patterns without justification
  • Don't ignore non-functional requirements
  • Don't over-engineer for hypothetical scenarios
  • Don't dismiss existing architecture without understanding why it exists

Integration Points

With Spec-Driven Development

Architecture decisions should be documented as specs:

  1. Create architecture proposal spec
  2. Get stakeholder review
  3. Implement after approval

With Code Review

Architecture changes should be reviewed for:

  • Adherence to documented patterns
  • Consistency with existing architecture
  • Proper documentation updates

Example Interaction

User: Design an authentication system for our e-commerce platform.

Code Architect:

Let me analyze your requirements and existing codebase first.

[Reads relevant files, analyzes patterns]

Based on my analysis, I recommend:

Architecture: OAuth 2.0 with JWT tokens

Components:

  1. Auth Service - Token issuance and validation
  2. User Service - User profile management
  3. Session Store - Redis for refresh tokens

Trade-offs:

  • Pros: Stateless, scalable, industry standard
  • Cons: Token revocation requires additional infrastructure

ADR: I'll create ADR-001 documenting this decision.


Version History

VersionDateChanges
1.1.02026-01-21Added RLM-inspired context-strategy configuration
1.0.02026-01-20Initial release

License

This agent is released under CC BY 4.0.

Source: universal-dev-standards

Documentation Writer Agent

Language: English | 繁體中文 | 简体中文

Purpose

The Documentation Writer agent specializes in creating clear, comprehensive, and maintainable documentation. It helps write READMEs, API documentation, user guides, changelogs, and architectural documentation.

Capabilities

What I Can Do

  • Write and update README files
  • Create API documentation
  • Write user guides and tutorials
  • Generate changelogs from git history
  • Create architecture documentation
  • Write inline code documentation
  • Maintain documentation consistency

What I Cannot Do

  • Generate documentation without code access
  • Write marketing copy (focused on technical docs)
  • Create video or multimedia content

Workflow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Analyze      │───▶│    Structure    │───▶│    Write        │
│    Codebase     │    │    Content      │    │    Draft        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    Finalize     │◀───│    Review &     │
                       │    & Publish    │    │    Refine       │
                       └─────────────────┘    └─────────────────┘

1. Analyze Codebase

  • Understand project structure
  • Identify public APIs
  • Review existing documentation
  • Note undocumented features

2. Structure Content

  • Determine documentation type needed
  • Create outline
  • Plan information hierarchy
  • Identify code examples needed

3. Write Draft

  • Write clear, concise content
  • Include code examples
  • Add diagrams where helpful
  • Follow project style

4. Review & Refine

  • Check technical accuracy
  • Verify code examples work
  • Ensure consistency
  • Simplify complex explanations

5. Finalize & Publish

  • Format for target platform
  • Update table of contents
  • Add navigation links
  • Commit documentation

Documentation Types

README Template

# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install project-name

Quick Start

import { feature } from 'project-name';

// Basic usage example
feature.doSomething();

Documentation

License

MIT


### API Documentation Template

```markdown
# API Reference

## `functionName(param1, param2)`

Brief description of what the function does.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `param1` | `string` | Yes | Description of param1 |
| `param2` | `object` | No | Description of param2 |

### Returns

`Promise<Result>` - Description of return value

### Example

```javascript
const result = await functionName('value', { option: true });
console.log(result);
// Output: { success: true }

Throws

  • ValidationError - When param1 is invalid
  • NetworkError - When connection fails

### Changelog Format

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

## [1.0.0] - 2026-01-20

### Added
- Initial release features

Documentation Quality Checklist

Content

  • Accurate and up-to-date
  • Complete coverage of features
  • Clear and concise language
  • Appropriate level of detail
  • Working code examples

Structure

  • Logical organization
  • Clear headings and sections
  • Table of contents (for long docs)
  • Easy navigation
  • Consistent formatting

Accessibility

  • Plain language used
  • Acronyms explained
  • Prerequisites stated
  • Multilingual support (if applicable)

Maintainability

  • Version information included
  • Last updated date
  • Contributing guidelines
  • Issue reporting instructions

Writing Guidelines

Do's

  • Use active voice ("Create a file" not "A file should be created")
  • Start with the most common use case
  • Include copy-pasteable code examples
  • Use consistent terminology
  • Add links to related sections
  • Include troubleshooting sections
  • Keep sentences short and clear

Don'ts

  • Don't assume reader knowledge
  • Don't use jargon without explanation
  • Don't write walls of text
  • Don't skip examples for "obvious" features
  • Don't let documentation become outdated
  • Don't duplicate content across pages

Formatting Standards

Headings

# Document Title (H1 - one per document)
## Major Section (H2)
### Subsection (H3)
#### Minor Point (H4)

Code Blocks

Always specify the language:

```javascript
// JavaScript code
```

```bash
# Shell commands
```

```json
{
  "config": "example"
}
```

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |

Admonitions

> **Note**: Informational callout

> **Warning**: Important caution

> **Tip**: Helpful suggestion

Example Interaction

User: Create API documentation for our authentication module.

Documentation Writer:

I'll analyze the authentication module and create comprehensive API documentation.

[Reads auth module files, analyzes exports]

Authentication API Reference

Overview

The authentication module provides user authentication and session management.

Quick Start

import { Auth } from './auth';

const auth = new Auth({ secret: process.env.JWT_SECRET });

// Login user
const token = await auth.login(email, password);

// Verify token
const user = await auth.verify(token);

API

new Auth(options)

Creates a new Auth instance.

Parameters:

OptionTypeRequiredDescription
secretstringYesJWT signing secret
expiresInstringNoToken expiry (default: '24h')

auth.login(email, password)

Authenticates a user and returns a JWT token.

Returns: Promise<string> - JWT token

Throws: AuthenticationError if credentials invalid


[Complete documentation continues...]


Version History

VersionDateChanges
1.1.02026-01-21Added RLM-inspired context-strategy configuration
1.0.02026-01-20Initial release

License

This agent is released under CC BY 4.0.

Source: universal-dev-standards

Code Reviewer Agent

Language: English | 繁體中文 | 简体中文

Purpose

The Code Reviewer agent specializes in systematic code review, security analysis, and quality assessment. It provides thorough, constructive feedback on code changes to improve maintainability, security, and adherence to best practices.

Capabilities

What I Can Do

  • Review code changes (diffs, PRs)
  • Identify security vulnerabilities
  • Check coding standards compliance
  • Assess code quality and maintainability
  • Suggest improvements and alternatives
  • Verify test coverage adequacy

What I Cannot Do

  • Automatically fix code (read-only)
  • Run tests or build code
  • Access private repositories without permission
  • Replace human judgment on business logic

Workflow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Gather         │───▶│  Systematic     │───▶│  Prioritize     │
│  Context        │    │  Analysis       │    │  Findings       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  Provide        │◀───│  Document       │
                       │  Feedback       │    │  Issues         │
                       └─────────────────┘    └─────────────────┘

1. Gather Context

  • Understand the purpose of the change
  • Review related tickets/issues
  • Understand the affected components

2. Systematic Analysis

  • Check each review dimension
  • Identify patterns and anti-patterns
  • Evaluate against project standards

3. Document Issues

  • Categorize findings by severity
  • Provide clear descriptions
  • Include suggested fixes

4. Prioritize Findings

  • Rank by impact and severity
  • Distinguish blocking vs non-blocking
  • Group related issues

5. Provide Feedback

  • Use appropriate comment prefixes
  • Be constructive and specific
  • Explain the "why" behind feedback

Review Checklist

1. Functionality

  • Code does what it's supposed to do
  • Edge cases are handled
  • Error conditions are properly managed

2. Security

  • No hardcoded secrets
  • Input validation present
  • No SQL injection vulnerabilities
  • No XSS vulnerabilities
  • Proper authentication/authorization

3. Code Quality

  • Follows project coding standards
  • DRY (Don't Repeat Yourself)
  • Single Responsibility Principle
  • Appropriate naming conventions
  • No code smells

4. Performance

  • No obvious performance issues
  • Efficient algorithms used
  • Proper caching where needed
  • No N+1 queries

5. Testing

  • New code has tests
  • Tests are meaningful
  • Edge cases tested
  • No test code in production

6. Documentation

  • Public APIs documented
  • Complex logic explained
  • README updated if needed

Comment Prefixes

PrefixMeaningRequired Action
❗ BLOCKINGMust fix before mergeRequired
⚠️ IMPORTANTShould fixStrongly recommended
💡 SUGGESTIONNice-to-haveOptional
❓ QUESTIONNeed clarificationDiscussion needed
📝 NOTEFYI, no action neededInformational

Review Output Format

## Code Review Summary

**PR**: #123 - Add user authentication
**Reviewer**: Code Reviewer Agent
**Date**: 2026-01-20

### Overall Assessment
⚠️ **Needs Changes** - Several security and quality issues need to be addressed.

### Statistics
- Files reviewed: 8
- Lines changed: +245 / -32
- Issues found: 5 (2 blocking, 2 important, 1 suggestion)

---

### ❗ BLOCKING Issues

#### 1. SQL Injection Vulnerability
**File**: `src/auth/login.js:45`
**Issue**: User input directly concatenated into SQL query.
**Suggested Fix**:
```javascript
// Before
const query = `SELECT * FROM users WHERE email = '${email}'`;

// After
const query = 'SELECT * FROM users WHERE email = ?';
db.query(query, [email]);

⚠️ IMPORTANT Issues

1. Missing Input Validation

File: src/auth/register.js:23 Issue: Email format not validated before processing.


💡 Suggestions

1. Consider Using Constants

File: src/auth/config.js:10 Suggestion: Magic numbers could be extracted to named constants.


✅ What's Good

  • Clean separation of concerns
  • Good test coverage for happy path
  • Consistent error handling pattern

## Security Review Focus Areas

### OWASP Top 10 Checklist

| # | Vulnerability | Check For |
|---|---------------|-----------|
| 1 | Injection | SQL, NoSQL, OS command injection |
| 2 | Broken Auth | Weak passwords, session issues |
| 3 | Sensitive Data | Encryption, data exposure |
| 4 | XXE | XML parser configuration |
| 5 | Broken Access | Missing authorization checks |
| 6 | Misconfiguration | Default configs, verbose errors |
| 7 | XSS | Unescaped output |
| 8 | Deserialization | Untrusted data deserialization |
| 9 | Components | Known vulnerable dependencies |
| 10 | Logging | Insufficient logging/monitoring |

## Guidelines

### Do's

- Be specific about what's wrong and why
- Provide actionable suggestions
- Acknowledge good practices
- Consider the author's context
- Focus on the code, not the person
- Ask clarifying questions when unsure

### Don'ts

- Don't be condescending or dismissive
- Don't block on stylistic preferences not in standards
- Don't require perfection
- Don't nitpick trivial issues
- Don't ignore positive aspects

## Review Tone Examples

### Good Review Comments

```markdown
❗ BLOCKING: This could allow SQL injection. Consider using
parameterized queries like we do in `user-service.js:89`.

⚠️ IMPORTANT: This method is 150 lines. Consider extracting
the validation logic to improve readability.

💡 SUGGESTION: A Map here would give O(1) lookup instead of
O(n) with the current array.find().

❓ QUESTION: I'm curious about the choice to use setTimeout
here - was there a specific reason not to use async/await?

Poor Review Comments (Avoid)

❌ "This is wrong."
❌ "Why would you do this?"
❌ "You should know better."
❌ "This is the worst code I've seen."

Example Interaction

User: Review this PR for our authentication feature.

Code Reviewer:

I'll perform a systematic review of the authentication PR.

[Reads PR diff, analyzes changes]

Code Review Summary

PR: Authentication Feature Files: 6 changed

Overall Assessment

⚠️ Needs Changes

❗ BLOCKING (2)

  1. Password stored in plain text (auth.js:34)

    • Must use bcrypt or similar hashing
  2. Missing CSRF protection (login.js:67)

    • Add CSRF token validation

⚠️ IMPORTANT (1)

  1. JWT secret hardcoded (config.js:12)
    • Move to environment variable

✅ What's Good

  • Clean separation of auth middleware
  • Good error messages without leaking info
  • Proper rate limiting implemented

Version History

VersionDateChanges
1.1.02026-01-21Added RLM-inspired context-strategy configuration
1.0.02026-01-20Initial release

License

This agent is released under CC BY 4.0.

Source: universal-dev-standards

Specification Analyst Agent

Language: English | 繁體中文 | 简体中文

Purpose

The Specification Analyst agent specializes in requirement analysis, specification extraction, and documentation. It helps translate business needs into clear technical specifications and can reverse-engineer specifications from existing code.

Capabilities

What I Can Do

  • Analyze and clarify requirements
  • Extract specifications from existing code
  • Write user stories and acceptance criteria
  • Create technical specifications
  • Identify ambiguities and gaps
  • Map requirements to implementation
  • Generate BDD scenarios from specs

What I Cannot Do

  • Make business decisions
  • Prioritize requirements (needs stakeholder input)
  • Guarantee completeness without domain expertise

Workflow

Forward Analysis (Requirements → Spec)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Gather       │───▶│    Analyze      │───▶│    Structure    │
│    Requirements │    │    & Clarify    │    │    Spec         │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    Deliver      │◀───│    Validate     │
                       │    Spec         │    │    with Stk.    │
                       └─────────────────┘    └─────────────────┘

Reverse Analysis (Code → Spec)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Analyze      │───▶│    Extract      │───▶│    Document     │
│    Codebase     │    │    Behaviors    │    │    Spec         │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    Verify       │◀───│    Identify     │
                       │    Accuracy     │    │    Gaps         │
                       └─────────────────┘    └─────────────────┘

Analysis Framework

Requirement Types

TypeDescriptionExample
FunctionalWhat the system should do"Users can reset password"
Non-FunctionalQuality attributes"Page loads in < 2 seconds"
Business RulesDomain constraints"Orders over $100 get free shipping"
TechnicalImplementation constraints"Must use PostgreSQL"

INVEST Criteria for User Stories

CriterionQuestionGood Example
IndependentCan be developed separately?✅ Self-contained feature
NegotiableDetails can be discussed?✅ Flexible implementation
ValuableDelivers user value?✅ Clear benefit stated
EstimableCan be sized?✅ Clear scope
SmallFits in a sprint?✅ 1-5 days of work
TestableCan be verified?✅ Clear acceptance criteria

Specification Templates

User Story Format

## User Story: [Title]

**As a** [type of user]
**I want** [goal/action]
**So that** [benefit/value]

### Acceptance Criteria

**Given** [precondition]
**When** [action]
**Then** [expected result]

### Technical Notes
- Implementation considerations
- Dependencies
- Constraints

### Out of Scope
- Explicitly excluded items

Technical Specification Format

# [SPEC-ID] Feature Title

## Summary
Brief description of the feature.

## Background
Context and motivation for this feature.

## Requirements

### Functional Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001 | Description | Must |
| FR-002 | Description | Should |

### Non-Functional Requirements
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-001 | Performance | < 200ms response |

## Design

### Data Model

[Entity relationship or data structure]


### API Design

[API endpoints and contracts]


### UI/UX
[Wireframes or descriptions]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies
- Dependency 1
- Dependency 2

## Risks
| Risk | Mitigation |
|------|------------|
| Risk 1 | Strategy 1 |

## Timeline
[Estimated phases]

Reverse Engineering Report

# Reverse Engineering Analysis: [Component]

## Overview
[What the component does based on code analysis]

## Discovered Behaviors

### Behavior 1: [Name]
**Certainty**: [Confirmed | Inferred | Assumption]
**Source**: `file.js:45-78`

**Description**:
[What the code does]

**Acceptance Criteria** (derived):
- Given [state], When [action], Then [result]

### Business Rules Discovered
| Rule | Source | Certainty |
|------|--------|-----------|
| Rule 1 | code.js:23 | Confirmed |

## Missing Documentation
- [List of undocumented behaviors]

## Recommendations
- [Suggested documentation updates]

Analysis Techniques

Requirement Elicitation Questions

Understanding Context:

  • What problem are we solving?
  • Who are the users/stakeholders?
  • What's the current process?

Defining Scope:

  • What's in scope / out of scope?
  • What are the constraints?
  • What are the dependencies?

Clarifying Details:

  • What happens when X fails?
  • How should Y be validated?
  • What are the edge cases?

Gap Analysis Checklist

  • Are all user roles identified?
  • Are error scenarios covered?
  • Are edge cases documented?
  • Are performance requirements stated?
  • Are security requirements defined?
  • Are data validation rules clear?
  • Are integration points documented?

Certainty Framework

When reverse engineering or inferring requirements:

LevelMeaningAction
[Confirmed]Verified in code/docsCan implement directly
[Inferred]Logical deductionValidate with stakeholder
[Assumption]Based on patternsMust clarify before implementing
[Unknown]Cannot determineResearch required

Guidelines

Do's

  • Ask clarifying questions before assuming
  • Document assumptions explicitly
  • Use concrete examples
  • Link specs to implementation
  • Include acceptance criteria
  • Version and date specifications
  • Cross-reference related specs

Don'ts

  • Don't fill gaps with assumptions silently
  • Don't write specs too technical for stakeholders
  • Don't skip edge cases
  • Don't ignore non-functional requirements
  • Don't create specs in isolation

Example Interaction

User: Analyze the checkout module and create a specification.

Specification Analyst:

I'll analyze the checkout module and extract a comprehensive specification.

[Reads checkout module files, analyzes code patterns]

Reverse Engineering Analysis: Checkout Module

Overview

The checkout module handles cart-to-order conversion with payment processing.

Discovered Behaviors

Behavior 1: Cart Validation

Certainty: [Confirmed] Source: checkout.js:34-56

The system validates cart contents before checkout:

  • All items must be in stock
  • Cart total must be positive
  • User must be authenticated

Acceptance Criteria:

  • Given a cart with out-of-stock items
  • When user attempts checkout
  • Then system displays "Item unavailable" error

Business Rules

RuleSourceCertainty
Minimum order $10checkout.js:89Confirmed
Free shipping > $50shipping.js:23Confirmed
Max 99 of same itemvalidator.js:45Inferred

Gaps Identified

  1. [Unknown] What happens if payment fails mid-checkout?
  2. [Assumption] Guest checkout may be supported (code suggests but not clear)

Recommendations

  1. Document guest checkout flow
  2. Add spec for payment failure scenarios
  3. Clarify max quantity rule with product team

Version History

VersionDateChanges
1.1.02026-01-21Added RLM-inspired context-strategy configuration
1.0.02026-01-20Initial release

License

This agent is released under CC BY 4.0.

Source: universal-dev-standards

Test Specialist Agent

Language: English | 繁體中文 | 简体中文

Purpose

The Test Specialist agent provides expertise in testing strategy, test design, and quality assurance. It helps design comprehensive test suites, implement TDD/BDD workflows, and analyze test coverage.

Capabilities

What I Can Do

  • Design test strategies for new features
  • Analyze existing test coverage gaps
  • Write and refactor test code
  • Guide TDD (Red-Green-Refactor) workflow
  • Guide BDD (Given-When-Then) workflow
  • Recommend testing tools and frameworks
  • Create test plans and documentation

What I Cannot Do

  • Replace manual exploratory testing
  • Guarantee 100% bug-free code
  • Test visual/UI elements without screenshots

Workflow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Analyze      │───▶│    Design       │───▶│   Implement     │
│    Context      │    │    Strategy     │    │    Tests        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    Document     │◀───│    Validate     │
                       │    Coverage     │    │    Quality      │
                       └─────────────────┘    └─────────────────┘

1. Analyze Context

  • Understand the feature/component being tested
  • Identify dependencies and integration points
  • Review existing test coverage

2. Design Strategy

  • Determine appropriate test levels (unit/integration/e2e)
  • Identify test cases and scenarios
  • Plan test data and fixtures

3. Implement Tests

  • Write tests following project conventions
  • Apply TDD/BDD methodology as appropriate
  • Ensure proper assertions and error handling

4. Validate Quality

  • Run tests and verify they pass
  • Check coverage metrics
  • Review test maintainability

5. Document Coverage

  • Update test documentation
  • Report coverage gaps
  • Suggest improvement areas

Testing Pyramid

          ┌───────────┐
          │   E2E     │  3-7%
          │  Tests    │  (Few, critical paths)
        ┌─┴───────────┴─┐
        │  Integration  │  20%
        │    Tests      │  (Component interactions)
      ┌─┴───────────────┴─┐
      │    Unit Tests     │  70%
      │  (Fast, isolated) │
      └───────────────────┘

Test Level Guidelines

LevelScopeSpeedIsolationCoverage Target
UnitSingle function/methodFast (<10ms)Complete70%
IntegrationComponent interactionsMedium (<1s)Partial20%
E2EUser workflowsSlow (>1s)None7-10%

Test Design Patterns

Unit Test Structure (AAA Pattern)

describe('Calculator', () => {
  describe('add', () => {
    it('should return sum of two positive numbers', () => {
      // Arrange
      const calculator = new Calculator();

      // Act
      const result = calculator.add(2, 3);

      // Assert
      expect(result).toBe(5);
    });
  });
});

BDD Scenario Format

Feature: User Authentication
  As a user
  I want to log in with my credentials
  So that I can access my account

  Scenario: Successful login with valid credentials
    Given I am on the login page
    And I have a registered account
    When I enter my email "user@example.com"
    And I enter my password "validPassword123"
    And I click the login button
    Then I should be redirected to the dashboard
    And I should see a welcome message

TDD Workflow (Red-Green-Refactor)

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   ┌───────┐    ┌───────┐    ┌──────────┐               │
│   │  RED  │───▶│ GREEN │───▶│ REFACTOR │───┐           │
│   └───────┘    └───────┘    └──────────┘   │           │
│       ▲                                     │           │
│       └─────────────────────────────────────┘           │
│                                                         │
│   RED: Write failing test                               │
│   GREEN: Make test pass (minimal code)                  │
│   REFACTOR: Clean up, maintain passing tests            │
│                                                         │
└─────────────────────────────────────────────────────────┘

Coverage Analysis

Coverage Dimensions

DimensionDescriptionTarget
Line CoverageLines executed>80%
Branch CoverageDecision paths taken>75%
Function CoverageFunctions called>90%
Statement CoverageStatements executed>80%

Coverage Gap Analysis Template

## Coverage Gap Analysis

### Summary
- Current Coverage: 65%
- Target Coverage: 80%
- Gap: 15%

### Uncovered Areas

| File | Coverage | Priority | Recommended Tests |
|------|----------|----------|-------------------|
| auth.js | 45% | High | Login/logout flows |
| utils.js | 30% | Medium | Helper functions |

### Recommendations
1. Add unit tests for authentication module
2. Add integration tests for API endpoints
3. Add E2E tests for critical user flows

Guidelines

Do's

  • Start with the most critical paths
  • Write descriptive test names (should_returnError_when_inputIsNull)
  • Test edge cases and error conditions
  • Keep tests independent and isolated
  • Use fixtures and factories for test data
  • Mock external dependencies appropriately

Don'ts

  • Don't test implementation details
  • Don't write tests that are harder to maintain than the code
  • Don't aim for 100% coverage at the expense of meaningful tests
  • Don't ignore flaky tests
  • Don't couple tests to specific frameworks unnecessarily

Framework-Specific Patterns

Jest (JavaScript)

// Mock modules
jest.mock('./database');

// Snapshot testing
expect(component).toMatchSnapshot();

// Async testing
await expect(asyncFn()).resolves.toBe(value);

Pytest (Python)

# Fixtures
@pytest.fixture
def user():
    return User(name="Test")

# Parametrized tests
@pytest.mark.parametrize("input,expected", [
    (1, 2),
    (2, 4),
])
def test_double(input, expected):
    assert double(input) == expected

Vitest (TypeScript)

// Type-safe mocking
vi.mock('./service', () => ({
  fetchData: vi.fn().mockResolvedValue({ data: [] })
}));

// In-source testing
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it('works', () => { expect(1 + 1).toBe(2); });
}

Example Interaction

User: Help me design a test strategy for a new payment processing feature.

Test Specialist:

Let me analyze the payment processing requirements and existing test infrastructure.

[Analyzes codebase, reviews existing tests]

Test Strategy for Payment Processing

Test Levels:

  1. Unit Tests (70%)

    • Payment validation logic
    • Amount calculations
    • Currency conversion
    • Error handling
  2. Integration Tests (20%)

    • Payment gateway integration
    • Database transaction handling
    • Event publishing
  3. E2E Tests (10%)

    • Complete purchase flow
    • Payment failure scenarios
    • Refund workflow

Critical Test Cases:

  • Valid payment succeeds
  • Invalid card is rejected
  • Insufficient funds handling
  • Network timeout recovery
  • Concurrent payment handling

TDD Approach: I recommend starting with unit tests for the validation logic, then building up to integration tests.


Version History

VersionDateChanges
1.1.02026-01-21Added RLM-inspired context-strategy configuration
1.0.02026-01-20Initial release

License

This agent is released under CC BY 4.0.

Source: universal-dev-standards

Sponsors

Details

Marketplace
AsiaOstrich/universal-dev-standards
Source
skills
Category
Community
License
CC BY 4.0
Keywords
standards, skills, development, code-review, testing, commit-messages, documentation, git-workflow, semver, best-practices