Spec

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:

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

# {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.}

{diagram illustrating this decision}

KD-2: {Decision-shaped title}

{...}

Components and Interfaces

{Component 1}

Purpose: {What this component does}

Interface:

// 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}