fsds/README.md

Feature Specification Documents (FSDs)

Comprehensive documentation for major features that span multiple components or introduce significant new functionality.

What Belongs Here

Feature specifications for:

Cross-component features - Spanning multiple services
Major new capabilities - Significant functionality additions
Complex integrations - External system integrations
Architectural features - New patterns or approaches

Rule of thumb: If you're creating a Linear project for it, create an FSD.

What Doesn't Belong Here

Single-component features → Document in component README
Small enhancements → Update existing docs
Bug fixes → Mention in CHANGELOG
Configuration changes → Update reference docs
How-to guides → Use docs/how-to/

Documentation Structure

Each feature specification follows a consistent structure:

docs/fsds/feature-name/
├── README.md                   # Overview and navigation
├── technical-design.md         # Architecture and implementation
├── entity-model.md             # Database schema (if applicable)
├── api-reference.md            # API endpoints (if applicable)
├── usage-examples.md           # Code examples
├── configuration.md            # Setup and configuration
├── migration-guide.md          # Upgrade guide (if applicable)
└── troubleshooting.md          # Common issues

For simpler features, a single markdown file is acceptable.

Current Feature Specifications

Feature	Description	Status
Unit of Measure System	ISO 80000/SI-compliant measurement framework	In Progress
Linear Notification System	Bidirectional Linear activity notifications for agent sessions	Phase 1 Complete

Writing Guidelines

README Template

# [Feature Name]

[One-paragraph description of the feature]

## Quick Start

[Minimal example showing the feature]

## Documentation

- [Technical Design](technical-design.md) - Architecture and implementation
- [Usage Examples](usage-examples.md) - Code samples and patterns
- [Configuration](configuration.md) - Setup and options
- [API Reference](api-reference.md) - Endpoint documentation

## Status

**Version:** 1.0
**Status:** Production
**Components:** [List of affected components]

## Related

- [ADR-XXX: Related Decision](../adrs/xxx-decision.md)

Technical Design Template

# Technical Design: [Feature Name]

## Overview

[High-level description]

## Architecture

[Architecture diagram and explanation]

## Components

### [Component Name]
**Role:** [What this component does for the feature]
**Location:** `engines/component-name/`

## Data Model

[Entity relationships, database schema]

## API Design

[HTTP endpoints, request/response schemas]

## Integration Points

[How this integrates with other systems]

## Security Considerations

[Authentication, authorization, data protection]

## Performance Characteristics

[Expected performance, scalability considerations]

FSD Lifecycle

1. Planning Phase

Create:

README.md (overview)
technical-design.md (architecture)
Related ADR documenting key decisions

2. Implementation Phase

Add:

usage-examples.md (as code is written)
configuration.md (as options are added)

3. Release Phase

Complete:

API reference (from OpenAPI specs)
migration-guide.md (if upgrading existing system)
troubleshooting.md (from testing)

4. Maintenance Phase

Update:

Keep examples current
Document new use cases
Add troubleshooting entries
Update version/status

Checklist

README - Clear overview and navigation
Design doc - Architecture explained
Examples - Real, working code samples
Configuration - All options documented
Testing - How to test the feature
Migration - Upgrade path (if applicable)
ADRs - Key decisions recorded
Related components - All components listed
Status - Current version and production status

Documentation