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 Type Description

id

string Format: SPEC-{number}

title

string Human-readable title

type

enum feature, bug, chore, spike, tech-debt

context.problem

string Min 20 characters

context.motivation

string Business value

requirements

array At least one requirement

metadata.status

enum draft, review, approved, implemented, deprecated

metadata.created

string ISO 8601 date

metadata.provider

string Provider that created this spec

Field Reference

Root Level

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

Type Values:

Type Description

feature

New functionality or capability

bug

Defect fix

chore

Maintenance task

spike

Research or investigation

tech-debt

Technical debt reduction

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

Priority Description

must

Non-negotiable, system fails without it

should

Important but not critical

could

Desirable if resources permit

wont

Explicitly excluded from scope

EARS Type Values:

Type Pattern Example

ubiquitous

The system SHALL... "The system SHALL encrypt data"

state-driven

WHILE..., the system SHALL... "WHILE active, the system SHALL..."

event-driven

WHEN..., the system SHALL... "WHEN clicked, the system SHALL..."

unwanted

IF..., THEN the system SHALL... "IF error, THEN the system SHALL..."

complex

Combinations "WHILE active, WHEN clicked..."

optional

WHERE..., the system SHALL... "WHERE enabled, the system SHALL..."

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:

Status Description

draft

Initial creation, not reviewed

review

Under review/refinement

approved

Approved for implementation

implemented

Implementation complete

deprecated

No longer valid

Bounded Context Values (ADR-024):

• WorkManagement

• Orchestration

• Workflows

• Expertise

• ExecutionControl

• TriggerManagement

• Integrations

Validation Rules

ID Formats

Field Format Example

Specification ID SPEC-{number} SPEC-042

Requirement ID REQ-{number} REQ-001

Acceptance Criterion ID AC-{number} AC-001

ADR Reference ADR-{number} ADR-115

EPIC Reference EPIC-{number} EPIC-1118

User Story Reference US-{number} US-001

Content Constraints

Field Constraint

context.problem

Minimum 20 characters

requirements

At least one requirement

acceptance_criteria

At least one criterion per requirement

metadata.created

Valid ISO 8601 date

EARS Pattern Validation

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

ears_type Required Pattern

ubiquitous

Starts with "The" + entity + "SHALL"

state-driven

Starts with "WHILE"

event-driven

Starts with "WHEN"

unwanted

Contains "IF" and "THEN"

optional

Starts with "WHERE"

complex

Multiple pattern keywords

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