universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bin/uds.js

@@ -76,6 +76,8 @@ program
   .option('--locale <locale>', 'Locale extension (zh-tw)')
   .option('--skills-location <location>', 'Skills location (marketplace, user, project, none) [default: marketplace]')
   .option('--content-mode <mode>', 'Content mode for integration files (minimal, index, full) [default: index]')
+  .option('--agents-md', 'Generate AGENTS.md universal summary')
+  .option('--no-agents-md', 'Skip AGENTS.md generation')
   .option('-y, --yes', 'Use defaults, skip interactive prompts')
   .option('-E, --experimental', 'Enable experimental features (methodology)')
   .action(initCommand);
@@ -112,7 +114,7 @@ program
 
 program
   .command('check')
-  .description('Check adoption status of current project')
+  .description('Check file integrity and adoption status (quick validation). For deep health diagnosis, use "uds audit"')
   .option('-s, --standard <id>', 'Validate against a specific standard physical spec')
   .option('--json', 'Output result in JSON format')
   .option('--summary', 'Show compact status summary (for use by other commands)')
@@ -172,7 +174,7 @@ program
 
 program
   .command('audit')
-  .description('Audit UDS installation and collect feedback')
+  .description('Deep health diagnosis with pattern detection and feedback (strategic). For quick file check, use "uds check"')
   .option('--health', 'Health check only')
   .option('--patterns', 'Pattern detection only')
   .option('--friction', 'Friction detection only')
@@ -197,7 +199,7 @@ program
 // Spec command with subcommands (Vibe Coding)
 const specCommand = program
   .command('spec')
-  .description('Manage micro-specs for vibe coding');
+  .description('Manage lightweight micro-specs for vibe coding. For full spec lifecycle with review, use "/sdd"');
 
 specCommand
   .command('create <intent>')

package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml

