Canonical specification format reference. Use when understanding the canonical spec schema, field requirements, provider-agnostic specification structure, or validating specifications against the schema.
Provides reference for the canonical specification schema used across providers. Use when creating, validating, or transforming specifications, or when you need to understand required fields, EARS requirement patterns, and provider-agnostic structure.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install spec-driven-development@melodic-softwareThis skill is limited to using the following tools:
references/schema-reference.mdreferences/validation-rules.mdReference 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
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.