spec · git:20261007.158dade · 2026-10-07 · sha256 0b16fd53f9eda230
spec git:20261007.158dadeA
Immutable. This exact content never changes and is served at /api/v1/blob/0b16fd53f9eda230.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_63avkj5kcs3d5gan/0b16fd53f9eda230aee402f90e2df76836b8a590a229c740d08e11eb8db7f043.json
Then /plugin install spec@markdownregistry-63avkj5kcs3d5gan in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: spec
description: Walk through spec-driven development, design then requirements, producing a local .spec.md and .requirements.md for one feature. Both files are local working material and are never committed. Use when planning a feature before building it.
---
# Spec Skill
Walk a feature through **spec-driven development**: two phases, each with a user approval gate.
```
Design ──[approve]──> Requirements ──[approve]──> build
```
**A spec is local working material, and it is never committed or promoted.** It guides one piece
of work while that work is being built. When the work lands, the spec has done its job:
| What the spec held | Where it goes when the work lands |
|---|---|
| Behaviour and its contract | The code and its tests. A test is the durable form of an acceptance criterion. |
| A decision someone would later ask "why" about | One entry in `docs/design/decisions.md`, through `/kd`, once the user decides it. |
| Everything else: options, task lists, open questions, history | Nowhere. It stays in the local draft. |
`docs/design/` pages are written for a reader who was not in the discussion. Write one fresh
from the code when one is needed. **Never copy or adapt a spec into one.**
**When implementing a feature, strictly honour its spec.** The design (`.spec.md`) defines the
architecture and the decisions, and the requirements define testable behaviour.
## Skill Invocation
`/spec {area}/{feature}`
Start at any phase or resume where you left off:
- `/spec policy/temporal-history`: start or continue the spec
- `/spec policy/temporal-history --phase requirements`: jump to the requirements phase
## Where a spec lives
```
.agents/drafts/spec/
{area}/
YYYY-MM-DD-{desc}.spec.md
YYYY-MM-DD-{desc}.requirements.md
```
`.gitignore` holds `/.agents/drafts/`, so nothing here is committed. The area names a component,
such as `box`, `containment`, `credentials`, `egress-gateway`, `monty`, `policy`, `shell`, or
`telemetry`. The date and description match across the two files for one effort.
Because the folder is local, a spec exists only in the working tree that wrote it. A second
agent or a second clone does not see it. Hand off a spec by path, in chat.
## First Step: Check what already exists
**Before anything else**, read what already owns this area:
1. `ls .agents/drafts/spec/{area}/`: a spec effort already in progress here.
2. `docs/design/decisions.md`: the decisions already made in this area. A spec does not
re-decide one silently. To change one, run `/kd` on it.
3. The crate itself: its `AGENTS.md`, its module docs, and its tests. The code owns behaviour.
Then decide scope, and say it to the user:
- **Extend** an existing local spec, or
- **Create** a new one for a topic not yet covered.
---
## Writing Style: ASD-STE100 Simplified Technical English
Write every sentence of both artifacts in it: the `.spec.md` prose and the `.requirements.md`
prose.
- Use the active voice. Say "the decoder borrows the buffer", not "the buffer is borrowed".
- Use the present tense. A design states what the system does, not what it will do.
- Give one idea in one sentence.
- Keep a descriptive sentence to 25 words or fewer, and an instruction to 20 or fewer.
- Use one word for one meaning across both files. A term that means two things
belongs in the Glossary twice, under two names.
- Use no metaphor and no idiom.
- Make no noun cluster of more than three words.
- Keep a paragraph to six sentences or fewer, and prefer a list to a long sentence.
### What the style does not touch
- **EARS is a fixed grammar, and it wins inside an acceptance criterion.** Keep
`WHEN … THE {System_Component} SHALL …` exactly as the pattern table specifies. `SHALL`
stays; do not rewrite it to the present tense. Apply the style to the words you choose
*inside* each clause: keep the trigger and the response short, concrete, and free of
metaphor.
- **The user-story line keeps its template.** `As a {role}, I want {functionality}, so
that {benefit}.` is a fixed shape.
- **Identifiers and glossary terms are not prose.** `Title_Case` terms, type names, config
keys, file paths, JSON field names, and status values keep their exact spelling. The
three-word noun-cluster limit does not apply to them.
- **The templates control the structure.** Section names, KD numbering, and requirement
numbering stay as specified. Where the style and a template
disagree on wording, the style wins.
Apply the style as a pass over each artifact before the approval gate, not while drafting.
Read for a sentence over 25 words, the passive voice, a paragraph over six sentences, metaphor,
idiom, and one meaning per word. Use [`docs/design/terminology.md`](../../../docs/design/terminology.md)
for the word to use for each thing.
---
## Phase 1: Design (`.spec.md`)
The design document captures **what** the system does and **why** — architecture, key decisions, component interactions, data flow.
### Workflow
1. **Gather information** — ask the user (one question at a time):
- What feature or change to document?
- What problem does it solve? What's the motivation?
- What alternatives were considered?
- Any existing code or interfaces to reference?
2. **Draft the design** — write Key Decisions with diagrams
3. **Present to user for approval** — "Here's the design. Want to adjust anything, or should I proceed to requirements?"
### Design Document Template
```markdown
# {Feature} — Design
## Overview
{1-3 sentences: what this feature does and why it's needed}
## Architecture
```mermaid
{high-level architecture diagram showing major components and relationships}
```
## Key Decisions
### KD-1: {Decision-shaped title}
**Context**: {What situation led to this decision}
**Decision**: {What the system does — 1-3 normative sentences only. No reasoning, no alternatives, no history. A reader who stops here knows the behavior.}
**Rationale**: {Why this over alternatives. All reasoning, tradeoffs, prior art, and justification goes here — clearly separated from the normative Decision above.}
```mermaid
{diagram illustrating this decision}
```
---
### KD-2: {Decision-shaped title}
{...}
---
## Components and Interfaces
### {Component 1}
**Purpose**: {What this component does}
**Interface**:
```rust
// src/path.rs — trait / struct / public fn signature
```
## Data Models
{Data structures, schemas, entity definitions — structs, enums, serde shapes}
## Error Handling
{Error categories, error enums / Result types, recovery strategies}
## Security Considerations
{Authentication, authorization, data protection, input validation implications}
## Backward Compatibility
| Change | Backward Compatible? | Migration |
|--------|---------------------|-----------|
| {API/field/behavior change} | Yes / No | {How existing callers/data are handled} |
Key questions:
- Can this be rolled back without data loss or manual intervention?
- Do existing serialized records, crate consumers, or config files continue to work unmodified?
- If a new field is added, what does its absence/`None` mean? (Document explicitly — a field name is an implicit contract.)
- Is this a one-way door (can't un-ship a public API shape) or two-way door (can revert via config/feature flag)?
- If config-driven, does it activate everywhere simultaneously or use staged rollout?
## Accepted Residuals
{What this spec explicitly does NOT cover and why. Every gap should be intentional and stated — silence about a topic reads as "covered" when it may be "out of scope." List each residual with a brief rationale for exclusion.}
- **{Residual 1}**: {Why it's out of scope — e.g., handled by another crate, deferred to a future phase, not yet designed}
- **{Residual 2}**: {…}
## Open Questions
{Threads not yet resolved. Each must annotate which requirements it would affect if resolved differently than currently assumed.}
- **{Question}** — Affects: Req {N.M}, {N.M}. {Current assumption and what would change.}
```
### Key Decision Guidelines
Each KD should be **self-contained**: a reader can understand the decision from just that section.
**Every KD must have a mermaid diagram.** Choose the right type:
| When showing... | Use |
|---|---|
| Data flow or request path | `flowchart LR` or `flowchart TD` |
| State transitions | `stateDiagram-v2` |
| Sequence of operations | `sequenceDiagram` |
| Component relationships | `flowchart TD` with subgraphs |
| Decision tree | `flowchart TD` with diamond nodes |
**Good KD titles** are decision-shaped:
- "Decoder borrows the input buffer (zero-copy)" (not "Decoder")
- "Builder returns `Result` on invalid config" (not "Builder API")
- "Snapshots are append-only" (not "Storage Backend")
**Decision vs Rationale separation:** The Decision field is normative — it states what the system does in 1-3 sentences. A reader scanning KDs for "what does this system do" should be able to read only Decision fields and get a complete picture. All reasoning, tradeoffs, internal research, prior art, LOC estimates, PRD reconciliation, and alternatives go in Rationale. Never mix mechanism justification into the Decision field.
**Backward compatibility:** Every KD that changes existing behavior must state whether the change is backward compatible and what happens to existing data/callers. If the answer is "absence = legacy behavior," document what `None`/missing means explicitly — a field name is an implicit contract.
**KD numbering:** Sequential within each doc (KD-1, KD-2, ...). When extending, continue from the last number. A spec's KD number is local to that spec, so **never cite it from code, a test, or a committed doc**: the spec is not committed, so the citation is dead for every reader. Code cites a decision by its `docs/design/decisions.md` anchor.
**Mermaid tips:**
- One concept per diagram, not the entire system
- Label edges with the important detail (latency, protocol, data format)
- **Quote every edge label**: `A -.->|"read(2)"| B`. Measured: unquoted labels fail the lexer when
they contain `(` or `|`, and quoting always parses.
- Use subgraphs to group related components
- Prefer `flowchart` over `graph`
**Compile every block — a grep check cannot see a lexer error:**
```sh
export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
mmdc -i block.mmd -o /tmp/block.svg
```
`mmdc` drives a headless browser and finds none by default, so without that variable it reports a
launch failure that reads like "mermaid is unavailable". The output path needs a real extension;
`-o /dev/null` fails on every input and proves nothing.
---
## Phase 2: Requirements (`.requirements.md`)
Requirements transform the design into **testable, formal specifications** using EARS notation. Each requirement is traced back to the design and structured as user stories with acceptance criteria.
### Workflow
1. **Read the design doc** (`.spec.md`) — extract every behavior, constraint, and edge case
2. **Identify requirement groups** — cluster by user story / capability
3. **Draft requirements** using EARS patterns
4. **Present to user for approval** — "Here are the requirements. Want to adjust anything?"
### Requirements Document Template
```markdown
# {Feature} — Requirements
## Introduction
{Overview of the feature, what problem it solves, why it's needed. Reference the design doc.}
## Glossary
{Define technical terms, acronyms, component names used in requirements. Use Title_Case for terms that appear in EARS statements to make them unambiguous. A term the whole product uses belongs in docs/design/terminology.md, and this glossary defines spec-specific terms only.}
- **{Term_Name}**: {Definition}
### Scope
{What is included and excluded from this requirements document. All terms used here MUST be defined in the Glossary above.}
## Requirements
### Requirement 1: {Capability Title}
**User Story:** As a {role}, I want {desired functionality}, so that {benefit/value}.
#### Acceptance Criteria
1. WHEN {specific event or trigger} THE {System_Component} SHALL {specific system response}
2. IF {condition or state} THE {System_Component} SHALL {required behavior}
3. WHILE {precondition} WHEN {trigger} THE {System_Component} SHALL {response}
#### Example
{One concrete input → expected output illustrating the happy path. Enough for a test author to see what pass/fail looks like without reverse-engineering the prose.}
### Requirement 2: {Capability Title}
**User Story:** As a {role}, I want {feature}, so that {benefit}.
#### Acceptance Criteria
1. WHEN ...
2. IF ...
#### Example
{...}
{... more requirements ...}
## Non-Functional Requirements
### Backward Compatibility
- WHEN {an existing crate consumer calls without the new field} THE {System} SHALL {behave identically to the current behavior}
- IF {rollback is triggered} THE {System} SHALL {return to previous behavior without manual data migration}
- WHEN {a record serialized before this change is deserialized} THE {System} SHALL {handle absent/None new fields as legacy behavior}
### Performance
{Latency, throughput, allocation, resource consumption requirements}
### Security
{Authentication, authorization, input validation, encryption requirements}
## Definition of Done
- [ ] All acceptance criteria are met
- [ ] Non-functional requirements are satisfied
- [ ] Design decisions are honored
- [ ] Each acceptance criterion is pinned by a named test
- [ ] Each decision a reader would ask "why" about is offered to the user for `/kd`
- [ ] User-facing behaviour that changed is reflected in `docs/user/`
- [ ] Accepted Residuals in the spec are not accidentally implemented or contradicted
```
### EARS Patterns
| Pattern | Syntax | Use when... |
|---------|--------|-------------|
| **Ubiquitous** | `THE {System} SHALL {response}` | Always true, no trigger needed |
| **Event-driven** | `WHEN {trigger} THE {System} SHALL {response}` | Triggered by a specific event |
| **State-driven** | `WHILE {precondition} THE {System} SHALL {response}` | Behavior depends on system state |
| **Conditional** | `IF {condition} THE {System} SHALL {response}` | Unwanted/exceptional behavior |
| **Optional** | `WHERE {feature} THE {System} SHALL {response}` | Feature-dependent behavior |
| **Combined** | `WHILE {state} WHEN {trigger} THE {System} SHALL {response}` | Complex multi-condition behavior |
**Guidelines:**
- Use Title_Case for system components and glossary terms in EARS statements
- Each acceptance criterion must be independently testable
- **One SHALL per criterion.** If a criterion contains AND or multiple SHALL clauses, split it into separate criteria. Each criterion = one assertion = one test case.
- **Acceptance criteria describe observable system behavior only.** Documentation obligations (rustdoc, README updates) belong in Definition of Done, not acceptance criteria.
- Cover happy paths, error paths, and edge cases
- Number acceptance criteria within each requirement (1, 2, 3...)
- Reference requirement numbers as `{N}.{M}` (e.g., `1.1`, `2.3`) for traceability **inside the spec only**. Never put `Req 1.1` in a code comment or a test: name the test instead.
- Every requirement MUST include an Example block showing one concrete input → expected output
---
## Phase Transitions
After each phase, explicitly ask for approval before proceeding:
**Design → Requirements:**
> "The design is ready at `.agents/drafts/spec/{area}/YYYY-MM-DD-{desc}.spec.md`. Review the key decisions and architecture. Want to adjust anything, or should I proceed to requirements?"
**Requirements → build:**
> "The requirements are ready at `.agents/drafts/spec/{area}/YYYY-MM-DD-{desc}.requirements.md`. Review the acceptance criteria. Want to adjust anything, or should I start building?"
**When the work lands**, close the spec out in chat rather than in a file:
- name the test that pins each acceptance criterion;
- list each key decision that a reader would later ask "why" about, and offer to record it with
`/kd`. Record nothing in `decisions.md` until the user decides it;
- name any `docs/user/` page the change made stale.
## Extending Existing Specs
When extending an existing feature's specs:
- **Design**: Continue KD numbering from the last existing KD
- **Requirements**: Add new requirement groups, continue numbering
- Keep the same date prefix if extending the same effort, or use today's date for a new effort