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