# Specifications Management

> Complete guide for creating, managing, and structuring specifications with requirements and features

- Skill: `ewe-studios/specifications-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ewe-studios/specifications-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ewe-studios/specifications-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: ewe-studios (https://skillmd.com/u/ewe-studios)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ewe-studios/specifications-management

---


# Specifications Management

## Overview

Complete guide for creating and managing specifications including requirements-first development, feature-based structure, and specification lifecycle.

**Usage Type**: EDUCATIONAL - Learn specification management patterns.

## When to Use

- Creating new specifications
- Managing specification lifecycle
- Structuring requirements and features
- Understanding specification versioning

## Core Principles

### Requirements-First Development

Before ANY work:
1. Engage in conversation with user (Socratic method)
2. Document requirements in specification directory
3. Create integrated task list
4. Get explicit user approval
5. Agents read specifications before starting

**No exceptions**: No coding without documented requirements.


### Specification clarity and detail (CRITICAL)

When you write a specification, review it or are about to start it, always ask yourself:

1. Does this spec have hidden details not clarified in the spec or feature
2. Does this spec or feature make lots of assumptions on how some entity or behaviour functions without specifying the boundaries of its behaviour and execution or functionality
3. Does this spec or feature leave alot out for assumption creating potential areas for mis-interpretation or wrong execution
4. Can we make things more clear and more detailed to ensure the full scope, behaviours, boundaries, limitations is clearly articulated and written down.

If any of this is true, you should indicate to the user, pause and ask more questions to get everything clarified, documented and updated.

Update does not mean going to delete stuff unless its clear from the conversation that is what the user expects after clarification and discussion so be thoughtful, logical and surgical.

### Single-File Architecture (CRITICAL)

**MANDATORY:** All specification and architecture details MUST be contained in:
- `requirements.md` - For simple specs (has_features: false) OR high-level spec architecture (has_features: true)
- `feature.md` - For detailed feature-level architecture and requirements (has_features: true)

**FORBIDDEN:** Never create separate architecture files like:
- ❌ `architecture.md`
- ❌ `design.md`
- ❌ `technical-spec.md`
- ❌ `system-design.md`

**Rationale:** Splitting architecture across multiple files fragments context and makes specifications harder to maintain. All architectural decisions, diagrams, component descriptions, and technical details belong in the primary specification file (`requirements.md` or `feature.md`).

**Architecture Content Requirements:**
- `requirements.md` (spec-level): High-level architecture overview, layer descriptions, component relationships
- `feature.md` (feature-level): Comprehensive, logically correct, cohesive deep architecture for the feature including:
  - Technical approach and patterns
  - Component structure and interfaces
  - Data flow diagrams (text-based or mermaid)
  - Interface definitions
  - Error handling strategy
  - Security considerations
  - Performance considerations
  - Trade-offs and decisions

**Mermaid Diagrams (MANDATORY):**
Agents MUST use Mermaid diagrams to visualize architecture and processes:
- **Component diagrams** - Show component relationships
- **Sequence diagrams** - Show data flow and interactions
- **Flow charts** - Show decision logic and processes
- **State diagrams** - Show state machines

Example Mermaid in markdown:
```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
```

```mermaid
sequenceDiagram
    Client->>API: Request
    API->>Service: Process
    Service->>Database: Query
    Database-->>Service: Result
    Service-->>API: Response
    API-->>Client: Result
