References canonical YAML specification schema, required fields, structure, and validation rules. Use for manual spec creation, provider-agnostic mapping, and debugging transformations.
npx claudepluginhub melodic-software/claude-code-plugins --plugin spec-driven-developmentThis skill is limited to using the following tools:
Reference guide for the canonical specification format - the provider-agnostic intermediate representation defined in ADR-115.
Central hub for specification-driven development workflows. Navigates to specialized skills for EARS, Gherkin, Kiro, Spec Kit; supports format conversions, quality checks, and 5-phase Spec Kit workflow.
Provides conventions for writing self-contained, implementation-ready spec documents. Distinguishes specs from docs; covers structure including data model, architecture, security, operations, scope, and deliverables.
Creates or updates SPEC.md documents from requirements, notes, or interview output, structuring into sections for goals, design, edge cases, security, testing, and success criteria. Use for feature specs.
Share bugs, ideas, or general feedback.
Reference guide for the canonical specification format - the provider-agnostic intermediate representation defined in ADR-115.
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:
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
| 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 |
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:
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:
- 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:
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:
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:
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):
| 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 |
| 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 |
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 |
schemas/canonical-spec.schema.json
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);
}
Detailed Documentation:
Repository Resources:
schemas/canonical-spec.schema.json - JSON Schemadocs/adr/ADR-115-specification-provider-abstraction.md - Architecture decisionLast Updated: 2025-12-26