Specs (Specifications)

What Are Specs?

Specs are the first tier in sudocode’s 4-tier abstraction structure. They capture user intent - the WHAT you want to build, not the HOW. Think of specs as your requirements documents, RFCs, design decisions, and research questions all living as version-controlled artifacts alongside your code.

Key Principle: Specs capture what humans want. Issues (tier 2) capture how agents will implement it.

A spec is a structured markdown document that defines user intent at various levels of detail. Specs can be:

High-level requirements - “Build a user authentication system”
RFCs - “Proposal for migrating to OAuth 2.0”
Design decisions - “API authentication flow design”
Research questions - “Evaluate database options for time-series data”
Architecture docs - “Microservices architecture overview”

Specs vs. Issues

Specs

User intent (WHAT)

Written by humans
Requirements and design
Long-lived documentation
Evolve with learnings

Issues

Agent tasks (HOW)

Created from specs
Actionable work items
Task-level granularity
Closed when complete

Spec Lifecycle

Specs progress through a defined lifecycle from creation to completion:

draft - Initial creation and iteration

Specs start as drafts when first created. Use this status while:

Gathering requirements
Iterating on design
Adding details
Getting feedback from agents during implementation

review - Ready for review

Move to review when the spec is ready for stakeholder review:

Requirements are complete
Design is fleshed out
Ready for implementation planning
Awaiting approval

approved - Finalized and ready

Approved specs are finalized and ready for implementation:

Requirements locked in
Issues can be created from this spec
Implementation can begin
Still can receive feedback from agents

deprecated - No longer relevant

Deprecated when the spec is superseded or no longer needed:

Feature removed
Replaced by newer spec
Requirements changed
Keep for historical reference

Spec Types

Specs are categorized by type to help with organization and filtering:

Type	Purpose	Example
architecture	System design and structure	”Microservices migration plan”
api	API design and contracts	”REST API v2 design”
database	Data models and schemas	”User data model redesign”
feature	Product features	”Multi-factor authentication”
research	Investigation and analysis	”Evaluate GraphQL vs REST”

Spec Structure

Specs are stored as markdown files with YAML frontmatter in .sudocode/specs/:

File Format

---
id: SPEC-001
title: Authentication System Design
type: architecture
status: draft
priority: 1
created_at: 2025-10-29T10:00:00Z
updated_at: 2025-10-29T15:30:00Z
created_by: alice
tags: [auth, security, backend]
---

# Authentication System Design

This spec defines the authentication system for our application.

## Requirements

1. Support OAuth 2.0 for third-party login [[@ISSUE-001]]
2. Implement multi-factor authentication [[@ISSUE-002]]
3. Session management with JWT tokens [[@ISSUE-003]]

## Design Decisions

### Token Strategy

We'll use JWT tokens with 1-hour expiration and refresh tokens
with 30-day expiration. See [[SPEC-010]] for API design patterns.

### Security Considerations

- Store refresh tokens securely in httpOnly cookies
- Implement token rotation on refresh
- Add rate limiting to prevent brute force

## Open Questions

- Token expiration policy needs clarification (feedback from ISSUE-001)

id: string                    # SPEC-001, SPEC-042, etc.
title: string                 # Human-readable title (max 500 chars)
type: enum                    # architecture | api | database | feature | research
status: enum                  # draft | review | approved | deprecated
priority: int                 # 0-4 (0=highest, 2=default)
created_at: timestamp         # ISO 8601 format
updated_at: timestamp         # ISO 8601 format
created_by: string            # Username or agent ID
updated_by: string            # Last modifier
parent: string?               # Optional parent spec ID
tags: [string]                # Free-form tags for organization

Flexible Content: The markdown body is completely flexible - no enforced structure. Organize sections however makes sense for your spec.

Cross-References and Links

Specs support two types of references using Obsidian-style syntax:

Issue References

Link to issues that implement parts of the spec:

## Requirements

1. Support OAuth 2.0 [[@ISSUE-001]]
2. Multi-factor auth [[@ISSUE-002]]

The [[@ISSUE-XXX]] syntax creates a bidirectional link:

The spec knows which issues implement it
The issue knows which spec requirements it addresses

Spec References

Link to related specs:

See also [[SPEC-010]] for API design patterns.

The [[SPEC-XXX]] syntax links specs together for cross-cutting concerns.

Automatic Backlinks: sudocode automatically tracks all references in both directions for easy graph traversal.

Hierarchical Organization

Specs can be organized hierarchically using parent-child relationships:

# Create a parent spec
sudocode spec create "Authentication System" --priority 0

# Create child specs
sudocode spec create "OAuth 2.0 Integration" --parent SPEC-001
sudocode spec create "Session Management" --parent SPEC-001
sudocode spec create "Password Reset Flow" --parent SPEC-001

This creates a hierarchy:

SPEC-001: Authentication System (parent)
├── SPEC-002: OAuth 2.0 Integration
├── SPEC-003: Session Management
└── SPEC-004: Password Reset Flow

Use hierarchies to:

Break complex specs into manageable pieces
Organize related specs
Maintain different levels of detail
Enable progressive disclosure

Priority Levels

Specs use a 0-4 priority scale:

Priority Levels

0 - Critical (highest priority)
1 - High
2 - Medium (default)
3 - Low
4 - Lowest

