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:

graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]

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

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

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

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