```

**When Creating/Updating Specifications:**
1. Architecture details → `requirements.md` or `feature.md` ONLY
2. Use Mermaid diagrams for visual clarity
3. Never split architecture into separate files
4. Keep architecture comprehensive, cohesive, and logically sound
5. Update architecture during implementation if approach changes

### Socratic Requirements Conversation

**Deep Thinking Approach:**
- Ask clarifying questions (expose assumptions)
- Probe edge cases
- Challenge vague requirements
- Help define "success" concretely
- Explore unknowns and dependencies

**Minimum questions**: 3-5 (small), 5-10 (medium), 10+ (large/complex)

**Critical areas**: Scope, technical approach, constraints, success criteria, edge cases, integration, priority, timeline, failure scenarios

**Encode Everything**: All decisions → requirements.md, edge cases → test scenarios, success criteria → measurable statements

## Directory Structure

### Simple Specification (has_features: false)

**Use ONLY for trivial specs (1-3 simple tasks)**

```
specifications/01-simple-spec/
├── start.md                 # Agent workflow entry point (permanent)
├── requirements.md          # Complete requirements + tasks + architecture (permanent)
├── LEARNINGS.md            # Permanent learnings
├── REPORT.md               # Permanent reports
├── PROGRESS.md             # Temporary progress report (deleted on completion or start)
├── VERIFICATION.md         # Verification signoff (permanent)
└── compacted.md            # Temporary context file (ephemeral - delete after session)
```

**CRITICAL:** All architecture and technical details MUST be in `requirements.md`. Never create `architecture.md`, `design.md`, or similar files.

**Notes:**
- May optionally have `scripts/`, `Makefile`, `templates/` directories
- May temporarily have `PROGRESS.md` during active work (ephemeral)

### Feature-Based Specification (has_features: true - DEFAULT)

**Use for all non-trivial work**

```
specifications/02-feature-spec/
├── start.md                 # Spec-level workflow entry point (permanent)
├── requirements.md          # High-level overview + architecture ONLY (permanent)
├── LEARNINGS.md            # Spec-wide learnings (permanent)
├── REPORT.md               # Spec-wide report (permanent)
├── VERIFICATION.md         # Spec-wide verification signoff (permanent)
└── features/
    ├── 00-foundation/
    │   ├── start.md         # Feature workflow entry point (permanent)
    │   ├── feature.md       # Detailed requirements + tasks + architecture (permanent)
    │   ├── VERIFICATION.md  # Feature verification (optional, permanent)
    │   ├── PROGRESS.md      # Temporary progress report (deleted on completion or start)
    │   └── compacted.md     # Temporary context (ephemeral - delete after session)
    ├── 01-core-api/
    │   ├── start.md
    │   └── feature.md
    └── 02-integrations/
        ├── start.md
        └── feature.md
```

**CRITICAL:**
- `requirements.md` contains spec-level high-level architecture
- `feature.md` contains comprehensive feature-level architecture
- **NEVER** create separate `architecture.md`, `design.md`, or similar files

**Notes:**
- Features markdown file should contain every detailed information and not be split into multiple files.
- Features may optionally have `templates/` directory
- Features may optionally have `scripts/` directory
- May temporarily have `PROGRESS.md` at spec level during active work (ephemeral)
- compacted.md is generated by agents during work, lives in feature directories

### When to Use Features

**DEFAULT: Use features** unless very simple.

**Use `has_features: true` when:**
- Multiple components or logical groupings
- Work split into phases with dependencies
- Requirements exceed ~5 tasks
- Context optimization needed

**Use `has_features: false` ONLY when:**
- Trivial (1-3 simple tasks)
- No logical component boundaries
- User explicitly requests simple structure

**Decision Rule**: When in doubt, default to `has_features: true`.

## start.md Files

**Purpose**: Agent workflow entry point - tells agents what to read and in what order.

**Location**: Required in every specification and feature directory.

### Variant 1: Feature-Based Spec (Spec Level)

**File**: `specifications/NN-spec/start.md`

**Purpose**: Redirect agents to feature-level start.md files.

**Content**: Short workflow that reads requirements.md, identifies feature from Feature Index, then navigates to feature start.md.

**Example**: See `.agents/templates/examples/start-specification-example.md`

**Template**: Use VARIANT 1 from `.agents/templates/START-template.md`

### Variant 2: Feature-Based Spec (Feature Level)

**File**: `specifications/NN-spec/features/[feature]/start.md`

**Purpose**: Complete agent workflow for implementing this specific feature.

**Content**: Full 13-step workflow including:
1. Read feature.md
2. Read LEARNINGS.md and VERIFICATION.md (from parent spec)
3. Read AGENTS.md and agent documentation
4. Read skills
5. Generate compacted.md
6. Clear context and reload
7. Work on ONE item at a time
8. TDD approach
9. Report to Main Agent
10. Wait for verification
11. Delete compacted.md after commit

**Example**: See `.agents/templates/examples/start-feature-example.md`

**Template**: Use VARIANT 2 from `.agents/templates/START-template.md`

### Variant 3: Simple Spec (Spec Level Only)

**File**: `specifications/NN-spec/start.md`

**Purpose**: Complete agent workflow for implementing the entire simple specification.

**Content**: Full 13-step workflow (same as feature-level but reads requirements.md instead of feature.md).

**Example**: See `.agents/templates/examples/start-simple-specification-example.md`

**Template**: Use VARIANT 3 from `.agents/templates/START-template.md`

### Key Differences

| Aspect | Spec-Level (Feature-Based) | Feature-Level | Simple Spec |
|--------|---------------------------|---------------|-------------|
| **Length** | Short (4 steps) | Full (13 steps) | Full (13 steps) |
| **Purpose** | Redirect to features | Complete workflow | Complete workflow |
| **Reads** | requirements.md | feature.md | requirements.md |
| **Compaction** | No | Yes | Yes |
| **Workflow** | Navigate to feature | Full implementation | Full implementation |

### When Creating start.md Files

**For feature-based specs (has_features: true):**
1. Create Variant 1 at spec root
2. Create Variant 2 for EACH feature directory

**For simple specs (has_features: false):**
1. Create Variant 3 at spec root only
2. No feature-level files needed

## Requirements.md Content

### For Simple Specs (has_features: false)

**Contains COMPLETE details:**
- Full functional requirements
- Full technical specifications
- Complete task breakdown
- Detailed implementation guidance
- All success criteria
- All verification commands

### For Feature-Based Specs (has_features: true - DEFAULT)

**Contains HIGH-LEVEL OVERVIEW ONLY:**

**Include:**
- Overview: Brief summary
- Known Issues/Limitations
- Feature Index: Table with descriptions
- Requirements Conversation Summary
- High-Level Architecture
- Success Criteria: Spec-wide only
- Module References

**Do NOT Include:**
- Detailed functional requirements (→ feature.md)
- Detailed technical specs (→ feature.md)
- Individual task breakdowns (→ feature.md)
- Implementation details (→ feature.md)

**Benefit**: Context optimization - agents read overview + specific feature, not all features.

## Frontmatter Requirements

### requirements.md

```yaml
---
description: "Brief description"
status: "in-progress" | "completed"
priority: "high" | "medium" | "low"
created: YYYY-MM-DD
author: "Main Agent"
metadata:
  version: "1.0"
  last_updated: YYYY-MM-DD
  estimated_effort: "small | medium | large"
  tags: [tag1, tag2]
  stack_files: [rust.md, javascript.md]
  skills: [skill1, skill2]
  tools: [Tool1, Tool2]