Priority affects:

Execution order (combined with dependencies)
Which work agents tackle first
Visibility in queries and reports

Storage and Versioning

Specs are stored in three synchronized layers:

.sudocode/
├── specs/
│   ├── specs.jsonl           # Source of truth (git-tracked)
│   ├── auth-system.md        # Human-editable markdown
│   ├── oauth-integration.md
│   └── session-mgmt.md
└── cache.db                   # SQLite cache (gitignored)

Markdown Files (.md)

Purpose: Human-editable interface

Located in .sudocode/specs/
YAML frontmatter + markdown body
Edit directly or via CLI
Synced to JSONL automatically

JSONL File (specs.jsonl)

Purpose: Source of truth, git-tracked

One JSON object per line
Contains all spec data
Committed to version control
Used for distribution via git

SQLite Cache (cache.db)

Purpose: Fast queries and relationships

Rebuilt from JSONL after git pull
Enables efficient graph queries
Not committed to git
Auto-synced from JSONL

Git-Native: Specs are version-controlled artifacts. Track requirements alongside code and see how they evolve over time.

Best Practices

When to Create a Spec

✅ Good candidates for specs

New features or major changes
Architectural decisions
Design documents that agents will implement
Research questions requiring investigation
Requirements that will generate multiple issues
Cross-cutting concerns affecting multiple areas

❌ Not good candidates for specs

Simple bug fixes (create issue directly)
Trivial changes (no spec needed)
Implementation details (belongs in issues)
Temporary notes (use comments or docs)

Writing Effective Specs

Start with WHY

Explain the problem you’re solving and why it matters

Define clear requirements

Use numbered lists and link to issues as you create them

Make design decisions explicit

Document choices and reasoning for future reference

Link related specs

Use [[SPEC-XXX]] to connect cross-cutting concerns

Keep it evolving

Update specs based on feedback from implementation

Spec vs Issue Decision Matrix

Aspect	Spec	Issue
Scope	High-level, multi-component	Single task, agent-scoped
Author	Primarily humans	Humans or agents
Lifecycle	Long-lived, evolves	Closed when complete
Detail	WHAT and WHY	HOW and acceptance criteria
Relationships	Links to issues, other specs	Links to spec, blockers

Rule of thumb: If it requires more than one agent session or multiple independent tasks, it’s probably a spec. If it’s a single actionable task, it’s an issue.

CLI Commands

Quick reference for working with specs:

# Create a spec
sudocode spec create "Feature Title" --type feature --priority 1

# List all specs
sudocode spec list

# Filter by status or type
sudocode spec list --status approved --type architecture

# View spec details
sudocode spec show SPEC-001

# Update spec
sudocode spec update SPEC-001 --status approved --priority 0

# Delete spec
sudocode spec delete SPEC-001

Complete CLI Reference

See full documentation for all spec commands and options

Common Workflows

Creating a Spec-Driven Feature

Create the spec

sudocode spec create "User Dashboard" \
  --type feature \
  --priority 1 \
  --tags frontend,ux

Write requirements and design

Edit .sudocode/specs/user-dashboard.md with your requirements

Create issues from spec

Use CLI or let an agent create issues linked to the spec:

sudocode issue create "Build dashboard layout" \
  --priority 1
sudocode link ISSUE-001 SPEC-001 --type implements

Track implementation feedback

As agents work on issues, they can provide feedback:

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Need responsive breakpoints specified" \
  --line 42

Iterate and refine

Update spec based on learnings from implementation

Next Steps

Issues

Learn about issues - the actionable work items derived from specs

Relationships

Understand how specs connect to issues and other specs

Feedback System

See how agents provide feedback on specs during implementation

Spec Commands

Complete CLI reference for managing specs

Getting Started

Examples & Tutorials

Core Concepts

Specs (Specifications)

What Are Specs?

Specs vs. Issues

Specs

Issues

Spec Lifecycle

Spec Types

Spec Structure

File Format

Cross-References and Links

Issue References

Spec References

Hierarchical Organization

Priority Levels

Storage and Versioning

Best Practices

When to Create a Spec

Writing Effective Specs

Spec vs Issue Decision Matrix

CLI Commands

Complete CLI Reference

Common Workflows

Creating a Spec-Driven Feature

Next Steps

Issues

Relationships

Feedback System

Spec Commands

​What Are Specs?

​Specs vs. Issues

Specs

Issues

​Spec Lifecycle

​Spec Types

​Spec Structure

​File Format

​Cross-References and Links

​Issue References

​Spec References

​Hierarchical Organization

​Priority Levels

​Storage and Versioning

​Best Practices

​When to Create a Spec

​Writing Effective Specs

​Spec vs Issue Decision Matrix

​CLI Commands

Complete CLI Reference

​Common Workflows

​Creating a Spec-Driven Feature

​Next Steps

Issues

Relationships

Feedback System

Spec Commands

What Are Specs?

Specs vs. Issues

Spec Lifecycle

Spec Types

Spec Structure

File Format

Cross-References and Links

Issue References

Spec References

Hierarchical Organization

Priority Levels

Storage and Versioning

Best Practices

When to Create a Spec

Writing Effective Specs

Spec vs Issue Decision Matrix

CLI Commands

Common Workflows

Creating a Spec-Driven Feature

Next Steps