
universal-dev-standards
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-ostrichRun it inside Claude Code after adding the marketplace with /plugin marketplace add AsiaOstrich/universal-dev-standards.
Contents
Discovered from sourceCommands 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 | 工作流程
- Parse SPEC — Read the specification file and extract all AC definitions (AC-1, AC-2, ...)
- Scan tests — Search test files for
@ACand@SPECannotations - Build matrix — Map each AC to its corresponding test references
- Classify status — ✅ covered | ⚠️ partial | ❌ uncovered
- Calculate coverage —
Coverage % = (covered + partial × 0.5) / total × 100 - Generate report — Output standardized Markdown report
How This Differs from /coverage | 與 /coverage 的區別
/coverage | /ac-coverage | |
|---|---|---|
| Level | Code (line/branch/function) | Requirements (AC-to-test) |
| Question | "How much code is tested?" | "Which AC have tests?" |
| Input | Source code + test runner | SPEC file + test annotations |
Both are complementary — use /coverage for code quality, /ac-coverage for requirement verification.
兩者互補 — 使用 /coverage 確保程式碼品質,使用 /ac-coverage 確保需求驗證。
Quality Thresholds | 品質門檻
| Context | Default Threshold | Configurable |
|---|---|---|
| Check-in | 80% | --threshold N |
| Release | 100% | --threshold N |
| Warning | 60% | --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/checkinquality gates- 有未覆蓋 AC → 執行
/derive-tdd補齊測試 — Uncovered AC found → Run/derive-tddto add tests- 有部分覆蓋 AC → 檢查缺少的邊界情況 — Partial AC → Review missing edge cases
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/ac-coverage | 列出可用的 spec 檔案供選擇 |
/ac-coverage <spec-file> | 直接分析指定 spec 的 AC 覆蓋率 |
/ac-coverage <spec-file> --threshold N | 使用自訂門檻 |
Interaction Script | 互動腳本
- 讀取 spec 檔案,擷取所有 AC
- 掃描測試檔案中的
@AC和@SPEC註解 - 建立 AC → Test 追蹤矩陣
- 計算覆蓋率
- 生成報告
Decision: 覆蓋率結果
- IF 覆蓋率 ≥ 門檻 → 標記 ✅,建議
/checkin - IF 有未覆蓋 AC → 列出並建議
/derive-tdd補測試 - IF 有部分覆蓋 AC → 建議檢查缺少的邊界情況
🛑 STOP: 報告展示後等待使用者決定下一步
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 報告展示後 | 使用者決定補測試或繼續 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| Spec 檔案不存在 | 列出可用的 spec 檔案 |
| Spec 無 AC 定義 | 告知並引導修改 spec |
測試檔案無 @AC 註解 | 嘗試以命名慣例匹配,標記 [Inferred] |
References | 參考
- AC Coverage Assistant Skill
- Core Standard: Acceptance Criteria Traceability
- Related: /coverage (code-level coverage)
- Related: /checkin (quality gates)
API Design Assistant | API 設計助手
Guide API design following REST, GraphQL and gRPC best practices.
引導 API 設計,遵循 REST、GraphQL 和 gRPC 最佳實踐。
Workflow | 工作流程
DEFINE ──► DESIGN ──► VALIDATE ──► DOCUMENT
- Define — Gather requirements, identify resources and operations
- Design — Design endpoints, request/response schemas, error codes
- Validate — Check consistency, naming conventions, versioning
- 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 | 進入路由
| Input | AI Action |
|---|---|
/api-design | 詢問 API 需求和目標資源,進入 DEFINE 階段 |
/api-design <resource> | 以指定資源為目標,進入 DEFINE |
/api-design --graphql | 使用 GraphQL 方法設計 |
Interaction Script | 互動腳本
DEFINE Phase
- 收集 API 需求(目標使用者、資源、操作)
- 確認 API 風格(REST / GraphQL / gRPC)
🛑 STOP: 需求確認後等待使用者確認進入 DESIGN
DESIGN Phase
- 設計端點/schema
- 定義 request/response 格式
- 設計錯誤碼和狀態碼
- 展示設計結果
🛑 STOP: 設計展示後等待使用者確認
VALIDATE Phase
- 檢查命名一致性、RESTful 慣例
- 驗證版本策略
- 展示驗證報告
DOCUMENT Phase
- 生成 API 文件(OpenAPI / GraphQL Schema)
🛑 STOP: 文件生成後等待使用者確認寫入
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| DEFINE | 需求確認後 | 確認進入 DESIGN |
| DESIGN | 設計展示後 | 確認設計方案 |
| DOCUMENT | 文件生成後 | 確認寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法判斷 API 風格 | 列出選項(REST/GraphQL/gRPC),請使用者選擇 |
| 資源命名不符慣例 | 建議修正,展示命名規則 |
Reference | 參考
- Full standard: api-design-assistant
- Core guide: api-design-standards
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:
- Automatically activate ATDD methodology if not already active
- Set current phase to SPECIFICATION-WORKSHOP (defining acceptance criteria)
- Track phase transitions as work progresses
- Show phase indicators in responses (🤝 Workshop, 🧪 Distillation, 💻 Development, 🎬 Demo, ✅ Done)
當調用 /atdd 時:
- 自動啟用 ATDD 方法論(如果尚未啟用)
- 將當前階段設為規格工作坊(定義驗收條件)
- 追蹤階段轉換隨著工作進展
- 在回應中顯示階段指示器(🤝 工作坊、🧪 提煉、💻 開發、🎬 展示、✅ 完成)
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 準則
| Criteria | Description | 描述 |
|---|---|---|
| Independent | Can be developed independently | 可獨立開發 |
| Negotiable | Details can be discussed | 細節可協商 |
| Valuable | Delivers business value | 提供商業價值 |
| Estimable | Can be estimated | 可估算 |
| Small | Fits in one sprint | 一個 Sprint 可完成 |
| Testable | Clear 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 | 進入路由
| Input | AI Action |
|---|---|
/atdd | 詢問使用者故事,進入 🤝 WORKSHOP |
/atdd "user story" | 以指定故事為目標,進入 🤝 WORKSHOP |
/atdd <story-id> | 載入現有故事,判斷進入哪個階段 |
Interaction Script | 互動腳本
🤝 WORKSHOP Phase
- 請使用者描述使用者故事(As a / I want / So that)
- 引導定義驗收條件(Given-When-Then)
- 記錄 Out of Scope 項目
Decision: PO 角色
- IF 使用者是 PO → 直接收集 AC
- IF 使用者是開發者 → AI 模擬 PO 視角提出質疑和補充
- ELSE → 建議邀請 PO 參與,或由 AI 輔助
🛑 STOP: AC 定義完成後展示使用者故事文件,等待確認
🧪 DISTILLATION Phase
- 將 AC 轉換為可執行的測試格式
- 消除歧義
- 展示可執行測試
🛑 STOP: 展示測試後等待使用者(或 PO)簽核
💻 DEVELOPMENT Phase
- 執行驗收測試(預期失敗)
- 使用 BDD/TDD 實作功能
- 迭代直到所有測試通過
🛑 STOP: 所有測試通過後等待使用者確認進入 DEMO
🎬 DEMO Phase
- 展示通過的測試結果
- 展示可運作的功能
- 等待 PO 正式驗收
🛑 STOP: 等待使用者確認 PO 已驗收
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| WORKSHOP | AC 定義後 | 確認使用者故事 |
| DISTILLATION | 測試轉換後 | PO 簽核 |
| DEVELOPMENT | 所有測試通過後 | 確認進入 DEMO |
| DEMO | 功能展示後 | PO 正式驗收 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 使用者故事不符合 INVEST 準則 | 指出哪些準則未滿足,建議修改 |
| PO 不在場 | AI 模擬 PO 視角提問,標記 [Needs PO Confirmation] |
| 驗收測試無法自動化 | 建議手動測試替代方案,產出測試檢查清單 |
| DEVELOPMENT 階段反覆失敗 | 回到 WORKSHOP 重新審視 AC 是否合理 |
Reference | 參考
- Core Standard: acceptance-test-driven-development.md
- Skill: atdd-assistant
- Methodology: atdd.methodology.yaml
- Methodology System: methodology-system
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 | 進入路由
| Input | AI Action |
|---|---|
/audit | 執行完整審計(health + patterns + friction) |
/audit --health | 僅檢查 UDS 安裝完整性 |
/audit --patterns | 僅偵測開發模式 |
/audit --friction | 僅識別摩擦點 |
/audit --report | 生成完整報告(含建議) |
Interaction Script | 互動腳本
- 依模式執行對應的診斷
- 收集分析結果
- 生成報告
Decision: 健康狀態
- IF ERROR 級問題 → 建議執行
uds init或uds check --restore - IF WARNING 級問題 → 列出建議,使用者自行決定
- IF 全部 OK → 展示健康摘要
🛑 STOP: 報告展示後等待使用者決定
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 報告展示後 | 使用者決定採取行動 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| UDS 未安裝 | 建議執行 uds init |
.standards/ 目錄不存在 | 告知 UDS 標準未安裝 |
Reference | 參考
- Full standard: audit-assistant
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 Phase | Pre-Flight Check | On Failure |
|---|---|---|
DISCOVERY | 1. Feature/behavior clearly identified | → Ask user to describe the desired behavior |
| 2. If SDD project: spec exists | → Guide to /sdd | |
FORMULATION | 1. Discovery output exists (examples, edge cases) | → Guide back to DISCOVERY |
| 2. At least one concrete example collected | → Collect examples first | |
AUTOMATION | 1. .feature file exists with scenarios | → Guide to FORMULATION |
| 2. Scenarios follow Given-When-Then format | → Fix scenario format | |
LIVING DOCS | 1. 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:
- Automatically activate BDD methodology if not already active
- Set current phase to DISCOVERY (exploring behavior)
- Track phase transitions as work progresses
- Show phase indicators in responses (🔍 Discovery, 📝 Formulation, 🤖 Automation, 📚 Living Docs)
當調用 /bdd 時:
- 自動啟用 BDD 方法論(如果尚未啟用)
- 將當前階段設為探索(探索行為)
- 追蹤階段轉換隨著工作進展
- 在回應中顯示階段指示器(🔍 探索、📝 制定、🤖 自動化、📚 活文件)
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:
| Role | Focus | 角色 | 關注點 |
|---|---|---|---|
| Business | What & Why | 業務 | 什麼和為什麼 |
| Development | How | 開發 | 如何實現 |
| Testing | What 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 | 進入路由
| Input | AI Action |
|---|---|
/bdd | 詢問要探索的行為,進入 🔍 DISCOVERY |
/bdd "feature description" | 以指定功能為目標,進入 🔍 DISCOVERY |
/bdd <feature-file> | 載入現有 .feature 檔案,判斷進入哪個階段 |
Interaction Script | 互動腳本
🔍 DISCOVERY Phase
- 與使用者討論功能行為
- 收集具體範例和邊界案例
- 以 Three Amigos 視角提問(Business / Dev / Testing)
🛑 STOP: 收集足夠範例後展示摘要,等待確認進入 FORMULATION
📝 FORMULATION Phase
- 將範例轉為 Gherkin 場景(Given-When-Then)
- 使用領域語言(ubiquitous language)
- 展示生成的
.feature內容
Decision: 場景品質
- IF 場景包含實作細節 → 自動抽離,改用業務語言
- IF 場景過於模糊 → 要求更具體的範例
🛑 STOP: 展示 .feature 後等待使用者確認寫入
🤖 AUTOMATION Phase
- 為每個場景實作 step definitions
- 執行場景,確認結果
- 場景內部使用 TDD 循環實作
🛑 STOP: 所有場景通過後等待使用者確認
📚 LIVING DOCS Phase
- 確認所有場景是最新狀態
- 建議文件可分享給利害關係人
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| DISCOVERY | 範例收集完成後 | 確認進入 FORMULATION |
| FORMULATION | .feature 生成後 | 確認寫入 |
| AUTOMATION | 所有場景通過後 | 確認進入 LIVING DOCS |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 使用者要求跳過 DISCOVERY 直接寫場景 | 提醒需要具體範例,但允許 override |
.feature 語法無效 | 自動修正 Gherkin 語法 |
| Step definition 實作失敗 | 報告哪個 step 失敗,嘗試修復,3 次後 STOP |
| 無 BDD 測試框架(Cucumber 等) | 建議安裝,或改用 TDD 方式實作場景邏輯 |
Reference | 參考
- Methodology: bdd.methodology.yaml
- Methodology System: methodology-system
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 集成+透鏡 多評審面板+硬角色反駁 輸出提案
| Phase | Goal | Key Techniques (v3) + BQS gate (v4) | 目標 |
|---|---|---|---|
| PRE-FLIGHT | Prevent AI anchoring | User writes 3 ideas first; no analogy seed; BQS Layer 0 intent (explore/exploit) | 防止錨定 |
| FRAME | Define problem clearly | 5 Whys, HMW, Stakeholder Map; D1 frame purity | 清楚定義問題 |
| DIVERGE | Force viewpoint diversity | Persona ensemble + diversity lenses; BQS Layer 1 D1–D4, hard gate hides D5–D8 | 逼出視角多樣性 |
| CONVERGE | Bias-checked selection | Multi-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) | 降偏誤選擇 |
| OUTPUT | Actionable report | Brainstorm 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 | 技法
| Technique | Best For | 適用場景 |
|---|---|---|
| Persona ensemble | Forced viewpoint diversity (v3 core) | 強制視角多樣性(v3 核心) |
| Diversity lenses | Analogical / reversal / morphological | 突破顯而易見區 |
| Multi-critic panel | Bias-reduced scoring (v3 core) | 降偏誤評分(v3 核心) |
| Devil's Advocate + Steelman | Hard-role rebuttal | 硬角色反駁 |
| 5 Whys / HMW / SCAMPER / Six Hats | Classic 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:
/brainstorm- Structured ideation (this command)/requirement- Write user stories and requirements/sdd- Create specification documents/derive-allor/tdd- Implement with test protection
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI 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
- 請使用者先寫 問題(一句)+3 個初始想法+最不想要的解法類型
- 拒絕「像 X 但給 Y」種子,改寫為底層問題
- BQS Layer 0:宣告本次 explore/exploit 配比與賭注類型(未宣告預設偏 explore)
🛑 STOP: 收到三項輸入前不生成任何想法(--skip-preflight 例外,顯示錨定警告)
FRAME Phase
- 釐清問題陳述(5 Whys 找根因)
- 重構為 HMW 問題;識別利害關係人
- BQS D1 框架純度:問題不得內嵌特定方案或「像 X 給 Y」,須到根因
🛑 STOP: 問題定義後等待使用者確認
DIVERGE Phase (BQS Layer 1 — D1–D4 leading, visible)
- 逐一以預設 persona(領域專家/懷疑者/跨域類比者/成本約束者/使用者代言)思維鏈生成想法
- 分支隔離:生成各 persona 時不互相預覽,全部產完才一起呈現
- 至少套用一個多樣性透鏡(類比/假設反轉/形態矩陣)
- 以多樣性(覆蓋的 persona/透鏡數,D2/D3)而非數量為繼續門檻
- 硬序列閘:D5–D8 在最後一個 persona 產完前不得揭示或評分;CONVERGE critic 不得提前呼叫
- 模型層級(發散側):以 Standard 或更高層級執行——依 core/model-selection.md 的 MS-004/Criterion 2(引用,不複述;不是「最高層級」)
CONVERGE Phase (BQS Layer 2 — D5–D8 on the Recommended Set only)
- 以 3 個獨立評審(工程可行性/使用者影響/策略一致)各自評分後聚合;評審提示以「目標+約束」表達(判準,不是步驟清單——理由見 skill 引用的 core/model-selection.md MS-009),加權公式與逐準則指南為參考格式
- 對推薦集(Agg. Score ≥ 3.5,不限筆數)跑硬角色 Devil's Advocate(論證會失敗)+ Steelman;使用者以 (a)修改/(b)反駁/(c)移除 回應。D4 判官≠產生者,兩軸:(1) 評審在獨立 context(
--enhanced)執行,且 (2) 宣告模型層級(core/model-selection.md 的廠商中立標籤;指名具體廠商模型即違規)——缺任一軸標[degraded]不得 pass - 僅對推薦集套用 D5 接地(外部事實需 file:line/來源、跨級地板;假說免接地)、D6 淨值(解誰問題/真有嗎/不做代價+掛 lagging 欄)、D7 二態證偽(「需先做 X」轉 next-step、不算 fail)、D8 next-step 裁決——四者為判準、不限順序
- Meta 停止規則:維度全綠且再跑一輪推薦集集合成員不變→停;硬上限 2 輪
🛑 STOP: 展示 Brainstorm Report(含 Seeds/爭議區/Judgment Override)後等待使用者決定下一步
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| PRE-FLIGHT 提交前 | 收到使用者三項輸入 |
| 問題定義後 | 確認問題正確 |
| 反駁輪每個反對理由 | 使用者 (a)/(b)/(c) 回應 |
| 報告展示後 | 決定進入 /requirement 或 /sdd |
Error Handling | 錯誤處理
| Error Condition | AI 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 | 參考
- Brainstorm Assistant Skill
- Brainstorm Assistant Guide
- Model Selection — model-level labels for BQS D4 and the divergence side (cited, not restated)
- Requirement Assistant
- Spec-Driven Development
Changelog Assistant | 變更日誌助手
Generate and maintain CHANGELOG.md entries following the Keep a Changelog format.
根據 Keep a Changelog 格式產生和維護 CHANGELOG.md 條目。
Usage | 用法
/changelog
Workflow | 工作流程
- Analyze git log - Read commit history since last release using
git log - Categorize changes - Map commits to changelog categories
- Generate entries - Write user-friendly descriptions for each change
- Update CHANGELOG.md - Insert entries into the [Unreleased] or versioned section
Change Categories | 變更分類
| Category | When to Use | 使用時機 | Commit Types |
|---|---|---|---|
| Added | New features | 新功能 | feat |
| Changed | Modifications to existing features | 修改既有功能 | perf, BREAKING CHANGE |
| Deprecated | Features to be removed | 即將移除的功能 | -- |
| Removed | Removed features | 已移除的功能 | BREAKING CHANGE |
| Fixed | Bug fixes | 錯誤修復 | fix |
| Security | Security patches | 安全性修補 | security |
Entry Format | 條目格式
## [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 | 進入路由
| Input | AI Action |
|---|---|
/changelog | 分析 git log 自上次 release 以來的 commits,生成 changelog 條目 |
Interaction Script | 互動腳本
- 找到最近的 git tag(上次 release)
- 讀取從上次 tag 至今的所有 commits
- 依類型分類(Added / Changed / Fixed / Security 等)
- 轉寫為使用者導向的描述(非開發者語言)
- 展示生成的 changelog 條目
🛑 STOP: 展示條目後等待使用者確認更新 CHANGELOG.md
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| Changelog 條目展示後 | 確認內容正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI 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:
| Action | Description |
|---|---|
| View diff | Show differences between current and original |
| Restore original | Replace with upstream version |
| Keep current | Accept modifications and update hash |
| Skip | Do nothing for this file |
For missing files:
| Action | Description |
|---|---|
| Restore | Download and restore from upstream |
| Remove from tracking | Remove from manifest |
| Skip | Do nothing for this file |
Options | 選項
| Option | Description | 說明 |
|---|---|---|
--summary | Show compact status summary | 顯示精簡狀態摘要 |
--offline | Skip npm registry check | 跳過 npm registry 檢查 |
--diff | Show diff for modified files | 顯示修改檔案的差異 |
--restore | Restore all modified and missing files | 還原所有修改和遺失的檔案 |
--restore-missing | Restore only missing files | 僅還原遺失的檔案 |
--migrate | Migrate 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:
| Symbol | Meaning | 意義 |
|---|---|---|
| ✓ (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 | 狀態指示
| Symbol | Meaning | 意義 |
|---|---|---|
| ✓ (green) | All good | 一切正常 |
| ⚠ (yellow) | Warning, action recommended | 警告,建議採取行動 |
| ✗ (red) | Error, action required | 錯誤,需要採取行動 |
| ○ (gray) | Not installed/configured | 未安裝/配置 |
Common Issues | 常見問題
"Standards not initialized"
- Run
/initto initialize standards
"Update available"
- Run
/updateto get latest version
"Missing files"
- Run
/check --restoreor/updateto restore
"Modified files detected"
- Run
/check --diffto see changes - Run
/check --restoreto reset to original - Or use interactive mode to handle each file
"Skills not installed"
- Run
/updateto install missing Skills - Or run
/config skillsto manage Skills
"Legacy manifest detected"
- Run
uds check --migrateto 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 | 進入路由
| Input | AI Action | AI 行為 |
|---|---|---|
/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 | 互動腳本
- 執行
uds check並解析輸出 - 展示狀態摘要(版本、層級、檔案、Skills、Commands)
Decision: 檢查結果
- IF 全部正常 → 顯示綠色摘要,結束
- IF 有修改/遺失檔案 → 進入互動修復迴圈
- 互動修復迴圈(每個問題檔案):
Decision: 檔案已修改
- 使用者可選:View diff → Restore original → Keep current → Skip
Decision: 檔案遺失
- 使用者可選:Restore → Remove from tracking → Skip
🛑 STOP: 每個問題檔案逐一詢問使用者處理方式
- 所有檔案處理完畢,顯示最終狀態
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 每個問題檔案 | 使用者選擇處理方式 |
| restore 操作前 | 確認還原(批次模式除外) |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 標準未初始化 | 提示執行 /init |
| npm registry 無法連線 | 建議加 --offline 重試 |
| manifest 格式過舊 | 建議執行 --migrate |
| Skills 未安裝 | 建議執行 /update 或 /config skills |
Reference | 參考
Check-in Assistant | 簽入助手
Verify pre-commit quality gates before committing code to ensure codebase stability.
在提交程式碼前驗證品質關卡,確保程式碼庫的穩定性。
Usage | 用法
/checkin
Workflow | 工作流程
- Check git status - Run
git statusandgit diffto understand pending changes - Run tests - Execute
npm test(or project test command) to verify all tests pass - Run linting - Execute
npm run lintto check code style compliance - Verify quality gates - Check each gate against the checklist below
- Report results - Present pass/fail summary and recommend next steps
Quality Gates | 品質關卡
| Gate | Check | 檢查項目 |
|---|---|---|
| Build | Code compiles with zero errors | 編譯零錯誤 |
| Tests | All existing tests pass (100%) | 所有測試通過 |
| Coverage | Test coverage not decreased | 覆蓋率未下降 |
| AC Coverage | AC-to-test coverage ≥ 80% (/ac-coverage) | AC 覆蓋率 ≥ 80% |
| Code Quality | Follows coding standards, no code smells | 符合編碼規範 |
| Security | No hardcoded secrets or vulnerabilities | 無硬編碼密鑰 |
| Documentation | API docs and CHANGELOG updated if needed | 文件已更新 |
| Workflow | Branch naming and commit message correct | 分支和提交格式正確 |
Never Commit When | 禁止提交的情況
- Build has errors | 建置有錯誤
- Tests are failing | 測試失敗
- Feature is incomplete and would break functionality | 功能不完整會破壞現有功能
- Contains debugging code (console.log, print) | 包含除錯程式碼
- Contains commented-out code blocks | 包含被註解的程式碼區塊
Next Steps | 後續步驟
After verification passes, proceed with /commit to create the commit message.
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/checkin | 自動執行所有品質關卡檢查 |
Interaction Script | 互動腳本
- 執行
git status確認有待提交的變更 - 依序檢查每個品質關卡:
- Build → Tests → Coverage → Code Quality → Security → Documentation → Workflow
- 為每個關卡標記 ✅ PASS / ❌ FAIL
- 生成摘要報告
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 Condition | AI Action |
|---|---|
| 無待提交變更 | 告知無變更可檢查 |
| 測試指令執行失敗 | 報告錯誤,建議檢查測試環境 |
| lint 工具未安裝 | 跳過該關卡,標記 ⚠️ SKIP |
References | 參考
- Check-in Assistant Skill
- Core Standard
- AC Coverage Command — AC-to-test traceability analysis
- AC Traceability Standard
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 | 進入路由
| Input | AI Action |
|---|---|
/ci-cd | 偵測現有 CI 配置(.github/workflows/、.gitlab-ci.yml 等),展示狀態或開始設計 |
/ci-cd <platform> | 為指定平台設計管線 |
/ci-cd --optimize | 分析現有管線,提出優化建議 |
/ci-cd <stage> | 聚焦特定階段(build/test/deploy) |
Interaction Script | 互動腳本
- 偵測專案技術棧和現有 CI 配置
- 依據需求設計或優化管線
Decision: 現有配置
- IF 已有 CI 配置 → 分析現狀,建議優化
- IF 無 CI 配置 → 引導從頭設計
- IF
--optimize→ 直接進入優化分析
- 逐階段設計(BUILD→TEST→ANALYZE→DEPLOY→VERIFY)
- 展示完整管線配置
🛑 STOP: 配置展示後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 管線設計完成後 | 確認配置正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法偵測 CI 平台 | 列出支援的平台供選擇 |
| 現有配置語法錯誤 | 報告錯誤位置,建議修正 |
Reference | 參考
- Full standard: ci-cd-assistant
Code Review Assistant | 程式碼審查助手
Perform systematic code review using standardized checklists and comment prefixes.
執行系統性的程式碼審查,使用標準化的檢查清單和評論前綴。
Workflow | 工作流程
- Identify changes - Get diff of files to review
- Apply checklist - Check each category systematically
- Generate report - Output findings with standard prefixes
- Summarize - Provide overall assessment
Review Categories | 審查類別
- Functionality - Does it work correctly?
- Design - Is the architecture appropriate?
- Quality - Is the code clean and maintainable?
- Readability - Is it easy to understand?
- Tests - Is there adequate test coverage?
- Security - Are there any vulnerabilities?
- Performance - Is it efficient?
- Error Handling - Are errors handled properly?
Comment Prefixes | 評論前綴
| Prefix | Meaning | Action |
|---|---|---|
| BLOCKING | Must fix before merge | Required |
| IMPORTANT | Should fix | Recommended |
| SUGGESTION | Nice-to-have | Optional |
| QUESTION | Need clarification | Discuss |
| NOTE | Informational | FYI |
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 | 進入路由
| Input | AI Action |
|---|---|
/code-review | 執行 git diff 取得當前分支所有變更,開始審查 |
/code-review <file> | 僅審查指定檔案 |
/code-review <branch> | 審查指定分支相對於 main 的差異 |
Interaction Script | 互動腳本
- 取得變更內容(git diff / 讀取檔案)
- 逐一套用 8 個審查類別
- 為每個發現標記嚴重度前綴(BLOCKING / IMPORTANT / SUGGESTION / QUESTION / NOTE)
- 生成審查報告
Decision: 發現衝突
- IF 多個發現互相矛盾(如效能 vs 可讀性) → 明確說明取捨,標記為 QUESTION 請使用者決定
- ELSE → 依嚴重度排序呈現
🛑 STOP: 報告生成後展示結果,等待使用者決定處理方式
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 審查報告展示後 | 使用者決定是否修復 BLOCKING 項目 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無變更可審查 | 告知無差異,建議先修改程式碼 |
| 檔案/分支不存在 | 列出可用的檔案或分支 |
| 變更量過大(>500 行) | 建議分批審查,列出建議的分批方式 |
Reference | 參考
- Full standard: code-review-assistant
- Core guide: code-review-checklist
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 助手必須執行以下檢查:
| Check | Command | On Failure |
|---|---|---|
| Staged changes exist | git diff --cached --stat | → Guide user to git add |
| No merge conflicts | grep -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 files | git diff --cached --name-only | grep -E '^\.(standards|claude/skills)/' | → Suggest /audit --friction (advisory) |
Spec Tracking Gate | Spec 追蹤閘門
For feat and fix type commits:
- Check:
ls docs/specs/SPEC-*.md 2>/dev/null— any active specs? - If specs exist: Suggest adding
Refs: SPEC-XXXto commit footer - If no specs and change is significant (>3 files or new API): Suggest creating a spec via
/sdd - Mode: This is advisory (non-blocking) — user can always proceed without a spec reference
對於 feat 和 fix 類型的提交:
- 檢查:是否有活躍的規格?
- 如果有規格:建議在 footer 加入
Refs: SPEC-XXX - 如果沒有規格且變更顯著:建議透過
/sdd建立規格 - 模式:這是建議性的(非阻斷)— 使用者可以不引用規格
Workflow | 工作流程
- Check status - Run
git statusandgit diff --stagedto understand changes - Analyze changes - Determine the type (feat, fix, refactor, etc.) and scope
- Spec tracking assessment - Evaluate whether this change needs a spec (see below)
- Generate message - Create a commit message following the format:
<type>(<scope>): <subject> <body> <footer> - 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 | 提交類型
| Type | When to Use | 使用時機 |
|---|---|---|
feat | New feature | 新功能 |
fix | Bug fix | 修復錯誤 |
refactor | Code refactoring | 重構 |
docs | Documentation | 文件更新 |
style | Formatting | 格式調整 |
test | Tests | 測試相關 |
perf | Performance | 效能優化 |
chore | Maintenance | 維護任務 |
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 | 進入路由
| Input | AI Action | AI 行為 |
|---|---|---|
/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 | 互動腳本
- 執行
git diff --cached --stat確認有 staged 變更 - 執行
git status和git diff --staged了解變更內容 - 判斷 commit 類型(feat/fix/refactor/docs/...)和範圍
Decision: Pre-Flight Check 結果
- IF 無 staged 變更 → 引導使用者
git add,停止 - IF 有合併衝突標記 → 提示先解決衝突,停止
- IF 類型為 feat/fix → 執行測試 + Spec 追蹤評估
- 產生 commit message(subject + body + footer)
- 展示完整 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 後等待使用者確認或修改
- 使用者確認後執行
git commit
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| Pre-Flight 失敗 | 使用者修復問題後重新執行 |
| Message 展示後 | 確認 message 正確,或要求修改 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無 staged 變更 | 顯示 git add 指引,不嘗試 commit |
| 合併衝突存在 | 提示解決衝突,列出衝突檔案 |
| 測試失敗(feat/fix) | 顯示失敗摘要,建議修復後再 commit |
| commit 執行失敗 | 顯示 git 錯誤訊息,不重試 |
Reference | 參考
- Full standard: commit-standards
- Core guide: commit-message-guide
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:
| Category | Options |
|---|---|
| Basic Options | Format, Git Workflow, Merge Strategy, Commit Language, Test Levels |
| AI Tools | Add or remove AI tool integrations |
| Skills | Manage Skills installations (install/update/reinstall declined) |
| Commands | Manage Commands installations |
| Advanced | Adoption Level, Content Mode |
| All | Configure 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 位置選項:
| Option | Path | Description |
|---|---|---|
project | .claude/skills/, .opencode/skill/ | Project-specific (default) |
user | ~/.claude/skills/, ~/.opencode/skill/ | Shared across all projects |
Configuration Types | 設定類型
| Type | Description | 說明 |
|---|---|---|
ai_tools | AI tool integrations | AI 工具整合 |
skills | Skills installations | Skills 安裝管理 |
commands | Commands installations | Commands 安裝管理 |
level | Adoption level (1/2/3) | 採用等級 |
content_mode | Integration file content mode | 整合檔案內容模式 |
format | AI/Human documentation format | AI/人類文件格式 |
workflow | Git workflow strategy | Git 工作流程策略 |
merge_strategy | Merge strategy | 合併策略 |
output_language | Output language | 產出語言 |
test_levels | Test levels to include | 測試層級 |
methodology | Development methodology (experimental, requires -E) | 開發方法論(實驗性) |
all | Configure all options | 設定所有選項 |
Skills Configuration | Skills 配置
When selecting skills type, CLI shows:
- Current Status - Shows installed Skills for each AI tool
- Declined Status - Shows tools where user previously declined Skills
- 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:
- Current Status - Shows installed Commands for each supported tool
- Declined Status - Shows tools where user previously declined Commands
- 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 | 內容模式選項
| Mode | Description | 說明 |
|---|---|---|
standard | Summary + task mapping, AI knows when to read which standard (Recommended) | 摘要 + 任務映射(推薦) |
minimal | Only core rules embedded | 僅內嵌核心規則 |
Effects of Configuration Changes | 設定變更的影響
| Configuration | Effect | 影響 |
|---|---|---|
| AI Tools (add) | Generates new integration files | 產生新的整合檔案 |
| AI Tools (remove) | Deletes integration files | 刪除整合檔案 |
| Skills | Installs/updates Skills to configured paths | 安裝/更新 Skills |
| Commands | Installs/updates Commands to configured paths | 安裝/更新 Commands |
| Level | Updates standards, regenerates integrations | 更新標準,重新產生整合 |
| Content Mode | Regenerates 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
/updateprompts - Use
/config skillsor/config commandsto reinstall declined features - Select "Reinstall declined Skills/Commands" from the menu
之前拒絕的工具不會在 /update 提示中出現。使用 /config skills 或 /config commands 重新安裝。
Options Reference | 選項參考
| Option | Description | 說明 |
|---|---|---|
--type <type> | Configuration type | 配置類型 |
--ai-tool <tool> | Specific AI tool (non-interactive) | 特定 AI 工具(非互動式) |
--skills-location <loc> | Skills install location: project, user | Skills 安裝位置 |
--yes, -y | Skip confirmation prompt | 跳過確認提示 |
-E, --experimental | Enable experimental features | 啟用實驗性功能 |
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action | AI 行為 |
|---|---|---|
/config | 顯示目前狀態 → 詢問配置類型 → 執行 | Show status, ask type, execute |
/config <type> | 直接執行指定類型配置(如 skills、ai_tools) | Execute specific config type |
/config --ai-tool <tool> | 非互動式為特定工具安裝 Skills/Commands | Non-interactive install for tool |
Interaction Script | 互動腳本
- 執行
uds check --summary顯示目前狀態
Decision: 有無指定 type
- IF 指定了 type → 直接執行
uds configure --type <type> - IF 指定了
--ai-tool→ 非互動式執行安裝 - ELSE → 進入互動流程
-
詢問配置類型(AskUserQuestion):
- Basic Options / AI Tools / Skills / Commands / Advanced / All
-
根據選擇執行對應 CLI 命令
Decision: Skills/Commands 配置
- IF 選擇 Skills → 顯示安裝狀態 + 拒絕狀態 → 動作選單
- IF 選擇 Commands → 同上流程
🛑 STOP: 顯示目前狀態後等待使用者選擇配置類型
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 狀態顯示後 | 使用者選擇要配置的類型 |
| Skills/Commands 動作選單 | 使用者選擇安裝/更新/重新安裝 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 標準未初始化 | 提示先執行 /init |
| 無效的 config type | 列出可用類型供選擇 |
| 指定的 AI tool 不支援 | 列出支援的工具清單 |
| 之前拒絕的 Skills/Commands | 提示可透過此命令重新安裝 |
Reference | 參考
Test Coverage Assistant | 測試覆蓋率助手
Analyze test coverage across multiple dimensions and provide actionable recommendations.
多維度分析測試覆蓋率並提供可執行的建議。
Coverage Dimensions | 覆蓋率維度
| Dimension | What it Measures | 測量內容 |
|---|---|---|
| Line | Lines executed | 執行的行數 |
| Branch | Decision paths | 決策路徑 |
| Function | Functions called | 呼叫的函數 |
| Statement | Statements executed | 執行的陳述式 |
8-Dimension Framework | 八維度框架
- Code Coverage - Lines, branches, functions
- Requirement Coverage - All requirements tested
- Risk Coverage - High-risk areas tested
- Integration Coverage - Component interactions
- Edge Case Coverage - Boundary conditions
- Error Coverage - Error handling paths
- Permission Coverage - Access control scenarios
- AI Generation Quality - AI-generated test effectiveness
Workflow | 工作流程
- Run coverage tool - Generate coverage report
- Analyze gaps - Identify untested areas
- Prioritize - Rank by risk and importance
- Recommend tests - Suggest specific tests to add
- Track progress - Monitor coverage over time
Coverage Targets | 覆蓋率目標
| Level | Coverage | Use Case |
|---|---|---|
| Minimum | 60% | Legacy code |
| Standard | 80% | Most projects |
| High | 90% | Critical systems |
| Critical | 95%+ | 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 | |
|---|---|---|
| Level | Code (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 | 進入路由
| Input | AI Action |
|---|---|
/coverage | 偵測測試框架,執行全專案覆蓋率分析 |
/coverage <path> | 僅分析指定模組/路徑 |
/coverage --recommend | 分析後重點輸出測試建議 |
Interaction Script | 互動腳本
- 偵測專案測試框架和覆蓋率工具
- 執行覆蓋率報告
- 解析結果,識別低覆蓋率區域
- 依風險和重要性排序
- 提出具體測試建議
Decision: 覆蓋率結果
- IF 覆蓋率 ≥ 目標 → 展示摘要,標記 ✅
- IF 覆蓋率 < 目標但 ≥ 60% → 展示差距,建議優先補測試的區域
- IF 覆蓋率 < 60% → 警告,建議系統性補強計畫
🛑 STOP: 報告展示後等待使用者決定是否補寫測試
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 覆蓋率報告展示後 | 使用者決定是否補測試 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無測試框架 | 詢問使用者選擇框架 |
| 覆蓋率工具執行失敗 | 報告錯誤,建議手動檢查配置 |
| 指定路徑不存在 | 列出可用路徑 |
Reference | 參考
- Full standard: test-coverage-assistant
- Core guide: testing-standards
- AC coverage: /ac-coverage — requirement-level traceability
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 | 進入路由
| Input | AI Action |
|---|---|
/database | 詢問任務類型(schema 設計 / 遷移規劃 / 查詢優化) |
/database schema | 進入 schema 設計/審查模式 |
/database --migration | 進入遷移規劃模式 |
Interaction Script | 互動腳本
- 確認任務類型和目標
- 分析現有 schema 或遷移檔案
Decision: 任務類型
- IF schema 設計 → 引導正規化、索引設計、關聯定義
- IF 遷移規劃 → 評估風險、產生遷移腳本、規劃回滾
- IF 查詢優化 → 分析慢查詢、建議索引
- 展示設計/計畫結果
🛑 STOP: 結果展示後等待使用者確認
🛑 STOP: 遷移腳本寫入前等待使用者確認
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 設計/計畫展示後 | 確認方案 |
| 遷移腳本生成後 | 確認寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法偵測資料庫類型 | 詢問使用者(PostgreSQL/MySQL/MongoDB 等) |
| 遷移存在資料遺失風險 | 明確警告,要求使用者確認 |
Reference | 參考
- Full standard: database-assistant
- Core guide: database-standards
/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
- Parse the SDD spec and validate it is approved
- Run
/derive-bddto generate Gherkin scenarios - Run
/derive-tddto generate test skeletons - Optionally run
/derive-atddfor acceptance test tables - Generate
DERIVATION-REPORT.mdsummarizing all outputs
Output Files | 輸出檔案
| File | Content | 內容 |
|---|---|---|
features/SPEC-XXX.feature | BDD Gherkin scenarios | BDD Gherkin 場景 |
tests/SPEC-XXX.test.ts | TDD test skeletons | TDD 測試骨架 |
DERIVATION-REPORT.md | Summary with statistics | 摘要與統計 |
Usage | 使用方式
| Command | Purpose | 用途 |
|---|---|---|
/derive-all specs/SPEC-001.md | Full derivation from spec | 從規格完整推演 |
/derive-all | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
Typical SDD Workflow | 典型 SDD 工作流程
/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 | 進入路由
| Input | AI Action |
|---|---|
/derive-all | 列出 status=Approved 的 spec 供選擇 |
/derive-all <spec-file> | 直接對指定 spec 執行完整推演 |
Interaction Script | 互動腳本
- 讀取並驗證 spec(status = Approved)
- 依序執行:
/derive-bdd→/derive-tdd→ 詢問是否需要/derive-atdd
Decision: ATDD 推演
- IF 使用者要求 → 執行
/derive-atdd - ELSE → 跳過 ATDD
🛑 STOP: BDD + TDD 推演完成後,詢問是否需要 ATDD 推演
- 生成
DERIVATION-REPORT.md彙總所有輸出 - 展示報告摘要
🛑 STOP: 展示所有生成檔案清單後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 所有推演完成後 | 確認寫入所有檔案 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| Spec status ≠ Approved | 引導到 /sdd approve |
| 子命令推演失敗 | 報告哪個推演失敗,已成功的仍保留,詢問是否繼續 |
Reference | 參考
- Parent command: /derive
- Core standard: forward-derivation-standards.md
- Sub-commands: /derive-bdd, /derive-tdd, /derive-atdd
/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
- Read the SDD spec and extract acceptance criteria
- Map each AC to an acceptance test table (Given-When-Then columns)
- Generate
acceptance.mdwith test data and expected results - 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 | 使用方式
| Command | Purpose | 用途 |
|---|---|---|
/derive-atdd specs/SPEC-001.md | Derive ATDD from specific spec | 從特定規格推演 ATDD |
/derive-atdd | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
Note: BDD scenarios already serve as executable acceptance tests.
/derive-atddis for specialized manual testing workflows.
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/derive-atdd | 列出 status=Approved 的 spec 供選擇 |
/derive-atdd <spec-file> | 直接從指定 spec 推演 ATDD 表格 |
Interaction Script | 互動腳本
- 讀取 spec,擷取所有 AC
- 將每個 AC 映射為驗收測試表格(Given-When-Then 欄位)
- 為每個 AC 生成多筆測試資料(正向 + 反向 + 邊界值)
- 展示生成的
acceptance.md內容
🛑 STOP: 展示表格後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 驗收測試表格生成後 | 確認內容正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| AC 缺乏具體的輸入/輸出描述 | 標記 [TODO: needs test data],繼續其餘 AC |
| Spec 無 AC | 告知並引導修改 spec |
Reference | 參考
- Parent command: /derive
- Core standard: forward-derivation-standards.md
/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
- Read the SDD spec and extract acceptance criteria
- Map each AC to a Gherkin Scenario (1:1)
- Generate
.featurefile with@SPEC-XXXand@AC-Ntags - Output derivation summary
Output Format | 輸出格式
Feature: [Feature Name]
@SPEC-001 @AC-1
Scenario: [AC-1 description]
Given [context]
When [action]
Then [expected result]
Usage | 使用方式
| Command | Purpose | 用途 |
|---|---|---|
/derive-bdd specs/SPEC-001.md | Derive BDD from specific spec | 從特定規格推演 BDD |
/derive-bdd | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/derive-bdd | 列出 status=Approved 的 spec 供選擇 |
/derive-bdd <spec-file> | 直接從指定 spec 推演 BDD 場景 |
Interaction Script | 互動腳本
- 讀取 spec,擷取所有 AC
- 將每個 AC 映射為一個 Gherkin Scenario(1:1)
- 加入
@SPEC-XXX和@AC-Ntags - 展示生成的
.feature內容
Decision: 輸出位置
- IF 專案有
tests/features/目錄 → 輸出到該目錄 - IF 專案有
features/目錄 → 輸出到該目錄 - ELSE → 詢問使用者輸出位置
🛑 STOP: 展示 .feature 內容後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
.feature 生成後 | 確認內容正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| AC 非 GWT 格式 | 嘗試轉換並標記 [Derived],展示供確認 |
| Spec 無 AC | 告知並引導修改 spec |
| 生成的 Gherkin 語法無效 | 自動修正語法,標記修正處 |
Reference | 參考
- Parent command: /derive
- Core standard: forward-derivation-standards.md
/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
- Read the SDD spec and extract acceptance criteria
- Map each AC to a
describe/itblock with AAA pattern - Generate test file with
[TODO]markers for implementation - 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 | 使用方式
| Command | Purpose | 用途 |
|---|---|---|
/derive-tdd specs/SPEC-001.md | Derive TDD from specific spec | 從特定規格推演 TDD |
/derive-tdd | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/derive-tdd | 列出 status=Approved 的 spec 供選擇 |
/derive-tdd <spec-file> | 直接從指定 spec 推演 TDD 骨架 |
Interaction Script | 互動腳本
- 讀取 spec,擷取所有 AC
- 偵測專案語言和測試框架
Decision: 語言/框架偵測
- IF 找到
vitest.config/jest.config→ 使用對應框架 - IF 找到
pytest.ini/pyproject.toml→ 使用 pytest - IF 無法偵測 → 詢問使用者
- 將每個 AC 映射為
describe/itblock(含 AAA 註解和[TODO]標記) - 展示生成的測試檔案內容
🛑 STOP: 展示測試骨架後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 測試骨架生成後 | 確認內容正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| AC 過於抽象無法轉為測試 | 標記 [TODO: AC needs refinement],繼續其餘 AC |
| 無法偵測語言/框架 | 詢問使用者指定 |
| Spec 無 AC | 告知並引導修改 spec |
Reference | 參考
- Parent command: /derive
- Core standard: forward-derivation-standards.md
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 | 子命令
| Subcommand | Description | Output |
|---|---|---|
all | Full derivation pipeline (BDD + TDD + IT + E2E + ATDD + Contracts) | All formats |
bdd | Generate BDD scenarios only | .feature |
tdd | Generate TDD skeletons only | .test.* |
it | Generate Integration test skeletons | .it.test.* |
e2e | Generate E2E test skeletons | .e2e.test.* |
atdd | Generate ATDD test tables | .md (Markdown tables) |
Options | 選項
| Option | Description | Default |
|---|---|---|
--lang | Target language (ts, python, etc.) | Detected or ts |
--framework | Test framework (vitest, pytest, etc.) | Detected or vitest |
--output-dir | Output directory | ./generated |
--dry-run | Preview output without writing | false |
Workflow | 工作流程
- Read Spec: Analyze the input
SPEC-XXX.mdfile. - Extract AC: Parse all Acceptance Criteria.
- Generate Artifacts:
- BDD: Convert AC to Gherkin
Scenarioformat. - TDD: Create test file skeleton with
describe/itblocks matching ACs. - ATDD: Create a Markdown table with inputs/outputs/pass-fail columns.
- BDD: Convert AC to Gherkin
- 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 | 進入路由
| Input | AI Action |
|---|---|
/derive | 列出 docs/specs/ 中 status=Approved 的 spec,問使用者選擇 spec 和子命令 |
/derive <subcommand> <spec-file> | 直接對指定 spec 執行指定子命令 |
/derive <subcommand> | 執行指定子命令,列出可用 spec 供選擇 |
/derive <spec-file> | 對指定 spec 執行 all(預設子命令) |
Interaction Script | 互動腳本
- 讀取 spec 檔案,驗證 status = Approved
- 擷取所有 AC,確認使用 GWT 格式
Decision: AC 格式
- IF AC 使用 GWT 格式 → 直接推演
- IF AC 不是 GWT 格式 → 嘗試轉換,標記
[Derived],展示轉換結果 - IF AC 無法轉換 → 🛑 STOP,請使用者先修改 spec 中的 AC 格式
🛑 STOP: AC 格式轉換後展示結果,等待使用者確認轉換正確再繼續
- 依子命令分派到
/derive-bdd、/derive-tdd、/derive-it、/derive-e2e、/derive-atdd - 驗證 1:1 對應(每個 AC 恰好一個測試/場景)
- 展示推演摘要
🛑 STOP: 展示生成的測試工件後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| AC 格式轉換後 | 確認轉換結果 |
| 測試工件生成後 | 確認寫入檔案 |
Error Handling | 錯誤處理
| Error Condition | AI 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 | 如果有進行中的工作流程:
- Display active workflow summary (name, phase, progress)
- Suggest resuming: "You have an active {workflow} at phase {phase}. Resume with
/{command}?" - Show the appropriate next command based on current phase
Phase → Next Command Mapping | 階段 → 下一步指令對應:
| Workflow | Current Phase | Suggested Next Command |
|---|---|---|
| SDD | discuss | /sdd create |
| SDD | create | /sdd review |
| SDD | review | /sdd approve |
| SDD | approve | /sdd implement |
| SDD | implement | /sdd verify |
| TDD | red | Write failing test, then run tests |
| TDD | green | Write minimal code to pass |
| TDD | refactor | Clean up, then /tdd for next cycle |
| BDD | discovery | /bdd to formulate scenarios |
| BDD | formulation | Write .feature file |
| BDD | automation | Implement 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 | 快速對照表
| Phase | UDS 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 | 進入路由
| Input | AI Action |
|---|---|
/dev-workflow | 先檢查 .workflow-state/,有活躍工作流程則顯示狀態,否則展示全階段總覽 |
/dev-workflow <phase> | 展示指定階段的詳細指令和說明 |
/dev-workflow <scenario> | 展示指定場景的推薦工作流程(new-feature / bug-fix / refactoring) |
Interaction Script | 互動腳本
- 檢查
.workflow-state/和docs/specs/的活躍狀態 - 依據結果決定展示內容
Decision: 活躍工作流程
- IF 有進行中的 workflow → 顯示狀態摘要,建議 resume 命令
- IF 有活躍 spec → 提示 spec 進度,建議下一步
- ELSE → 展示完整階段總覽或指定內容
Decision: 場景模式
- IF 指定場景(new-feature / bug-fix / refactoring) → 展示該場景的推薦命令序列
- ELSE → 展示總覽表
Stop Points | 停止點
此命令為純查詢/導引,無需停止點。
Error Handling | 錯誤處理
| Error Condition | AI 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 | 評估維度
| Dimension | What to Check | 檢查項目 |
|---|---|---|
| Architecture | Module structure, dependency graph, entry points | 模組結構、相依圖、進入點 |
| Dependencies | Outdated packages, known vulnerabilities, license risks | 過時套件、已知漏洞、授權風險 |
| Test Coverage | Existing test suite, coverage gaps, test quality | 現有測試、覆蓋率缺口、測試品質 |
| Security | npm audit findings, hardcoded secrets, exposed endpoints | 安全稽核、硬編碼密鑰、暴露端點 |
| Technical Debt | TODOs, code duplication, complexity hotspots | TODO 標記、程式碼重複、複雜度熱點 |
Workflow | 工作流程
- Scan project - Read package.json, directory structure, config files
- Analyze architecture - Map modules, dependencies, and data flow
- Check dependencies - Run
npm outdated,npm auditfor health signals - Assess risks - Identify complexity hotspots, missing tests, security issues
- Generate report - Output health score with actionable recommendations
- 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:
/discover- Assess project health (this command)/reverse spec- Reverse engineer existing code to specs/sdd- Write specification for new features/tddor/bdd- Implement with test protection
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/discover | 執行全專案健康評估(所有 5 個維度) |
/discover <area> | 聚焦評估指定功能區域的相關模組 |
Interaction Script | 互動腳本
- 掃描專案結構(package.json、目錄結構、配置檔)
- 逐維度分析(Architecture → Dependencies → Test Coverage → Security → Technical Debt)
- 計算各維度分數和整體分數
- 生成健康報告
Decision: 整體評估
- IF 有 Critical 級問題 → 判定 NO-GO,列出必須修復項目
- IF 有 Warning 級問題 → 判定 CONDITIONAL,列出建議修復項目
- IF 全部 Good → 判定 GO,建議進入下一步
🛑 STOP: 報告展示後等待使用者決定(GO / NO-GO / CONDITIONAL)
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 健康報告展示後 | 使用者決定是否繼續開發 |
Error Handling | 錯誤處理
| Error Condition | AI 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 | 工作流程
- Read config - Load
.usage-docs.yaml(or specified config file) - Scan sources - Read source files, commands, and skill definitions
- Extract content - Parse descriptions, options, examples from source
- Generate docs - Produce output in the configured format
- Write output - Save generated files to the configured output directory
Output Types | 輸出類型
| Type | Description | 說明 |
|---|---|---|
| cheatsheet | Quick reference card with commands and shortcuts | 速查表,列出命令與快捷方式 |
| reference | Comprehensive feature reference with all options | 完整功能參考手冊含所有選項 |
| usage-guide | Step-by-step usage guide for new users | 新手入門的逐步使用指南 |
Examples | 範例
/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 | 進入路由
| Input | AI Action |
|---|---|
/docgen | 尋找預設配置檔 .usage-docs.yaml,找到則使用,否則詢問 |
/docgen <config> | 使用指定配置檔 |
/docgen --format <type> | 僅生成指定格式(cheatsheet / reference / usage-guide) |
Interaction Script | 互動腳本
- 載入配置檔,解析來源和輸出設定
- 掃描來源檔案,擷取描述、選項、範例
- 依配置格式生成文件
- 展示生成的檔案清單和預覽
🛑 STOP: 展示生成結果後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 文件生成後 | 確認內容正確並寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 配置檔不存在 | 建議建立 .usage-docs.yaml,提供模板 |
| 來源目錄為空 | 告知無內容可擷取,列出已掃描的路徑 |
| 輸出目錄不存在 | 自動建立目錄 |
References | 參考
/docs Command | /docs 命令
Manage, write, and generate project documentation.
管理、撰寫和生成專案文件。
Usage | 用法
/docs [subcommand] [options]
Subcommands | 子命令
| Subcommand | Description | 說明 |
|---|---|---|
impact | Analyze documentation impact of recent code changes | 分析程式碼變更對文件的影響 |
translate | Check translation status or translate documents | 檢查翻譯狀態或翻譯文件 |
generate | Generate documentation artifacts (cheatsheets, reference) | 產生文件工件 |
readme | Audit and update README.md | 審計並更新 README.md |
api | Generate API documentation from code | 從程式碼產生 API 文件 |
structure | Check documentation folder structure | 檢查文件目錄結構 |
(none) | Show documentation guide/status | 展示文件狀態總覽 |
Impact Options
Used with /docs impact:
| Option | Description |
|---|---|
--staged | Only 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:
| Option | Description |
|---|---|
<file> | Translate a specific source file |
--lang <lang> | Target language (zh-TW, zh-CN) |
--check | Check translation sync status only (no changes) |
--all | Translate all outdated files |
| (default) | Show translation status summary |
Generate Options
Used with /docs generate:
| Option | Description |
|---|---|
--lang <lang> | Language (en, zh-TW, zh-CN) |
--cheatsheet | Generate cheatsheet only |
--reference | Generate feature reference only |
--check | Check if docs are out of sync |
Examples | 範例
# 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 | 進入路由
| Input | AI 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 流程
- 取得變更清單(
git diff或git diff --staged或git diff <ref>) - 對每個變更的檔案,掃描哪些文件引用了它
- 輸出影響報告,格式:
📋 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 流程
- IF
--check或無參數 → 掃描locales/目錄,比對源檔版本 - 輸出翻譯狀態表:
📋 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)
- IF 指定
<file>或--all→ 讀取源檔和現有翻譯,產生更新的翻譯內容 - 根據
output_language設定決定翻譯語言和風格
🛑 STOP: 展示翻譯結果後等待使用者確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| impact 報告展示後 | 選擇要執行哪些更新 |
| translate 結果展示後 | 確認翻譯內容寫入 |
| generate/readme/api 結果展示後 | 確認寫入 |
Error Handling | 錯誤處理
| Error Condition | AI 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 | 進入路由
| Input | AI Action |
|---|---|
/durable | 詢問工作流程或失敗情境,進入 DETECT |
/durable --checkpoint | 直接進入檢查點策略設計 |
/durable --retry | 直接進入重試策略設計 |
/durable --rollback | 直接進入回滾策略規劃 |
/durable <workflow> | 分析指定工作流程 |
Interaction Script | 互動腳本
DETECT / DIAGNOSE
- 分析工作流程結構和失敗點
- 識別需要持久化的狀態
Decision: 故障類型
- IF 暫時性故障(網路、超時) → 建議重試策略(exponential backoff)
- IF 資料不一致 → 建議檢查點 + 補償交易
- IF 不可逆失敗 → 建議回滾策略
🛑 STOP: 診斷結果展示後等待使用者確認策略方向
RECOVER
- 設計選定的恢復策略
- 展示策略細節和程式碼建議
🛑 STOP: 策略設計後等待使用者確認
VERIFY
- 建議驗證步驟確認恢復成功
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| DIAGNOSE | 診斷結果後 | 確認策略方向 |
| RECOVER | 策略設計後 | 確認實施 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法識別工作流程模式 | 詢問使用者描述工作流程步驟 |
| 多種故障類型並存 | 逐一分析,建議組合策略 |
Reference | 參考
- Full standard: durable-execution-assistant
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 | 選項
| Option | Description | 說明 |
|---|---|---|
<feature-file> | Path to .feature file | .feature 檔案路徑 |
<spec-file> | Path to SPEC-XXX.md file (delegates to /derive e2e) | SDD 規格路徑(委派) |
--analyze | Run 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
.featurefile before classifying — never guess scenario content - MUST detect framework from
package.jsonor existing test files — never assume a framework - MUST use utility functions from
cli/src/utils/e2e-analyzer.jsandcli/src/utils/e2e-detector.jsas 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 | 進入路由
| Input | AI 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 適用性分析
- 讀取
.feature檔案,解析所有 Scenario - 使用分類邏輯(E2E/Integration/Unit keywords + step count)分類每個 Scenario
- 以表格展示分類結果
Decision: 無 E2E 適合的場景
- IF 所有場景都非
e2e-suitable→ 通知使用者,建議使用/tdd或/bdd替代 - IF 部分適合 → 僅處理
e2e-suitable場景,列出跳過的場景及原因
🛑 STOP: 展示分類結果後等待使用者確認繼續
Phase 2: 框架偵測與模式分析
- 偵測專案使用的 E2E 框架(package.json dependencies)
- 掃描既有 E2E 測試目錄,提取 import、helper、編碼慣例
Decision: 多框架偵測
- IF 偵測到多個框架 → 列出選項,詢問使用者選擇
- IF 未偵測到框架 → 詢問使用者指定,或預設使用 Vitest
Phase 3: 骨架生成
- 使用框架模板生成 E2E 測試骨架
- 包含
[TODO]標記、traceability tags(@SPEC-XXX @AC-N) - 包含 fixture/setup 引導(beforeAll/beforeEach)
- 展示生成的程式碼
🛑 STOP: 展示生成的骨架後等待使用者確認寫入
Phase 4: 完成與下一步
- 寫入檔案(經使用者確認)
- 建議下一步操作
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| AC 分析 | 分類結果展示後 | 確認繼續生成 |
| 骨架生成 | 程式碼展示後 | 確認寫入檔案 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
.feature 檔案不存在 | 列出目錄中可用的 .feature 檔案 |
.feature 無 Scenario | 通知使用者,建議先使用 /bdd 撰寫場景 |
輸入為 SPEC-XXX.md | 辨識後委派至 /derive e2e,說明原因 |
| 框架未偵測到 | 詢問使用者選擇框架(Playwright/Cypress/Vitest) |
| 既有 E2E 目錄不存在 | 使用預設模板,不進行模式分析 |
Reference | 參考
- Spec: SPEC-E2E-001
- Skill: e2e-assistant
- Utilities:
cli/src/utils/e2e-analyzer.js,cli/src/utils/e2e-detector.js - Related: /derive, /bdd, /tdd
/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
| Topic | Description | Source |
|---|---|---|
git | Git workflow & branching strategies | skills/git-workflow-guide/ |
testing | Testing pyramid & strategy | skills/testing-guide/ |
errors | Error code design standards | skills/error-code-guide/ |
logging | Structured logging standards | skills/logging-guide/ |
structure | Project structure conventions | skills/project-structure-guide/ |
ai-arch | AI-friendly architecture | skills/ai-friendly-architecture/ |
ai-collab | AI collaboration & anti-hallucination | skills/ai-collaboration-standards/ |
ai-instruct | AI instruction file standards | skills/ai-instruction-standards/ |
Examples
/guide git- Show Git branching and naming conventions/guide testing- Show testing pyramid and best practices/guide structure- Show recommended project folder structure/guide- List all available guides
Implementation Note for AI
When the user invokes /guide [topic]:
- Identify the requested topic.
- Read the corresponding standard/skill file (e.g.,
skills/git-workflow-guide/SKILL.md). - Summarize or present the key information from that file to the user.
- 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 | 進入路由
| Input | AI Action |
|---|---|
/incident | 詢問事故描述和嚴重程度,進入 DETECT |
/incident "description" | 以描述為起點,進入 TRIAGE |
/incident --post-mortem | 直接進入 POST-MORTEM 階段 |
/incident --sev1 | 啟動 SEV1 緊急回應協議 |
Interaction Script | 互動腳本
DETECT / TRIAGE
- 收集事故症狀和影響範圍
- 評估嚴重程度(SEV1-4)
Decision: 嚴重程度
- IF SEV1/SEV2 → 立即列出緊急行動清單,建議通知相關人員
- IF SEV3/SEV4 → 按標準流程排查
🛑 STOP: 嚴重程度評估後等待使用者確認
MITIGATE
- 建議即時緩解措施
- 追蹤緩解狀態
RESOLVE
- 引導根因分析(5 Whys)
- 建議修復方案
🛑 STOP: 修復方案確認後等待使用者確認實施
POST-MORTEM
- 收集時間線、根因、影響
- 生成事後檢討文件
🛑 STOP: 文件生成後等待使用者確認寫入
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| TRIAGE | 嚴重程度評估後 | 確認分級 |
| RESOLVE | 修復方案提出後 | 確認實施 |
| POST-MORTEM | 文件生成後 | 確認寫入 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法判斷嚴重程度 | 列出分級標準,請使用者選擇 |
| 缺乏足夠症狀資訊 | 引導收集更多資訊(日誌、監控、錯誤訊息) |
Reference | 參考
- Full standard: incident-response-assistant
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 Tool | Integration File | Skills Support | Commands Support |
|---|---|---|---|
| Claude Code | CLAUDE.md | ✅ | ❌ |
| Cursor | .cursorrules | ✅ | ❌ |
| Windsurf | .windsurfrules | ✅ | ❌ |
| Cline | .clinerules | ✅ | ❌ |
| GitHub Copilot | .github/copilot-instructions.md | ✅ | ✅ |
| OpenCode | AGENTS.md | ✅ | ✅ |
| Gemini CLI | GEMINI.md | ✅ | ✅ |
| Codex | AGENTS.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 時顯示):
| Option | Description |
|---|---|
| Lean (Recommended) | Reference docs only, Skills provide real-time task guidance |
| Complete | Install all standard files, independent of Skills |
Step 6: Ask Adoption Level | 步驟 6:詢問採用層級
Use AskUserQuestion:
使用 AskUserQuestion:
| Option | Description |
|---|---|
| Level 1: Starter | 6 core standards: commit, anti-hallucination, checkin, etc. |
| Level 2: Professional (Recommended) | Adds testing, Git workflow, error handling - 12 total |
| Level 3: Complete | Includes versioning, logging, SDD - all 16 standards |
Step 7: Ask Standards Format | 步驟 7:詢問標準格式
Use AskUserQuestion:
| Option | Description |
|---|---|
| AI (Compact) | Optimized for AI consumption (Recommended) |
| Human (Detailed) | Readable format for humans |
| Both | Generate 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:
| Option | Description |
|---|---|
| English (Default) | English documentation |
| Traditional Chinese | 繁體中文文件 |
Step 12: Ask Content Mode | 步驟 12:詢問內容模式
Use AskUserQuestion for integration file content:
使用 AskUserQuestion 設定整合檔案內容:
| Option | Description |
|---|---|
| Standard (Recommended) | Summary + task mapping, AI knows when to read which standard |
| Minimal | File 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 | 選項參考
| Option | Description | 說明 |
|---|---|---|
--yes, -y | Non-interactive mode | 非互動模式 |
--level N | Adoption level (1, 2, or 3) | 採用層級 |
--skills-location | marketplace, user, project, or none | Skills 位置 |
--content-mode | standard, full, or minimal | 內容模式 |
--format | ai, human, or both | 格式 |
-E, --experimental | Enable experimental features (methodology) | 啟用實驗性功能 |
See uds init --help for all options.
Adoption Levels | 採用層級
| Level | Name | Standards Count | Description | 說明 |
|---|---|---|---|---|
| 1 | Starter | 6 | Core standards for small projects | 核心標準(小型專案) |
| 2 | Professional | 12 | Adds testing, Git workflow, error handling | 團隊專業品質標準 |
| 3 | Complete | 16 | All 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.jsonfor tracking installation
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action | AI 行為 |
|---|---|---|
/init | 進入互動模式,逐步詢問 13 個配置問題 | Enter interactive mode, 13-step configuration |
/init --yes | 使用所有預設值直接執行 | Execute with all defaults |
/init --level N | 設定採用層級,其餘進入互動或搭配 --yes | Set level, rest interactive or defaults |
/init --level N --yes | 指定層級 + 所有預設值直接執行 | Specified level + all defaults |
Interaction Script | 互動腳本
Decision: 互動 vs 快速模式
- IF
--yes存在 → 使用預設值直接執行,跳過所有 AskUserQuestion - ELSE → 進入 13 步驟互動流程
互動流程(13 步驟)
- 偵測專案 — 自動偵測語言、框架、AI 工具
- AI 工具選擇 — 多選,預選偵測到的工具
- Skills 安裝 — Smart Grouping(1-2 工具合併 / 3+ 工具兩階段)
- Commands 安裝 — Smart Grouping(同上策略)
- 標準範圍 — Lean(建議)或 Complete
- 採用層級 — Level 1/2/3
- 標準格式 — AI / Human / Both
- 標準選項 — Git Workflow、Merge Strategy、Commit Language、Test Levels
- 語言擴展 — 偵測到語言時詢問
- 框架擴展 — 偵測到框架時詢問
- 地區設定 — English / Traditional Chinese
- 內容模式 — Standard / Minimal
- 確認並執行 — 展示摘要,確認後一次執行所有安裝
IMPORTANT: AskUserQuestion 最多 4 個選項。3+ 工具時必須使用 Smart Grouping 兩階段策略。
🛑 STOP: Step 13 展示配置摘要後等待使用者確認再執行安裝
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 配置摘要展示後 | 確認安裝或修改配置 |
偵測到已有 .standards/ | 詢問是否覆寫或跳過 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
已有 .standards/ 目錄 | 提示使用 /update 更新,或確認覆寫 |
| 無法偵測專案語言 | 跳過語言擴展步驟,繼續流程 |
| npm/npx 不可用 | 提示安裝 Node.js >= 18 |
| AskUserQuestion 超過 4 選項 | 使用 Smart Grouping 拆分為多階段 |
Reference | 參考
- CLI documentation:
uds init --help - Adoption guide: ADOPTION-GUIDE.md
- Check command: /check
- Update command: /update
/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
| Output | Description |
|---|---|
TESTPLAN-NNN.md | Ordered journey steps (T-000 reset → T-001 login → T-010 core flows) with personas, environment, and a dependency graph |
*.journey.spec.ts | E2E skeletons aligned to each TESTPLAN step |
Difference from /e2e
/e2egenerates E2E skeletons from individual BDD scenarios./journey-testplans 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 | 進入路由
| Input | AI 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
- 分析專案描述,識別所有使用者角色
- 定義每個角色的 Actor / Role / Key Permissions
Decision: 角色無法從描述判定
- IF 描述中找不到任何角色 → 詢問使用者列舉角色,不得自行臆造
- IF 只識別出單一角色 → 明確告知並詢問是否確實為單角色系統
🛑 STOP: 展示 Persona 清單後等待使用者確認
Phase 2: 設計旅程地圖
- 列出主要業務目標
- 拆解為 T-NNN 步驟群組(T-000 環境重置為 optional)
- 宣告步驟間的依賴鏈
🛑 STOP: 展示依賴圖後等待使用者確認順序
Phase 3: 生成 TESTPLAN
- 依格式輸出
test-plans/TESTPLAN-NNN.md(含 Personas、步驟群組、執行順序依賴圖)
Decision: 檔案已存在
- IF
TESTPLAN-NNN.md已存在 → 詢問覆蓋或遞增編號,不得逕行覆蓋
Phase 4: 生成 E2E 骨架
- 從 TESTPLAN 的 T-NNN 生成
*.journey.spec.ts(含describe.skipIf與共享 state) - 骨架僅含
[TODO]標記,不生成臆測的斷言
🛑 STOP: 產物清單展示後等待使用者決定下一步
分析模式(--analyze)
- 讀取
test-plans/TESTPLAN-NNN.md(若存在) - 掃描
src/e2e/下所有*.journey.spec.ts與*.journey.e2e.test.ts - 比對 TESTPLAN 的 T-NNN 與測試中的 T-NNN 引用
- 輸出 Coverage gap 報告,列出缺乏自動化對應的 T-NNN
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| Persona 清單展示後 | 使用者確認角色定義正確 |
| 依賴圖展示後 | 使用者確認步驟順序 |
| TESTPLAN 檔案已存在時 | 使用者決定覆蓋或遞增編號 |
| 產物清單展示後 | 使用者決定是否補實測試內容 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 未提供專案描述且無既有 TESTPLAN | 詢問專案描述,不得自行假設領域 |
| 專案描述中無法識別任何角色 | 請使用者列舉角色,不得臆造 persona |
--archetype 值不在 A1/A2/A3 | 列出三個原型的適用場景供選擇 |
--analyze 但 test-plans/ 不存在 | 告知無 TESTPLAN 可比對,建議先執行生成模式 |
--analyze 但找不到任何 journey 測試 | 回報覆蓋率為 0 並列出全部 T-NNN,不視為錯誤 |
References | 參考
- Journey Test Assistant Skill
- Related: /e2e (single-scenario E2E skeletons)
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 | 動作
| Action | Description | 說明 |
|---|---|---|
| (none) | Show current methodology status | 顯示當前方法論狀態 |
status | Show current phase and checklist | 顯示當前階段和檢查清單 |
switch <id> | Switch to different methodology | 切換到不同方法論 |
phase [name] | Show or change current phase | 顯示或變更當前階段 |
checklist | Show current phase checklist | 顯示當前階段檢查清單 |
skip | Skip current phase (with warning) | 跳過當前階段(會有警告) |
list | List available methodologies | 列出可用方法論 |
create | Create 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 | 相關命令
| Command | System | Description |
|---|---|---|
/sdd | A: SDD | Start SDD spec proposal |
/derive-all | A: SDD | Generate tests from spec |
/bdd | B: Double-Loop TDD | Start BDD outer loop |
/tdd | B: Double-Loop TDD | Start TDD inner loop |
/atdd | Input (both) | Start ATDD workshop |
/config methodology | - | Configure methodology settings |
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action | AI 行為 |
|---|---|---|
/methodology | 顯示當前方法論狀態和 checklist | Show 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 | 顯示當前階段的 checklist | Show phase checklist |
/methodology skip | 跳過當前階段(含警告) | Skip phase with warning |
/methodology list | 列出所有可用方法論 | List available methodologies |
/methodology create | 啟動自訂方法論建立精靈 | Start creation wizard |
Interaction Script | 互動腳本
Status / Checklist
- 讀取
.standards/manifest.json中的 methodology 配置 - 顯示狀態面板(方法論、階段、checklist 進度)
Switch
- 檢查是否有未提交變更(
git status)
Decision: 未提交變更
- IF 有未提交變更 → 顯示警告,提供 4 選項:Commit first / Stash / Switch anyway / Cancel
- IF 無變更 → 直接切換
🛑 STOP: 有未提交變更時等待使用者選擇處理方式
- 更新 manifest 中的 active methodology
- 顯示切換結果和新方法論的第一個階段
Skip
- 檢查當前 checklist 未完成項目
- 顯示警告(含已跳過次數)
🛑 STOP: 顯示跳過警告後等待使用者確認
Decision: 跳過限制
- IF 已達跳過上限(skipLimit) → 強制顯示嚴重警告
- ELSE → 記錄跳過,進入下一階段
Create
- 啟動互動式精靈,引導使用者定義自訂方法論
🛑 STOP: 定義完成後展示方法論結構,等待確認寫入
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| Switch 有未提交變更 | 使用者選擇處理方式 |
| Skip 確認 | 使用者確認跳過 |
| Create 完成 | 使用者確認寫入自訂方法論 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 方法論未啟用 | 提示執行 /methodology switch <id> |
| 指定的方法論不存在 | 列出可用方法論(/methodology list) |
| 指定的階段在當前方法論中不存在 | 列出可用階段 |
| manifest 無 methodology 配置 | 提示透過 /config methodology 啟用 |
Reference | 參考
- Methodology System Skill - Full skill documentation
- Runtime Guide - AI behavior specification
- Create Custom - Custom methodology guide
Version History | 版本歷史
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-25 | Update to reflect two independent systems architecture |
| 1.0.0 | 2026-01-12 | Initial /methodology command |
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 | 進入路由
| Input | AI Action |
|---|---|
/metrics | 執行全面指標分析 |
/metrics --quality | 僅分析程式碼品質指標 |
/metrics --debt | 僅分析技術債 |
/metrics --test | 僅分析測試指標 |
/metrics <path> | 分析指定模組 |
Interaction Script | 互動腳本
- 偵測專案結構和可用工具
- 收集指標資料(git log、測試覆蓋率、程式碼複雜度)
- 分析趨勢和異常
- 生成報告
🛑 STOP: 報告展示後等待使用者決定是否採取行動
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 報告展示後 | 使用者決定後續行動 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無法執行覆蓋率工具 | 跳過該指標,報告可用的其他指標 |
| git 歷史不足以分析趨勢 | 僅報告當前快照,標記趨勢為 N/A |
Reference | 參考
- Full standard: metrics-dashboard-assistant
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 | 進入路由
| Input | AI Action |
|---|---|
/migrate | 詢問遷移目標,進入 ASSESS |
/migrate --assess | 直接執行範圍和風險評估 |
/migrate "target" | 以指定目標進入 ASSESS |
/migrate --deps | 僅分析相依套件升級 |
/migrate --rollback | 規劃回滾策略 |
Interaction Script | 互動腳本
ASSESS Phase
- 分析現有程式碼和相依性
- 評估風險矩陣(breaking changes、資料遷移、API 變更)
- 展示評估報告
🛑 STOP: 評估報告後等待使用者決定是否繼續
PLAN Phase
- 制定遷移計畫(分階段步驟)
- 定義回滾策略
🛑 STOP: 計畫確認後等待使用者確認
MIGRATE Phase
- 逐步執行遷移
- 每個步驟後驗證
🛑 STOP: 每個主要步驟完成後等待確認
VERIFY Phase
- 執行測試確認遷移成功
- 生成驗證報告
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| ASSESS | 評估報告後 | 決定是否繼續 |
| PLAN | 計畫制定後 | 確認計畫 |
| MIGRATE | 每個主要步驟後 | 確認繼續 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 遷移步驟失敗 | 建議回滾到上一個檢查點 |
| 相依性衝突 | 列出衝突,建議解決方案 |
| 測試失敗 | 報告失敗,建議修復後重試 |
Reference | 參考
- Full standard: migration-assistant
Observability Assistant | 可觀測性助手
See SKILL.md for full documentation.
詳見 SKILL.md。
AI Agent Behavior | AI 代理行為
Follows AI Command Behavior Standards
Entry Router | 進入路由
| Input | AI Action |
|---|---|
/observability | 詢問目標服務,進行整體可觀測性評估 |
/observability --checklist | 直接執行可觀測性檢查清單 |
/observability --maturity | 執行成熟度評估並給出改善建議 |
/observability --alerting | 進入告警規則設計與審查流程 |
/observability <service> | 針對指定服務進行可觀測性分析 |
Interaction Script | 互動腳本
- 確認目標服務與現有可觀測性工具(Prometheus、Grafana、Datadog 等)
- 依選定模式執行評估或設計流程
- 展示現況分析與缺口報告
Decision: 可觀測性缺口
- IF 缺少 Metrics → 建議關鍵指標清單(RED/USE method)
- IF 缺少 Tracing → 建議分散式追蹤導入步驟
- IF 缺少 Logging → 建議結構化日誌規範
- IF 告警規則不完整 → 建議補齊 SLO-based alerting
🛑 STOP: 缺口分析完成後等待使用者確認優先補齊項目
Stop Points | 停止點
| Stop Point | 等待內容 |
|---|---|
| 現況評估報告後 | 使用者確認分析正確性 |
| 改善建議展示後 | 使用者決定優先實施項目 |
Error Handling | 錯誤處理
| Error Condition | AI 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 | 進入路由
| Input | AI Action |
|---|---|
/pr | 檢查當前分支狀態,詢問建立或審查 PR |
/pr create | 分析當前分支差異,建立 PR |
/pr --template | 使用 PR 模板建立 |
/pr review <number> | 審查指定 PR |
Interaction Script | 互動腳本
CREATE
- 確認當前分支和目標分支
- 分析 commits,生成 PR title 和 description
- 展示 PR 內容預覽
🛑 STOP: PR 內容確認後等待使用者確認建立
REVIEW
- 取得 PR 差異
- 執行程式碼審查(套用
/code-review標準) - 展示審查結果
🛑 STOP: 審查結果展示後等待使用者決定
Stop Points | 停止點
| Phase | Stop Point | 等待內容 |
|---|---|---|
| CREATE | PR 內容預覽後 | 確認建立 |
| REVIEW | 審查結果後 | 決定後續行動 |
Error Handling | 錯誤處理
| Error Condition | AI Action |
|---|---|
| 無遠端分支 | 建議先 push |
| PR 已存在 | 展示現有 PR,詢問是否更新 |
| CI 檢查失敗 | 列出失敗項目,建議修復 |
Reference | 參考
- Full standard: pr-automation-assistant
Agents 5
Code Architect Agent
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
| Criterion | Description | Weight |
|---|---|---|
| Scalability | Can it handle growth? | High |
| Maintainability | Easy to modify and extend? | High |
| Testability | Easy to test in isolation? | Medium |
| Performance | Meets performance requirements? | Medium |
| Security | Secure by design? | High |
| Simplicity | Avoids unnecessary complexity? | Medium |
Common Patterns I Recommend
| Pattern | Use Case | Trade-offs |
|---|---|---|
| Layered Architecture | Traditional apps, clear separation | Can become rigid |
| Microservices | Large teams, independent scaling | Operational complexity |
| Event-Driven | Async processing, decoupling | Debugging difficulty |
| CQRS | Read/write optimization | Complexity overhead |
| Hexagonal | Domain-centric, testable | Learning 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:
- Create architecture proposal spec
- Get stakeholder review
- 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:
- Auth Service - Token issuance and validation
- User Service - User profile management
- 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
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
| 1.0.0 | 2026-01-20 | Initial release |
License
This agent is released under CC BY 4.0.
Source: universal-dev-standards
Documentation Writer Agent
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 invalidNetworkError- 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:
| Option | Type | Required | Description |
|---|---|---|---|
secret | string | Yes | JWT signing secret |
expiresIn | string | No | Token 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
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
| 1.0.0 | 2026-01-20 | Initial release |
License
This agent is released under CC BY 4.0.
Source: universal-dev-standards
Code Reviewer Agent
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
| Prefix | Meaning | Required Action |
|---|---|---|
| ❗ BLOCKING | Must fix before merge | Required |
| ⚠️ IMPORTANT | Should fix | Strongly recommended |
| 💡 SUGGESTION | Nice-to-have | Optional |
| ❓ QUESTION | Need clarification | Discussion needed |
| 📝 NOTE | FYI, no action needed | Informational |
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)
-
Password stored in plain text (
auth.js:34)- Must use bcrypt or similar hashing
-
Missing CSRF protection (
login.js:67)- Add CSRF token validation
⚠️ IMPORTANT (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
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
| 1.0.0 | 2026-01-20 | Initial release |
License
This agent is released under CC BY 4.0.
Source: universal-dev-standards
Specification Analyst Agent
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
| Type | Description | Example |
|---|---|---|
| Functional | What the system should do | "Users can reset password" |
| Non-Functional | Quality attributes | "Page loads in < 2 seconds" |
| Business Rules | Domain constraints | "Orders over $100 get free shipping" |
| Technical | Implementation constraints | "Must use PostgreSQL" |
INVEST Criteria for User Stories
| Criterion | Question | Good Example |
|---|---|---|
| Independent | Can be developed separately? | ✅ Self-contained feature |
| Negotiable | Details can be discussed? | ✅ Flexible implementation |
| Valuable | Delivers user value? | ✅ Clear benefit stated |
| Estimable | Can be sized? | ✅ Clear scope |
| Small | Fits in a sprint? | ✅ 1-5 days of work |
| Testable | Can 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:
| Level | Meaning | Action |
|---|---|---|
| [Confirmed] | Verified in code/docs | Can implement directly |
| [Inferred] | Logical deduction | Validate with stakeholder |
| [Assumption] | Based on patterns | Must clarify before implementing |
| [Unknown] | Cannot determine | Research 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
| Rule | Source | Certainty |
|---|---|---|
| Minimum order $10 | checkout.js:89 | Confirmed |
| Free shipping > $50 | shipping.js:23 | Confirmed |
| Max 99 of same item | validator.js:45 | Inferred |
Gaps Identified
- [Unknown] What happens if payment fails mid-checkout?
- [Assumption] Guest checkout may be supported (code suggests but not clear)
Recommendations
- Document guest checkout flow
- Add spec for payment failure scenarios
- Clarify max quantity rule with product team
Version History
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
| 1.0.0 | 2026-01-20 | Initial release |
License
This agent is released under CC BY 4.0.
Source: universal-dev-standards
Test Specialist Agent
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
| Level | Scope | Speed | Isolation | Coverage Target |
|---|---|---|---|---|
| Unit | Single function/method | Fast (<10ms) | Complete | 70% |
| Integration | Component interactions | Medium (<1s) | Partial | 20% |
| E2E | User workflows | Slow (>1s) | None | 7-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
| Dimension | Description | Target |
|---|---|---|
| Line Coverage | Lines executed | >80% |
| Branch Coverage | Decision paths taken | >75% |
| Function Coverage | Functions called | >90% |
| Statement Coverage | Statements 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:
-
Unit Tests (70%)
- Payment validation logic
- Amount calculations
- Currency conversion
- Error handling
-
Integration Tests (20%)
- Payment gateway integration
- Database transaction handling
- Event publishing
-
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
| Version | Date | Changes |
|---|---|---|
| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
| 1.0.0 | 2026-01-20 | Initial 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