has_features: true | false
has_fundamentals: true | false
builds_on: "specifications/NN-previous-spec"  # optional
related_specs: ["spec1", "spec2"]  # optional
tasks:  # or features:
  completed: N
  uncompleted: N
  total: N
  completion_percentage: N%
---
```

### feature.md (if has_features: true)

```yaml
---
feature: "Feature Name"
description: "Brief description"
status: "pending" | "in-progress" | "completed"
priority: "high" | "medium" | "low"
depends_on: ["feature-name"]  # optional
estimated_effort: "small | medium | large"
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
author: "Main Agent"
tasks:
  completed: N
  uncompleted: N
  total: N
  completion_percentage: N%
---
```

## Specification Lifecycle

### Creation Phase

1. User requests feature
2. Main Agent conversation with user (Socratic questions)
3. Create specification directory
4. Write requirements.md
5. Create start.md files:
   - **If has_features: false**: Create spec-level start.md (Variant 3)
   - **If has_features: true**: Create spec-level start.md (Variant 1) + feature-level start.md (Variant 2) for each feature
6. Get explicit user approval ("Start implementation", "Go ahead", "Proceed")

### Implementation Phase

1. Spawn implementation agents
2. Agents implement following specifications
3. Update PROGRESS.md as work progresses
4. Verification before commits

### Completion Phase

1. All tasks/features completed
2. Generate REPORT.md (permanent)
3. Generate VERIFICATION.md (permanent)
4. Update status to "completed"
5. Delete PROGRESS.md
6. Specification now IMMUTABLE

## Specification Versioning (CRITICAL)

**Completed specifications are IMMUTABLE.**

**Before updating:**
1. Check status in requirements.md frontmatter
2. If "completed": Create NEW specification (use `builds_on` field)
3. If "in-progress": Can update

**Example:**
```
User: "Add retry logic to HTTP client"
Main Agent checks: specifications/01-build-http-client/requirements.md
Status: completed ✅
Action: Create specifications/04-add-http-client-retry-logic/
Reference: builds_on: "specifications/01-build-http-client"
```

**Why**: Preserves historical record, creates clear lineage, enables audit trail.

## Implementation Plans

**Location**: `specifications/[spec]/features/[feature]/feature.md`

The feature.md should contain all and comprehensive details of what needs to be implemented.
Instead we should add a section in it for the implementation plans.

**NEVER create multiple files, the feature.md is the comprehensive documentation of whats needs to be done**.

**Contents:**
- Technical approach and architecture
- Key framework patterns
- Step-by-step implementation tasks
- Success criteria
- Trade-offs considered

**Lifecycle:**
- Created in plan mode (BEFORE implementation)
- Updated if approach changes
- Kept permanently (never delete)
- Referenced in feature.md

**Don't:**
- Create in `~/.claude/plans/` (temporary)
- Put in requirements.md (too high-level)
- Delete after implementation

## Naming Convention

**Format**: `NN-descriptive-name/` (two-digit prefix, dashes, lowercase)

**Good**: `01-build-http-client/`, `features/dns-resolution/`
**Bad**: `http-client/` (no number), `1-client/` (single digit), `features/DnsResolution/` (wrong case)

## File Lifecycle

### Permanent Files (Never Delete)
- start.md (workflow entry point)
- requirements.md
- feature.md
- LEARNINGS.md
- REPORT.md
- VERIFICATION.md
- scripts/ (if exists)
- Makefile (if exists)
- templates/ (if exists)

### Ephemeral Files (Delete When Done)
- PROGRESS.md (delete when spec 100% complete - optional file)
- compacted.md (delete after each agent session or task completion)

## User Approval Requirements

**MANDATORY user review:**
- Specification writing (user must approve specs)
- Requirements clarification
- Defining success criteria
- Major architectural decisions

**NO user approval needed:**
- Implementation details (follow spec)
- Fixing broken tests
- Completing incomplete tests (if clear)
- Standard quality improvements
- Following established patterns

**Principle**: User deeply involved in **what** to build. Agents autonomously execute **how** per approved spec.

## Common Patterns

### Pattern: Simple Specification

```
1. User requests simple task
2. Socratic conversation (3-5 questions)
3. Create specifications/NN-task/requirements.md
4. Include all details in requirements.md
5. Set has_features: false
6. Create start.md (Variant 3 - simple spec)
7. Get user approval
8. Implement
```

### Pattern: Feature-Based Specification

```
1. User requests complex feature
2. Socratic conversation (10+ questions)
3. Create specifications/NN-feature/requirements.md (overview only)
4. Create features/00-foundation/feature.md (detailed)
5. Create features/01-core/feature.md
6. Set has_features: true
7. Create spec-level start.md (Variant 1 - redirect to features)
8. Create feature-level start.md (Variant 2) for EACH feature
9. Get user approval
10. Implement feature-by-feature
```

### Pattern: Building on Completed Spec

```
1. User requests enhancement to completed spec
2. Check specifications/01-original/requirements.md status
3. Status: completed ✅
4. Create NEW spec: specifications/04-enhancement/
5. Set builds_on: "specifications/01-original"
6. Continue normal workflow
```

## Summary

**Requirements-First:**
1. Socratic conversation (3-5+ questions)
2. Document requirements
3. Get explicit user approval
4. No coding without requirements

**Structure:**
- Simple specs: has_features: false (1-3 tasks only)
- Feature-based: has_features: true (DEFAULT)
- High-level overview in requirements.md
- Detailed requirements in feature.md

**Versioning:**
- Completed specs are IMMUTABLE
- Build on completed specs with new spec
- Use builds_on field to reference

**Lifecycle:**
- Creation → Implementation → Completion
- PROGRESS.md ephemeral (delete at 100%)
- REPORT.md + VERIFICATION.md permanent

**Key Principles:**
1. Requirements-first (no coding without specs)
2. User approval required (explicit confirmation)
3. Features by default (unless trivial)
4. Immutable when complete (create new for changes)
5. start.md in every spec and feature (workflow entry points)
6. compacted.md for context optimization (ephemeral, delete after session)
7. **ALWAYS UPDATE LEARNINGS.md** after each milestone/task completion

## ⚠️ CRITICAL REMINDER ⚠️

**NEVER FORGET TO UPDATE LEARNINGS.MD**

After completing each milestone, phase, or significant task:
1. Document what was learned
2. Capture design decisions and rationale
3. Note challenges and solutions
4. Record patterns discovered
5. Update `specifications/XX-spec-name/LEARNINGS.md`
6. Each feature only has feature.md has the comprehensive documentation of everything. No splits.

**This is MANDATORY** - learnings are critical for:
- Future development
- Knowledge transfer
- Avoiding repeated mistakes
- Pattern documentation

---

_Version: 4.1 - Last Updated: 2026-03-03_