@@ -0,0 +1,178 @@
+# Acceptance Criteria Traceability Standards - AI Optimized
+# Source: core/acceptance-criteria-traceability.md
+
+standard:
+  id: acceptance-criteria-traceability
+  name: Acceptance Criteria Traceability
+  description: AC-to-test traceability matrix, coverage calculation, and spec generation quality rules
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-18"
+    source: core/acceptance-criteria-traceability.md
+    references:
+      - "ISO/IEC/IEEE 29119-3 (Test Documentation — Traceability Matrix)"
+      - "IEEE 830 (Software Requirements Specification — Traceability)"
+      - "ISTQB Foundation (Requirements-based testing)"
+      - "INVEST Principles (Acceptance criteria quality)"
+
+  traceability_matrix:
+    description: Standard format for tracking AC to test relationships
+    fields:
+      - name: AC-ID
+        required: true
+        description: Unique identifier from specification (e.g., AC-1)
+      - name: Test File
+        required: conditionally
+        description: Path to test file (required if covered)
+      - name: Test Name
+        required: conditionally
+        description: Name of test case or describe block (required if covered)
+      - name: Status
+        required: true
+        description: "Coverage status: covered, partial, uncovered"
+      - name: Notes
+        required: false
+        description: Additional context (blockers, dependencies)
+
+    linking_convention:
+      description: Tests must reference source AC using standard annotations
+      annotations:
+        - "@AC AC-N — in test name or comment"
+        - "@SPEC SPEC-XXX — in test name or comment"
+        - "describe('AC-N: description') — in test structure"
+
+  coverage_status:
+    definitions:
+      - status: covered
+        symbol: "✅"
+        definition: AC is fully tested
+        criteria: All conditions in AC have corresponding test assertions
+
+      - status: partial
+        symbol: "⚠️"
+        definition: AC is partially tested
+        criteria: Some conditions tested, but edge cases or paths missing
+
+      - status: uncovered
+        symbol: "❌"
+        definition: AC has no tests
+        criteria: No test case references this AC
+
+    calculation:
+      formula: "AC Coverage % = (covered_count + partial_count × 0.5) / total_ac_count × 100"
+      note: Partial counts as 0.5 for coverage calculation
+
+  quality_thresholds:
+    defaults:
+      - name: Minimum AC Coverage
+        value: 100
+        enforcement: Required for production release
+      - name: Minimum for Check-in
+        value: 80
+        enforcement: Required for feature branch merge
+      - name: Warning Level
+        value: 60
+        enforcement: Triggers coverage warning
+
+    configurable: true
+    config_example:
+      acCoverage:
+        minimum: 100
+        checkinMinimum: 80
+        warningLevel: 60
+        partialWeight: 0.5
+
+  spec_generation_quality:
+    description: Rules for automatically generating specifications from PRD/user stories
+    ac_quality_criteria:
+      - criterion: Specific
+        description: AC describes concrete, observable behavior
+        validation: No vague terms like "should work well"
+
+      - criterion: Measurable
+        description: AC has quantifiable or verifiable outcome
+        validation: Contains expected values, states, or behaviors
+
+      - criterion: Achievable
+        description: AC is technically feasible
+        validation: References known APIs, data, or capabilities
+
+      - criterion: Relevant
+        description: AC relates to feature purpose
+        validation: Maps to user need or business requirement
+
+      - criterion: Testable
+        description: AC can be verified by a test
+        validation: Can be expressed as Given-When-Then
+
+    io_contract:
+      input_types:
+        - type: PRD
+          required_fields: Title, Description, User Stories
+        - type: User Story
+          required_fields: As a / I want / So that
+        - type: Feature Brief
+          required_fields: Feature name, Goals, Constraints
+
+      output_requirements:
+        - section: SPEC ID
+          required: true
+        - section: Title
+          required: true
+        - section: Description
+          required: true
+        - section: Acceptance Criteria
+          required: true
+          format: Numbered list (AC-1, AC-2, ...)
+        - section: AC Format
+          required: true
+          format: Given-When-Then or structured bullet
+        - section: Testability Flag
+          required: true
+          format: Each AC marked as testable/not-testable
+
+      validation_rules:
+        - "AC count >= 1"
+        - "No duplicate AC descriptions"
+        - "Happy path + at least 1 error/edge case"
+        - "100% of AC must be testable"
+        - "Each AC links back to source requirement"
+
+  rules:
+    - id: annotate-tests
+      trigger: writing tests for a specification
+      instruction: Always annotate tests with AC-ID and SPEC-ID using standard annotations
+      priority: required
+
+    - id: honest-status
+      trigger: reporting AC coverage
+      instruction: Use honest status classification (covered/partial/uncovered); never inflate coverage
+      priority: required
+
+    - id: track-all-ac
+      trigger: creating traceability matrix
+      instruction: Include ALL AC from specification, even uncovered ones
+      priority: required
+
+    - id: testable-ac
+      trigger: generating or reviewing specifications
+      instruction: Ensure all AC are testable; flag non-testable AC for revision
+      priority: required
+
+    - id: coverage-gate
+      trigger: before check-in or merge
+      instruction: Verify AC coverage meets project threshold before allowing commit
+      priority: recommended
+
+    - id: spec-quality
+      trigger: generating specifications automatically
+      instruction: Validate generated AC against SMART criteria and testability
+      priority: required
+
+related_standards:
+  - forward-derivation-standards.md
+  - spec-driven-development.md
+  - testing-standards.md
+  - checkin-standards.md
+  - test-governance.md

package/bundled/ai/standards/agent-dispatch.ai.yaml

@@ -0,0 +1,69 @@
+# Agent Dispatch & Parallel Coordination - AI Optimized
+# Source: core/agent-dispatch.md
+# Inspired by Superpowers dispatching-parallel-agents + subagent-driven-development (MIT)
+
+standard:
+  id: agent-dispatch
+  name: Agent Dispatch & Parallel Coordination
+  description: 子代理派遣與並行協調標準
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/agent-dispatch.md
+    description: 子代理派遣、並行協調與狀態回報標準
+    inspired_by: superpowers/subagent-driven-development
+
+  guidelines:
+    - "派遣前必須識別獨立域（無共享狀態 → 可並行）"
+    - "每個代理的 prompt 必須 Focused（單一問題域）、Self-contained（完整上下文）、Specific output（明確回報格式）"
+    - "代理必須回報明確狀態：DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED"
+    - "並行代理返回後必須檢查檔案衝突"
+    - "所有代理完成後必須跑完整測試套件驗證整合"
+
+  status_protocol:
+    - status: DONE
+      description: "任務完成，無問題"
+      orchestrator_action: "繼續後續任務"
+    - status: DONE_WITH_CONCERNS
+      description: "任務完成，但有疑慮需記錄"
+      orchestrator_action: "記錄 concerns 到報告，繼續後續任務"
+    - status: NEEDS_CONTEXT
+      description: "需要更多上下文才能完成"
+      orchestrator_action: "注入額外 context，重新派遣（不計為 retry）"
+    - status: BLOCKED
+      description: "無法完成，需要人工介入或升級處理"
+      orchestrator_action: "嘗試升級模型或拆分任務"
+
+  prompt_structure:
+    - principle: Focused
+      description: "每個代理只處理單一問題域"
+    - principle: Self-contained
+      description: "prompt 包含完整執行所需的上下文"
+    - principle: Specific_output
+      description: "明確定義期望的回報格式"
+
+  rules:
+    - id: AD-001
+      trigger: "多個代理編輯相同檔案"
+      action: "標記衝突，需要人工或自動合併"
+      priority: critical
+    - id: AD-002
+      trigger: "代理回報 BLOCKED"
+      action: "嘗試升級模型等級再試一次"
+      priority: high
+    - id: AD-003
+      trigger: "所有並行代理完成"
+      action: "跑完整測試套件驗證整合"
+      priority: high
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查代理派遣是否遵循獨立域識別、prompt 三原則、狀態協定"
+  checks:
+    - "並行代理是否在獨立域上工作（無共享檔案）"
+    - "代理 prompt 是否包含完整上下文"
+    - "代理是否回報標準化狀態碼"
+    - "並行完成後是否執行整合測試"

