SED Specification File Structure

Introduction

SED specifications are Markdown files with YAML front matter that define complete, unambiguous implementation blueprints. Every specification file follows a standardized structure to ensure AI can parse, understand, and execute them without interpretation.

Key Principles

• Spec is the absolute standard — AI executes exactly what is written
• Zero ambiguity — Everything must be explicitly defined
• Complete specifications — No room for assumptions or interpretation
• Structured format — Consistent organization enables systematic processing

File Structure Overview

Every SED specification file consists of three main parts:

---
# 1. YAML Header (metadata)
name: project-module-feature
version: 1.0.0
description: Brief description
author: Your Name
email: [email protected]
---

# 2. Document Sections
## Overview
## Requirements
## Workflow
## Details

# 3. Implementation Specifications
(Detailed specifications for every aspect)

YAML Header Specification

Required Fields

All specification files must include these fields:

---
name: project-module-feature           # Unique identifier
version: 1.0.0                         # Semantic versioning
description: Brief description         # ≤4096 characters
author: Your Name                      # ≤64 characters
email: [email protected]                  # ≤64 characters
---

Optional Fields

Additional fields enhance functionality:

---
homepage: https://example.com          # Project website
funding: https://example.com/donate    # Support/payment route
license: MIT                           # License identifier
step: 20                               # Execution order
screenshot: https://example.com/img.png # Preview image URL
dependencies: account/repo/specs       # External spec dependencies
priority: **                           # Spec importance level
tags: [authentication, security, core] # Spec categorization tags
created: 2025-01-15                    # Spec creation date (YYYY-MM-DD)
updated: 2025-01-20                    # Last modification date (YYYY-MM-DD)
---

Field Descriptions

name (Required)

• Purpose: Unique identifier for the specification
• Format: English letters, numbers, hyphens only
• Length: ≤255 characters
• Convention: <project>-<module>-<feature> (e.g., my-app-auth-login)
• Two Usage Patterns:
  • Unified Project Name: All spec files in the same ./specs directory can share the same name value (representing the project name). Example: All files use my-app as the base name
  • Individual Spec Names: Each spec file can have its own unique name value (representing individual components). Example: my-app-auth-login, my-app-database-schema, my-app-api-users
• Recommendation: Choose one pattern for consistency across your entire spec directory. The unified project name pattern works better for related specs that form a single project; the individual spec names pattern works better when specs are independent or reusable across projects

version (Required)

• Purpose: Track specification version
• Format: Semantic versioning (MAJOR.MINOR.PATCH)
• Example: 1.0.0, 2.3.1

description (Required)

• Purpose: Brief summary of the specification
• Length: ≤4096 characters
• Content: Clear, concise explanation of what this spec defines

author (Required)

• Purpose: Specification author's name
• Length: ≤64 characters

email (Required)

• Purpose: Author's contact email
• Length: ≤64 characters
• Format: Valid email address

homepage (Optional)

• Purpose: Reference website or documentation
• Format: Valid URL

funding (Optional)

• Purpose: Payment route for supporting the spec maintainer
• Format: Valid URL (e.g., GitHub Sponsors, PayPal, custom page)

license (Optional)

• Purpose: Specify copyright and usage terms
• Values: MIT, GPL, SED Specification License, proprietary, etc.
• Note: Each spec file can have a different license
• Default: If omitted, copyright belongs to the author
• SED License: View at SED-LICENSE

step (Optional)

• Purpose: Define execution order when AI processes multiple specs
• Format: Integers (recommended: increments of 10)
• Example: step: 10, step: 20, step: 30
• Execution Rule: Lower numbers execute first
• Concurrent Execution: Files with the same step value run simultaneously
• Usage:

  step: 10   # Database setup (runs first)
  step: 20   # Backend API (runs second)
  step: 20   # Frontend setup (runs concurrently with backend)
  step: 30   # Integration tests (runs after both)

screenshot (Optional)

• Purpose: Visual preview specific to this spec file
• Format: Valid URL pointing to an image
• Use Case: Documentation tools and spec viewers can display this image
• Example: screenshot: https://example.com/screenshots/auth-preview.png

dependencies (Optional)

• Purpose: Reference or require other specifications for reuse
• Format: Comma-separated list of spec repository paths
• Details: See Dependencies System section

priority (Optional)

• Purpose: Mark the importance level of your own specification
• Format: Asterisks (*) indicating priority level:
  • No asterisk: Default/normal priority
  • *: Priority level 1
  • **: Priority level 2 (highest)
  • More asterisks = higher priority
