spec-compliance-validator

驗證規格檔案的完整性與一致性，確保所有必要的規格元素都已定義且符合標準格式。

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "spec-compliance-validator" with this command: npx skills add knowlet/skills/knowlet-skills-spec-compliance-validator

Spec Compliance Validator Skill

觸發時機

  • 新規格檔案創建後
  • 規格修改後的驗證
  • 進入開發階段前的品質門檻
  • 與 multi-model-reviewer 協作時

核心任務

  1. 結構完整性：驗證規格目錄結構
  2. 格式合規性：YAML 格式與 schema 驗證
  3. 追溯性檢查：Frame Concerns ↔ Acceptance Criteria ↔ Tests
  4. 跨規格一致性：標準引用、命名慣例

驗證項目

1. 目錄結構檢查

structure_checks:
  required_files:
    - name: "frame.yaml"
      description: "Problem Frame 定義"
      required: true
      
    - name: "acceptance.yaml"
      description: "驗收標準 (根目錄)"
      required: true
      
    - name: "requirements/*.yaml"
      description: "需求規格"
      required: true
      min_count: 1
      
    - name: "machine/machine.yaml"
      description: "Machine 定義"
      required: true
      
    - name: "machine/use-case.yaml"
      description: "Use Case 規格 (CBF)"
      required_if: "frame_type == 'CBF'"
      
    - name: "machine/query.yaml"
      description: "Query 規格 (IDF)"
      required_if: "frame_type == 'IDF'"
      
    - name: "controlled-domain/aggregate.yaml"
      description: "Aggregate 定義"
      required: true

2. Frame 定義驗證

frame_checks:
  - id: FR1
    name: "Frame Type 有效"
    rule: "frame_type ∈ {CBF, IDF, RIF, WPF, TF}"
    
  - id: FR2
    name: "Frame Concerns 完整"
    rule: "每個 concern 必須有 satisfied_by 連結"
    
  - id: FR3
    name: "Phenomena 定義"
    rule: "input/output phenomena 必須定義"
    
  - id: FR4
    name: "Cross-Context 識別"
    rule: "cross_context_dependencies 如有則必須有對應 ACL"

3. Acceptance Criteria 驗證

acceptance_checks:
  - id: AC1
    name: "格式合規"
    rule: "使用 acceptance_criteria 格式 (非舊版 scenarios)"
    expected_format: |
      acceptance_criteria:
        - id: AC1
          given: "前置條件"
          when: "觸發動作"
          then: "預期結果"
          trace: "requirements/req.yaml#REQ1"
    
  - id: AC2
    name: "追溯性完整"
    rule: "每個 AC 必須有 trace 連結到 requirement"
    
  - id: AC3
    name: "Tests Anchor"
    rule: "應定義 tests_anchor 指向測試檔案"

4. Domain Event 標準驗證

domain_event_checks:
  - id: DE1
    name: "標準引用"
    rule: "domain_events 應包含 includes_standard 和 standard_ref"
    expected: |
      domain_events:
        includes_standard: true
        standard_ref: "../../../../shared/domain-event-standard.yaml"
    
  - id: DE2
    name: "Metadata 屬性"
    rule: "使用標準時不需重複定義 id, occurredOn"
    
  - id: DE3
    name: "屬性排序"
    rule: "主要 ID 應為第一個屬性"

5. Invariant 驗證

invariant_checks:
  - id: INV1
    name: "Enforced 位置"
    rule: "每個 invariant 必須有 enforced_in 位置"
    
  - id: INV2
    name: "測試連結"
    rule: "invariant 應有對應的違反測試"
    
  - id: INV3
    name: "共享標準"
    rule: "共同 invariants 應抽取到 shared/invariants.yaml"

輸出格式

驗證報告

╔═══════════════════════════════════════════════════════════════════╗
║               SPEC COMPLIANCE VALIDATION REPORT                    ║
╠═══════════════════════════════════════════════════════════════════╣
║ Spec Directory: docs/specs/create-workflow/                        ║
║ Frame Type: CBF (Command-Behavior Frame)                          ║
╠═══════════════════════════════════════════════════════════════════╣
║                                                                    ║
║ 📁 STRUCTURE                                                       ║
║ ├── ✅ frame.yaml                              EXISTS              ║
║ ├── ✅ acceptance.yaml                         EXISTS              ║
║ ├── ✅ requirements/cbf-req-1-create-workflow.yaml                 ║
║ ├── ✅ machine/machine.yaml                    EXISTS              ║
║ ├── ✅ machine/use-case.yaml                   EXISTS              ║
║ └── ✅ controlled-domain/aggregate.yaml        EXISTS              ║
║                                                                    ║
║ 📋 FRAME DEFINITION                                                ║
║ ├── ✅ FR1: Frame Type Valid                   PASS               ║
║ ├── ✅ FR2: Frame Concerns Complete            PASS               ║
║ ├── ✅ FR3: Phenomena Defined                  PASS               ║
║ └── ⚠️ FR4: Cross-Context Identified           WARNING             ║
║         └─ AuthorizationContext referenced but no ACL defined     ║
║                                                                    ║
║ 📝 ACCEPTANCE CRITERIA                                             ║
║ ├── ✅ AC1: Format Compliant                   PASS               ║
║ ├── ✅ AC2: Traceability Complete              PASS               ║
║ └── ✅ AC3: Tests Anchor Defined               PASS               ║
║                                                                    ║
║ 🎯 DOMAIN EVENTS                                                   ║
║ ├── ✅ DE1: Standard Reference                 PASS               ║
║ ├── ✅ DE2: No Duplicate Metadata              PASS               ║
║ └── ✅ DE3: Property Ordering                  PASS               ║
║                                                                    ║
║ 🔒 INVARIANTS                                                      ║
║ ├── ✅ INV1: Enforced Location                 PASS               ║
║ ├── ⚠️ INV2: Violation Tests                   WARNING             ║
║ │       └─ 2/5 invariants missing violation tests                 ║
║ └── ✅ INV3: Shared Standards                  PASS               ║
║                                                                    ║
╠═══════════════════════════════════════════════════════════════════╣
║ TOTAL: 14/16 PASS, 2 WARNINGS, 0 ERRORS                           ║
║ STATUS: ⚠️ CONDITIONAL PASS                                        ║
╚═══════════════════════════════════════════════════════════════════╝

