Canonical Spec Format

Canonical Specification Format

Reference guide for the canonical specification format - the provider-agnostic intermediate representation defined in ADR-115.

When to Use This Skill

Keywords: canonical specification, canonical spec, spec schema, specification format, provider-agnostic, spec fields, spec validation, spec structure, YAML specification, JSON schema

Use this skill when:

• Understanding canonical specification structure
• Validating specifications against schema
• Creating specifications manually
• Mapping between providers and canonical format
• Debugging specification transformation issues

Quick Reference

Minimal Valid Specification

id: "SPEC-001"
title: "Feature Title"
type: feature

context:
  problem: "Problem description (min 20 chars)"
  motivation: "Business value"

requirements:
  - id: "REQ-001"
    text: "The system SHALL do something"
    priority: must
    ears_type: ubiquitous
    acceptance_criteria:
      - id: "AC-001"
        given: "precondition"
        when: "action"
        then: "outcome"

metadata:
  status: draft
  created: "2025-12-24"
  provider: canonical

Required Fields

Field Reference

Root Level

id: "SPEC-001"           # Required: Unique identifier
title: "Feature Title"    # Required: Human-readable name
type: feature             # Required: Specification type

Type Values:

Context Section

context:
  problem: |                    # Required: min 20 chars
    Clear description of the problem.
    What pain point does this address?
  motivation: |                 # Required
    Business value or user benefit.
    Why should we invest in this?
  background: |                 # Optional
    Additional context, history, constraints

Requirements Section

requirements:
  - id: "REQ-001"               # Required: Unique within spec
    text: "EARS requirement"    # Required: EARS-formatted
    priority: must              # Required: must/should/could/wont
    ears_type: event-driven     # Required: EARS pattern type
    acceptance_criteria:        # Required: at least one
      - id: "AC-001"
        given: "precondition"
        when: "action"
        then: "outcome"
        and:                    # Optional: additional conditions
          - "additional condition"
    notes: "Optional notes"     # Optional

Priority Values (MoSCoW):

EARS Type Values:

Design Section (Optional)

design:
  approach: |                   # Optional: implementation approach
    High-level description of how to implement
  components:                   # Optional: affected components
    - "Component 1"
    - "Component 2"
  dependencies:                 # Optional: prerequisites
    - "External dependency"
  alternatives:                 # Optional: considered alternatives
    - name: "Alternative approach"
      reason_rejected: "Why not chosen"

Traceability Section (Optional)

traceability:
  adr_refs:                     # Optional: related ADRs
    - "ADR-115"
  requirement_refs:             # Optional: related requirements
    - "FR-001"
    - "NFR-001"
  epic_ref: "EPIC-1118"         # Optional: parent EPIC
  user_story_refs:              # Optional: related user stories
    - "US-001"

Metadata Section

metadata:
  status: draft                 # Required
  created: "2025-12-24"         # Required: ISO 8601
  provider: canonical           # Required
  version: "1.0.0"              # Optional: semantic version
  bounded_context: "WorkManagement"  # Optional: from ADR-024

Status Values:

Bounded Context Values (ADR-024):

• WorkManagement
• Orchestration
• Workflows
• Expertise
• ExecutionControl
• TriggerManagement
• Integrations

Validation Rules

ID Formats

Content Constraints

EARS Pattern Validation

Each requirement's text field must match its declared ears_type:

JSON Schema Location

schemas/canonical-spec.schema.json

Provider Transformation

The canonical format serves as the hub for all provider transformations:

                    ┌─────────────┐
                    │  Canonical  │
                    │    Spec     │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │       │       │       │       │
           ▼       ▼       ▼       ▼       ▼
        ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
        │EARS │ │Ghrkn│ │Kiro │ │SpKit│ │ ADR │
        └─────┘ └─────┘ └─────┘ └─────┘ └─────┘

All providers implement ISpecificationProvider:

interface ISpecificationProvider
{
    string ProviderName { get; }
    Task<Result<CanonicalSpec>> ParseAsync(string input);
    Task<Result<string>> GenerateAsync(CanonicalSpec spec);
    Task<ValidationResult> ValidateAsync(CanonicalSpec spec);
    bool CanParse(string input);
}

References

Detailed Documentation:

• Schema Reference
• Validation Rules

Repository Resources:

• schemas/canonical-spec.schema.json - JSON Schema
• docs/adr/ADR-115-specification-provider-abstraction.md - Architecture decision

Last Updated: 2025-12-26