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

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

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

**Type Values:**

| Type | Description |
| --- | --- |
| `fea