問題詳情

validation_issues:
  - id: SCV-001
    check: FR4
    severity: warning
    location: "frame.yaml#cross_context_dependencies"
    message: "AuthorizationContext referenced but no ACL specification found"
    
    current: |
      cross_context_dependencies:
        - context: AuthorizationContext
          dependency_type: query
    
    expected: |
      # Should have corresponding file:
      cross-context/authorization.yaml
    
    suggestion: |
      Run: analyze-frame --add-acl AuthorizationContext
      
  - id: SCV-002
    check: INV2
    severity: warning
    location: "controlled-domain/aggregate.yaml#invariants"
    message: "Invariants missing violation tests"
    
    missing_tests:
      - invariant: "workflow_name_unique_in_board"
        expected_test: "should reject duplicate workflow name"
      - invariant: "max_stages_limit"
        expected_test: "should reject when exceeding max stages"

與其他 Skills 協作

┌─────────────────────────────────────────────────────────────────┐
│                     Validation Pipeline                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────┐                                    │
│  │   spec-compliance-      │ ◄── 本 Skill (第一道防線)           │
│  │   validator             │                                    │
│  │   (規格完整性驗證)        │                                    │
│  └───────────┬─────────────┘                                    │
│              │ Spec 完整                                         │
│              ▼                                                   │
│  ┌─────────────────────────┐                                    │
│  │   code-reviewer         │                                    │
│  │   (程式碼審查)           │                                    │
│  └───────────┬─────────────┘                                    │
│              │ Code 符合規格                                     │
│              ▼                                                   │
│  ┌─────────────────────────┐                                    │
│  │   multi-model-reviewer  │                                    │
│  │   (多模型交叉驗證)        │                                    │
│  └───────────┬─────────────┘                                    │
│              │ 三角驗證通過                                      │
│              ▼                                                   │
│         ✅ Ready for PR                                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

命令行工具

# 驗證單一規格目錄
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
    docs/specs/create-workflow/

# 驗證所有規格
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
    docs/specs/ --recursive

# 快速檢查 (只檢查結構)
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
    docs/specs/create-workflow/ --quick

# 生成修復建議
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
    docs/specs/create-workflow/ --fix-suggestions

# JSON 輸出
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
    docs/specs/create-workflow/ --format json

標準參考檔案

共用標準位置

shared_standards:
  domain_events: "shared/domain-event-standard.yaml"
  invariants: "shared/invariants-standard.yaml"
  metadata: "shared/metadata-standard.yaml"

domain-event-standard.yaml 範例

# shared/domain-event-standard.yaml
standard:
  name: "Domain Event Standard"
  version: "1.0"
  
base_properties:
  - name: id
    type: EventId
    description: "事件唯一識別碼"
    
  - name: occurredOn
    type: Instant
    description: "事件發生時間"
    
  - name: metadata
    type: EventMetadata
    description: "事件元資料 (correlationId, causationId, userId)"
    
usage:
  includes_standard: true
  standard_ref: "path/to/domain-event-standard.yaml"
  # 使用標準後，只需定義特定屬性，base_properties 自動繼承

配置檔案

.spec-validator.yaml

version: "1.0"

structure:
  strict: true
  required_dirs:
    - requirements
    - machine
    - controlled-domain
    
format:
  acceptance: "acceptance_criteria"  # new format
  allow_legacy: false  # reject old 'scenarios' format
  
traceability:
  require_trace: true
  require_tests_anchor: true
  
standards:
  domain_events:
    require_standard_ref: true
    standard_path: "shared/domain-event-standard.yaml"
    
  invariants:
    require_enforced_in: true
    require_violation_tests: true

ignore:
  paths:
    - "**/_draft/**"
    - "**/_deprecated/**"

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

enforce-contract

No summary provided by upstream source.

Repository SourceNeeds Review
9-knowlet
General

multi-model-reviewer

No summary provided by upstream source.

Repository SourceNeeds Review
8-knowlet
General

arch-guard

No summary provided by upstream source.

Repository SourceNeeds Review
8-knowlet
General

coding-standards

No summary provided by upstream source.

Repository SourceNeeds Review
8-knowlet