• Example: priority: **
• Relationship to Dependencies: When specifications have dependencies, the priority levels in the dependencies system override this field's value
• Use Case: Help AI and developers understand which specs are critical for core functionality vs. optional enhancements

tags (Optional)

• Purpose: Categorize and label specifications for easy filtering and organization
• Format: YAML array format with comma-separated tags enclosed in brackets
• Syntax: tags: [tag1, tag2, tag3]
• Examples:
  • tags: [authentication, security, core]
  • tags: [frontend, ui, react]
  • tags: [database, postgresql, schema]
  • tags: [api, rest, endpoints]
• Common Tag Categories:
  • Feature Area: authentication, database, api, frontend, backend
  • Functionality: core, optional, experimental, deprecated
  • Technical Domain: security, performance, testing, documentation
  • Technology Stack: react, nodejs, postgresql, docker
• Use Cases:
  • Filter specifications by topic in spec browsers
  • Organize large specification repositories
  • Help AI quickly identify related specifications
  • Enable spec discovery and navigation
• Best Practices:
  • Use 2-5 tags per specification for optimal organization
  • Use lowercase for consistency
  • Use hyphens for multi-word tags (e.g., user-authentication)
  • Keep tags relevant and meaningful

created (Optional)

• Purpose: Record when the specification was initially created
• Format: ISO 8601 date format (YYYY-MM-DD)
• Example: created: 2025-01-15
• Use Case: Track specification history and age for documentation purposes

updated (Optional)

• Purpose: Record the last modification date of the specification
• Format: ISO 8601 date format (YYYY-MM-DD)
• Example: updated: 2025-01-20
• Use Case: Help users identify recently updated specifications and track maintenance activity
• Note: Should be updated whenever significant changes are made to the specification content

Spec Content Structure

Every specification file follows this standard structure:

1. Overview

Brief summary of the specification's purpose and scope.

## Overview

User authentication system supporting email/password and OAuth 2.0 (Google, Facebook, Apple).
Includes session management, password reset, and two-factor authentication (2FA).

2. Requirements

Complete list of prerequisites:

• Libraries: Exact package names and versions
• Tools: Required software and utilities
• Environment: Operating system, runtime versions
• Configuration: Environment variables, config files
• Installation: Commands to set up dependencies

## Requirements

### Libraries
- bcrypt ^5.1.0 — Password hashing
- jsonwebtoken ^9.0.0 — JWT token generation
- passport ^0.6.0 — Authentication middleware
- @google-oauth/client ^2.0.0 — Google OAuth integration

### Environment
- Node.js 20.10.0 LTS
- TypeScript 5.3.3
- PostgreSQL 15.4

### Installation
```bash
npm install bcrypt jsonwebtoken passport @google-oauth/client
```

3. Workflow

Step-by-step process AI must follow. Each step should be clear and actionable.

## Workflow

1. User submits credentials (email + password) via `/auth/login` endpoint
2. Validate input format:
   - Email: RFC 5322 compliant
   - Password: Minimum 8 characters
3. Query database for user record matching email
4. If user not found, return `401 Unauthorized`
5. Compare submitted password with stored hash using bcrypt
6. If password invalid, return `401 Unauthorized`
7. Generate JWT token with 24-hour expiration
8. Return token and user profile to client

4. Details

Exhaustive implementation specifications. This is the most critical section where every detail must be specified.

All function specifications should include:

• Purpose and location
• Parameters with types
• Return types with interfaces
• Complete implementation code
• Error handling with specific messages
• Test cases with coverage targets

Dependencies System

The dependencies field enables spec reuse and composition.

Basic Format

dependencies: account/repo/specs

Important: All dependency paths must end with /specs (plural form required).

GitHub Dependencies

GitHub repositories use the format: [account]/[repository]/[path]/specs

If the path does not start with http:// or https://, it is interpreted as a GitHub path.

# GitHub repository examples
dependencies: thruthesky/forum/specs
dependencies: withcenter/chat/firebase/specs

Expands to:

• github.com/thruthesky/forum/specs
• github.com/withcenter/chat/firebase/specs

Non-GitHub Dependencies

For non-GitHub resources, include the full URL ending with /specs:

dependencies: https://abc.com/def/specs
dependencies: https://cdn.example.com/shared/specs

Priority System