package/bundled/ai/standards/ai-command-behavior.ai.yaml

@@ -0,0 +1,45 @@
+# AI Command Behavior Standards (AI-Optimized)
+# Source: core/ai-command-behavior.md
+
+id: ai-command-behavior
+meta:
+  version: "1.0.0"
+  updated: "2026-03-24"
+  source: core/ai-command-behavior.md
+  description: Standard structure for specifying AI Agent runtime behavior in command/skill definition files
+
+rules:
+  - id: behavior-section
+    trigger: creating or modifying command definition files
+    instruction: Include an "AI Agent Behavior" section with four subsections - Entry Router, Interaction Script, Stop Points, Error Handling
+    priority: recommended
+
+  - id: entry-router
+    trigger: command supports multiple invocation patterns
+    instruction: Define a decision table mapping each invocation pattern to a specific AI action. The "no arguments" case MUST always be defined
+    priority: required
+
+  - id: interaction-script
+    trigger: command requires multi-step AI interaction
+    instruction: Use mixed granularity - precise IF/THEN for decision points, numbered lists for general steps
+    priority: recommended
+
+  - id: stop-points
+    trigger: command involves file writes, irreversible operations, or phase completions
+    instruction: Mark explicit stop points with 🛑 STOP markers. Never rely on AI judgment for when to pause
+    priority: required
+
+  - id: error-handling
+    trigger: command has prerequisites or can encounter unexpected states
+    instruction: Define error conditions and AI actions. Never silently skip failures. Stop and ask when uncertain
+    priority: required
+
+  - id: applicability
+    trigger: evaluating whether a command needs behavior definition
+    instruction: Multi-phase workflows and multi-invocation commands require full definition. Single-action and pure-query commands do not
+    priority: recommended
+
+related_standards:
+  - ai-instruction-standards
+  - ai-agreement-standards
+  - anti-hallucination

package/bundled/ai/standards/api-design-standards.ai.yaml

