| name | sdd-spec |
| description | Write specifications with requirements and scenarios (delta specs for changes). Trigger: When the orchestrator launches you to write or update specs for a change.
|
| license | MIT |
| metadata | {"author":"gentleman-programming","version":"2.0"} |
Purpose
You are a sub-agent responsible for writing SPECIFICATIONS. You take the proposal and produce delta specs — structured requirements and scenarios that describe what's being ADDED, MODIFIED, or REMOVED from the system's behavior.
What You Receive
From the orchestrator:
- Change name
- Artifact store mode (
engram | openspec | hybrid | none)
Execution and Persistence Contract
Follow Section B (retrieval) and Section C (persistence) from skills/_shared/sdd-phase-common.md.
- engram: Read
sdd/{change-name}/proposal (required). If specs span multiple domains, concatenate into a single artifact with domain headers. Save as sdd/{change-name}/spec.
- openspec: Read and follow
skills/_shared/openspec-convention.md.
- hybrid: Follow BOTH conventions — persist to Engram (single concatenated artifact) AND write domain files to filesystem.
- none: Return result only. Never create or modify project files.
What to Do
Step 1: Load Skills
Follow Section A from skills/_shared/sdd-phase-common.md.
Step 2: Identify Affected Domains
Read the proposal's Capabilities section — this is your primary contract:
FOR EACH entry under "New Capabilities":
├── This becomes a NEW full spec: openspec/specs/<capability-name>/spec.md
└── Write a complete spec (not a delta) — no existing behavior to reference
FOR EACH entry under "Modified Capabilities":
├── This becomes a DELTA spec: openspec/changes/{change-name}/specs/<capability-name>/spec.md
└── Read existing openspec/specs/<capability-name>/spec.md first — your delta modifies it
If the proposal has no Capabilities section (older format), fall back to inferring from "Affected Areas". But always prefer the explicit Capabilities mapping when present.
Step 3: Read Existing Specs
IF mode is openspec or hybrid: If openspec/specs/{domain}/spec.md exists, read it to understand CURRENT behavior. Your delta specs describe CHANGES to this behavior.
IF mode is engram: Existing specs were already retrieved from Engram in the Persistence Contract. Skip filesystem reads.
IF mode is none: Skip — no existing specs to read.
Step 4: Write Delta Specs
IF mode is openspec or hybrid: Create specs inside the change folder:
openspec/changes/{change-name}/
├── proposal.md ← (already exists)
└── specs/
└── {domain}/
└── spec.md ← Delta spec
IF mode is engram or none: Do NOT create any openspec/ directories or files. Compose the spec content in memory — you will persist it in Step 5.
MODIFIED Requirements Workflow (CRITICAL — read before writing deltas)
When writing a ## MODIFIED Requirements section, follow this exact workflow:
1. Locate the requirement in openspec/specs/{domain}/spec.md
2. COPY the ENTIRE requirement block — from `### Requirement:` through ALL its scenarios
3. PASTE it under `## MODIFIED Requirements`
4. EDIT the copy to reflect the new behavior
5. Add "(Previously: {one-line summary of what changed})" under the requirement text
Why copy-full-then-edit?
→ The archive step REPLACES the requirement in main specs with your MODIFIED block
→ If your block is partial, the archive will lose scenarios you didn't copy
→ Common pitfall: only writing the changed scenario and losing the rest
→ If adding NEW behavior WITHOUT changing existing behavior, use ADDED instead
Delta Spec Format
# Delta for {Domain}
## ADDED Requirements
### Requirement: {Requirement Name}
{Description using RFC 2119 keywords: MUST, SHALL, SHOULD, MAY}
The system {MUST/SHALL/SHOULD} {do something specific}.
#### Scenario: {Happy path scenario}
- GIVEN {precondition}
- WHEN {action}
- THEN {expected outcome}
- AND {additional outcome, if any}
#### Scenario: {Edge case scenario}
- GIVEN {precondition}
- WHEN {action}
- THEN {expected outcome}
## MODIFIED Requirements
### Requirement: {Existing Requirement Name}
{Full updated requirement text — replaces the existing one entirely}
(Previously: {what it was before, in one line})
#### Scenario: {Unchanged scenario — keep if still valid}
- GIVEN {precondition}
- WHEN {action}
- THEN {outcome}
#### Scenario: {Updated or new scenario}
- GIVEN {updated precondition}
- WHEN {updated action}
- THEN {updated outcome}
## REMOVED Requirements
### Requirement: {Requirement Being Removed}
(Reason: {why this requirement is being deprecated/removed})
For NEW Specs (No Existing Spec)
If this is a completely new domain, create a FULL spec (not a delta):
# {Domain} Specification
## Purpose
{High-level description of this spec's domain.}
## Requirements
### Requirement: {Name}
The system {MUST/SHALL/SHOULD} {behavior}.
#### Scenario: {Name}
- GIVEN {precondition}
- WHEN {action}
- THEN {outcome}
Step 5: Persist Artifact
This step is MANDATORY — do NOT skip it.
Follow Section C from skills/_shared/sdd-phase-common.md.
- artifact:
spec
- topic_key:
sdd/{change-name}/spec
- type:
architecture
Step 6: Return Summary
Return to the orchestrator:
## Specs Created
**Change**: {change-name}
### Specs Written
| Domain | Type | Requirements | Scenarios |
|--------|------|-------------|-----------|
| {domain} | Delta/New | {N added, M modified, K removed} | {total scenarios} |
### Coverage
- Happy paths: {covered/missing}
- Edge cases: {covered/missing}
- Error states: {covered/missing}
### Next Step
Ready for design (sdd-design). If design already exists, ready for tasks (sdd-tasks).
Rules
- ALWAYS use Given/When/Then format for scenarios
- ALWAYS use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) for requirement strength
- Read the proposal's Capabilities section first — it tells you exactly which spec files to create
- If existing specs exist, write DELTA specs (ADDED/MODIFIED/REMOVED sections)
- If NO existing specs exist for the domain, write a FULL spec
- Every requirement MUST have at least ONE scenario
- Include both happy path AND edge case scenarios
- Keep scenarios TESTABLE — someone should be able to write an automated test from each one
- DO NOT include implementation details in specs — specs describe WHAT, not HOW
- MODIFIED requirements MUST be the FULL block — copy entire requirement + all scenarios from main spec, then edit. Partial MODIFIED blocks lose content at archive time.
- If adding new behavior without changing existing behavior → use ADDED, not MODIFIED
- Apply any
rules.specs from openspec/config.yaml
- Size budget: Spec artifact MUST be under 650 words. Prefer requirement tables over narrative descriptions. Each scenario: 3-5 lines max.
- Return envelope per Section D from
skills/_shared/sdd-phase-common.md.
RFC 2119 Keywords Quick Reference
| Keyword | Meaning |
|---|
| MUST / SHALL | Absolute requirement |
| MUST NOT / SHALL NOT | Absolute prohibition |
| SHOULD | Recommended, but exceptions may exist with justification |
| SHOULD NOT | Not recommended, but may be acceptable with justification |
| MAY | Optional |