Use leading asterisks (*) to indicate priority when multiple specs contain similar content:

• No asterisk: Normal priority (default)
• *: Priority level 1
• **: Priority level 2 (highest)
• More asterisks = higher priority when conflicts occur

dependencies: |
  thruthesky/forum/specs,
  *withcenter/chat/firebase/specs,
  **https://example.com/high-priority/specs

Resolution: If multiple specs define the same functionality, higher priority specs override lower priority ones.

Specific File References

You can reference individual files or sections within a spec repository:

Option 1: Bracket Notation (path must end with /specs)

dependencies: withcenter/chat/firebase/specs[chat-rooms-join.md]
dependencies: withcenter/chat/firebase/specs[chat-rooms-join.md#overview]

Option 2: Direct File Paths (must be under /specs directory)

dependencies: thruthesky/forum/specs/authentication.md
dependencies: *https://abc.com/def/specs/validation.md
dependencies: **another/project/specs/main.md

Multiple Dependencies

Separate multiple dependencies with commas:

dependencies: |
  my-app/database/specs[users-schema.md],
  my-app/security/specs[encryption.md#password],
  *external/package/specs,
  **https://cdn.example.com/shared/specs[validation.md]

File Organization

Spec Repository Structure

All project specifications must be stored in the ./specs directory:

project-root/
├── specs/                    # All spec files go here
│   ├── index.md              # DTOC (Detailed Table of Contents)
│   │                          # Must reference https://sedai.dev/instructions for AI
│   ├── preview.png           # Spec repository preview image (1024×1024)
│   ├── project-setup.md
│   ├── project-database.md
│   ├── project-auth-login.md
│   └── project-auth-signup.md
├── src/                      # Implementation code
└── README.md

File Naming Convention

Pattern: <project>-<module>-<feature>.md

Examples:

• my-app-auth-login.md
• my-app-database-schema.md
• my-app-api-users.md
• forum-posts-create.md

Important Note on Hyphens:

The <feature> portion of the filename can contain multiple hyphens. Only the first two hyphens are used as separators for <project> and <module>. Everything after the second hyphen is considered part of the feature name.

Example with Multiple Hyphens:

For a filename like a-b-c-d-e.md:

• a = project name
• b = module name
• c-d-e = feature name (contains additional hyphens)

Benefits:

• Clear hierarchy (project → module → feature)
• Easy to locate specific functionality
• Systematic organization for large projects

Mandatory Files

index.md (REQUIRED)

Purpose: Detailed Table of Contents (DTOC) serving as the navigation hub for AI and developers

Why DTOC is Critical for SED:

When AI starts working on a task, it first reads index.md to understand:

• What each spec file contains (summary and purpose)
• When each spec should be used (triggering conditions, workflow order)
• Where the spec fits in the project architecture
• Why the spec exists (problems it solves, requirements it fulfills)
• How the spec relates to other specs (dependencies, execution order)
• Who created and maintains the spec (authorship, ownership)

This allows AI to make intelligent decisions about which specifications to load and in what order to execute them, following the 5W1H principle to determine relevance to the current task.

AI Development Instructions (MANDATORY)

Purpose: AI Development Directive — The mandatory guideline document that AI must strictly follow when working with specifications

Why SED Instructions are Critical:

According to SED principles, AI must:

1. Read https://sedai.dev/instructions FIRST before starting any task
2. Follow the instructions EXACTLY as written, without interpretation
3. Apply these rules consistently throughout development
4. Report violations if instructions conflict with specifications

This directive transforms AI from a passive code generator into a compliant development agent that follows project-specific rules with absolute fidelity.

How to Configure: In your specs/index.md, add a directive for AI to read https://sedai.dev/instructions before starting any development task. This ensures AI always has access to the latest SED development guidelines.

Mandatory Sections:

1. SED Compliance Rules — How to follow Spec-Exact Development principles
2. Code Style Guidelines — Formatting, naming, structure requirements
3. Testing Requirements — Coverage targets, test types, assertion patterns
4. Error Handling Standards — How to handle and report errors
5. Development Workflow — Step-by-step process for implementing specs
6. Quality Checks — Pre-commit validation, review criteria
7. Communication Protocol — How AI should request clarification

preview.png (RECOMMENDED)

Purpose: Visual identity for the specification repository

Format:

• Square image (width equals height)
• Size: 1024px × 1024px
• Location: ./specs/preview.png

Usage: Spec browsers, catalogs, and repository viewers display this image to help users quickly identify specifications.

Table of Contents (TOC) (OPTIONAL)

Purpose: Enhance navigation and improve discoverability of specifications

You can optionally add a structured Table of Contents at the top of your index.md file. This TOC serves as a quick reference guide for developers and AI to understand the overall structure of your specifications.

Format Example:

## Table of Contents

1. [Setup & Installation](my-app-setup.md)
2. [Database Schema](my-app-database.md)
3. [Authentication](my-app-auth-login.md)
4. [API Endpoints](my-app-api.md)
5. [Frontend Components](my-app-frontend.md)

Benefits:

• Faster navigation through multiple specification files
• Clear project structure overview
• Helps AI understand the relationship between different specs
• Improves developer onboarding

External References (OPTIONAL)

Purpose: Reference external specifications and shared specs repositories

You can optionally include references to internet URL addresses and external specification repositories in your index.md or individual spec files. This allows you to:

• Share and reuse specifications across projects
• Reference public specification repositories
• Link to external documentation and standards
• Maintain a centralized specification catalog

Usage Example:

## External Specifications & References

### Shared Libraries
- [User Authentication Spec](https://github.com/myteam/shared-specs/blob/main/specs/auth.md)
- [Database Utilities](https://github.com/myteam/shared-specs/blob/main/specs/db-utils.md)

### Public References
- [REST API Standards](https://jsonapi.org/)
- [Google OAuth 2.0 Protocol](https://developers.google.com/identity/protocols/oauth2)

Benefits:

• Avoid specification duplication across projects
• Leverage community specifications and best practices
• Maintain version control and documentation of external dependencies
• Enable specification composition and reuse

Complete Examples

Example 1: User Authentication Spec

This example demonstrates a complete authentication specification with all required sections, detailed implementations, error handling, and test cases.

Example 2: Database Schema Spec

This example demonstrates a complete database schema specification with PostgreSQL tables, indexes, foreign keys, triggers, and sample data.

Best Practices

1. Completeness Over Brevity

Bad Example:

description: User auth

Good Example:

description: Complete user authentication system with email/password login, OAuth 2.0 (Google, Facebook), session management, password reset, and account lockout after failed attempts

2. Explicit Version Numbers

Bad Example:

### Libraries
- bcrypt
- jsonwebtoken

Good Example:

### Libraries
- bcrypt ^5.1.0 — Password hashing with configurable salt rounds
- jsonwebtoken ^9.0.0 — JWT token generation and verification

3. Complete Code Examples

Bad Example:

Create a function to authenticate users

Good Example:

/**
 * Authenticates a user with email and password
 * @param email - User's email address
 * @param password - Plain text password
 * @returns Promise<AuthResult>
 */
export async function authenticateUser(
  email: string,
  password: string
): Promise<AuthResult> {
  // Complete implementation here...
}

4. Detailed Error Handling

Bad Example:

Handle errors appropriately

Good Example:

5. Specific Test Cases

Bad Example:

Write tests for the authentication function

Good Example:

### Test Cases

1. **Valid credentials** → Returns token and user profile (200)
2. **Invalid email format** → Returns validation error (400)
3. **Non-existent user** → Returns authentication error (401)
4. **Incorrect password** → Returns authentication error (401)
5. **5 failed attempts** → Locks account for 15 minutes (423)
6. **Database unavailable** → Returns server error (500)

**Coverage Target:** ≥80% (statement, branch, function, line)

6. User-Facing Text

Specify exact text strings that users will see:

Bad Example:

Show an error message

Good Example:

### Error Messages

- Invalid email: "Please enter a valid email address."
- Wrong password: "Invalid credentials. Please try again."
- Account locked: "Your account has been temporarily locked due to multiple failed login attempts. Please try again in 15 minutes."

7. CSS and Styling

Define exact visual specifications:

Bad Example:

Style the button nicely

Good Example:

.button-primary {
  background: linear-gradient(135deg, #6366F1 0%, #8B5CF6 100%);
  color: #FFFFFF;
  font-size: 16px;
  font-weight: 600;
  padding: 12px 24px;
  border-radius: 8px;
  border: none;
  box-shadow: 0 2px 8px rgba(99, 102, 241, 0.3);
  transition: all 200ms ease-in-out;
  cursor: pointer;
}

.button-primary:hover {
  transform: scale(1.05);
  box-shadow: 0 4px 12px rgba(99, 102, 241, 0.4);
}