@@ -0,0 +1,192 @@
+# API Design Standards - AI Optimized
+# Source: core/api-design-standards.md
+
+standard:
+  id: api-design
+  name: API Design Standards
+  description: Comprehensive API design guidelines for REST, GraphQL, and gRPC
+  guidelines:
+    - "Use nouns (plural, kebab-case) for resource URLs"
+    - "Follow RFC 7807 Problem Details for error responses"
+    - "Use cursor-based pagination for large datasets"
+    - "Version APIs via URL path (/v1/)"
+    - "Always require HTTPS"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-18"
+    source: core/api-design-standards.md
+    description: Comprehensive API design guidelines for REST, GraphQL, and gRPC
+
+  rest_principles:
+    resource_naming:
+      use_nouns: true
+      use_plural: true
+      case: kebab-case
+      max_nesting: 2
+      examples:
+        correct: ["/users", "/user-profiles", "/users/123/orders"]
+        incorrect: ["/getUsers", "/user_profiles", "/users/123/orders/456/items/789"]
+    http_verbs:
+      GET: {purpose: "Retrieve", body: false, idempotent: true, safe: true}
+      POST: {purpose: "Create", body: true, idempotent: false, safe: false}
+      PUT: {purpose: "Full replace", body: true, idempotent: true, safe: false}
+      PATCH: {purpose: "Partial update", body: true, idempotent: false, safe: false}
+      DELETE: {purpose: "Remove", body: optional, idempotent: true, safe: false}
+    status_codes:
+      success:
+        200: "OK — GET, PUT, PATCH success"
+        201: "Created — POST success (include Location header)"
+        202: "Accepted — async processing"
+        204: "No Content — DELETE success"
+      client_error:
+        400: "Bad Request — malformed request"
+        401: "Unauthorized — missing/invalid auth"
+        403: "Forbidden — insufficient permissions"
+        404: "Not Found — resource does not exist"
+        409: "Conflict — state conflict"
+        422: "Unprocessable Entity — validation error"
+        429: "Too Many Requests — rate limited"
+      server_error:
+        500: "Internal Server Error"
+        502: "Bad Gateway"
+        503: "Service Unavailable"
+        504: "Gateway Timeout"
+
+  versioning_strategies:
+    recommended: url_path
+    options:
+      url_path: {example: "/v1/users", pros: "explicit, cacheable", cons: "URL pollution"}
+      header: {example: "Accept-Version: v1", pros: "clean URLs", cons: "hidden, harder to test"}
+      query_param: {example: "?v=1", pros: "easy to add", cons: "caching issues"}
+    lifecycle:
+      current: "Full support, new features"
+      supported: "6-12 months, bug/security fixes only"
+      deprecated: "3-6 months notice, sunset header"
+      retired: "Return 410 Gone"
+
+  pagination:
+    strategies:
+      offset: {best_for: "Simple lists, UI page numbers", default_limit: 20, max_limit: 100}
+      cursor: {best_for: "Real-time feeds, large datasets", consistent: true}
+      keyset: {best_for: "Sorted large datasets", performant: true}
+    standard_fields:
+      offset: [page, limit, totalCount, totalPages]
+      cursor: [limit, cursor, hasMore]
+
+  authentication:
+    methods:
+      api_key: {use_case: "Server-to-server", complexity: low, security: medium}
+      oauth2: {use_case: "Third-party access", complexity: high, security: high}
+      jwt_bearer: {use_case: "Stateless auth, microservices", complexity: medium, security: high}
+      mtls: {use_case: "Service mesh, zero-trust", complexity: high, security: very_high}
+    jwt_rules:
+      algorithm: "RS256 or ES256 (asymmetric)"
+      access_token_ttl: "15 min max"
+      refresh_token_ttl: "7-30 days"
+      never: [sensitive_data_in_payload, symmetric_for_multi_party]
+
+  rate_limiting:
+    headers:
+      - "X-RateLimit-Limit: max requests in window"
+      - "X-RateLimit-Remaining: requests left"
+      - "X-RateLimit-Reset: unix timestamp of reset"
+      - "Retry-After: seconds to wait (on 429)"
+    tiers:
+      free: "100/hour"
+      basic: "1,000/hour"
+      pro: "10,000/hour"
+      enterprise: "custom"
+    strategies: [fixed_window, sliding_window, token_bucket, leaky_bucket]
+
+  error_format:
+    standard: "RFC 7807 Problem Details"
+    required_fields:
+      type: "URI reference to error documentation"
+      title: "Short, human-readable summary"
+      status: "HTTP status code"
+      detail: "Specific explanation of this occurrence"
+    optional_fields:
+      instance: "URI of the request"
+      errors: "Array of field-level validation errors"
+      traceId: "Request trace identifier"
+
+  filtering_sorting:
+    filtering:
+      simple: "?status=active"
+      bracket: "?filter[status]=active"
+      range: "?filter[created_at][gte]=2026-01-01"
+    sorting:
+      ascending: "?sort=created_at"
+      descending: "?sort=-created_at"
+      multiple: "?sort=-created_at,last_name"
+    field_selection: "?fields=id,name,email"
+
+  graphql:
+    naming:
+      types: PascalCase
+      fields: camelCase
+      enums: SCREAMING_SNAKE_CASE
+      mutations: "verb + noun (createUser)"
+      input_types: "action + noun + Input"
+      payload_types: "action + noun + Payload"
+    pagination: "Relay connections (edges, nodes, pageInfo)"
+    errors: "Return userErrors in payload, not top-level errors"
+
+  grpc:
+    package: "company.service.version"
+    service_naming: "PascalCase + Service suffix"
+    rpc_methods: "PascalCase verb + noun"
+    field_naming: snake_case
+    error_mapping:
+      INVALID_ARGUMENT: 400
+      UNAUTHENTICATED: 401
+      PERMISSION_DENIED: 403
+      NOT_FOUND: 404
+      ALREADY_EXISTS: 409
+      RESOURCE_EXHAUSTED: 429
+      INTERNAL: 500
+
+rules:
+  - id: REST-001
+    rule: "Use plural nouns in kebab-case for resource URLs; never use verbs"
+    severity: error
+  - id: REST-002
+    rule: "Return correct HTTP status codes; 201 for creation, 204 for deletion, 422 for validation errors"
+    severity: error
+  - id: REST-003
+    rule: "Use RFC 7807 Problem Details format for all error responses"
+    severity: error
+  - id: REST-004
+    rule: "Version APIs via URL path (/v1/) and maintain version lifecycle (current → deprecated → retired)"
+    severity: warning
+  - id: REST-005
+    rule: "Include rate limiting headers (X-RateLimit-Limit, Remaining, Reset) on all responses"
+    severity: warning
+  - id: REST-006
+    rule: "Use cursor-based pagination for large or real-time datasets; offset-based for simple lists"
+    severity: info
+  - id: REST-007
+    rule: "Require HTTPS for all API endpoints; TLS 1.2 minimum, TLS 1.3 preferred"
+    severity: error
+  - id: REST-008
+    rule: "Document every endpoint with OpenAPI 3.x including parameters, request/response examples, and auth"
+    severity: warning
+
+quick_reference:
+  url_pattern: "[VERB] https://api.{domain}/v{N}/{resources}/{id}"
+  response_success: "{ data, meta, links }"
+  response_error: "{ type, title, status, detail, errors, traceId }"
+  verb_cheat_sheet:
+    list: "GET /users → 200"
+    read: "GET /users/123 → 200"
+    create: "POST /users → 201"
+    update_full: "PUT /users/123 → 200"
+    update_partial: "PATCH /users/123 → 200"
+    delete: "DELETE /users/123 → 204"
+
+physical_spec:
+  type: custom_script
+  validator:
+    command: "test -f openapi.yaml || test -f openapi.json || test -f swagger.yaml || test -f swagger.json || test -f docs/api.yaml"
+    rule: "api_spec_exists"

package/bundled/ai/standards/branch-completion.ai.yaml

@@ -0,0 +1,82 @@
+# Branch Completion Workflow - AI Optimized
+# Source: core/branch-completion.md
+# Inspired by Superpowers finishing-a-development-branch (MIT)
+
+standard:
+  id: branch-completion
+  name: Branch Completion Workflow
+  description: 分支完成工作流標準
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/branch-completion.md
+    description: 分支完成決策與清理標準
+    inspired_by: superpowers/finishing-a-development-branch
+
+  guidelines:
+    - "測試全過才能談完成"
+    - "提供 4 個完成選項讓使用者選擇"
+    - "Discard 需要明確確認，防止誤刪"
+    - "Worktree 對應分支完成後必須清理"
+
+  prerequisites:
+    - "所有測試通過"
+    - "lint 通過"
+    - "type check 通過"
+    - "無未提交的變更"
+
+  options:
+    - id: merge_locally
+      description: "合併到目標分支"
+      steps:
+        - "git checkout <target>"
+        - "git merge --no-ff <branch>"
+        - "刪除分支"
+        - "清理 worktree（若有）"
+    - id: create_pr
+      description: "建立 Pull Request"
+      steps:
+        - "推送分支到 remote"
+        - "建立 PR（含描述與測試計畫）"
+        - "等待審查"
+    - id: keep_as_is
+      description: "保持現狀不動"
+      steps:
+        - "記錄分支狀態"
+        - "提醒使用者稍後處理"
+    - id: discard
+      description: "丟棄所有變更"
+      steps:
+        - "要求使用者明確確認（輸入分支名稱）"
+        - "刪除分支（git branch -D）"
+        - "清理 worktree（若有）"
+
+  rules:
+    - id: BC-001
+      trigger: "使用者選擇 discard"
+      action: "要求輸入分支名稱確認，防止誤刪"
+      priority: critical
+    - id: BC-002
+      trigger: "分支有 worktree"
+      action: "完成後自動清理 worktree"
+      priority: high
+    - id: BC-003
+      trigger: "前置條件未滿足"
+      action: "阻止完成，顯示失敗的檢查項目"
+      priority: high
+    - id: BC-004
+      trigger: "分支閒置超過 14 天"
+      action: "通知使用者完成或丟棄"
+      priority: medium
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查分支完成是否遵循前置條件檢查和四選項流程"
+  checks:
+    - "完成前是否通過所有前置條件（測試、lint、type check）"
+    - "是否提供完成選項供使用者選擇"
+    - "Discard 操作是否要求明確確認"
+    - "關聯的 worktree 是否被清理"