Skip to main content

​
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:
Specs start as drafts when first created. Use this status while:
  • Gathering requirements
  • Iterating on design
  • Adding details
  • Getting feedback from agents during implementation
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 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 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:
TypePurposeExample
architectureSystem design and structure”Microservices migration plan”
apiAPI design and contracts”REST API v2 design”
databaseData models and schemas”User data model redesign”
featureProduct features”Multi-factor authentication”
researchInvestigation 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)
Flexible Content: The markdown body is completely flexible - no enforced structure. Organize sections however makes sense for your spec.
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:
  • 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)
Purpose: Human-editable interface
  • Located in .sudocode/specs/
  • YAML frontmatter + markdown body
  • Edit directly or via CLI
  • Synced to JSONL automatically
Purpose: Source of truth, git-tracked
  • One JSON object per line
  • Contains all spec data
  • Committed to version control
  • Used for distribution via git
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

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

1

Start with WHY

Explain the problem you’re solving and why it matters
2

Define clear requirements

Use numbered lists and link to issues as you create them
3

Make design decisions explicit

Document choices and reasoning for future reference
4

Link related specs

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

Keep it evolving

Update specs based on feedback from implementation

​
Spec vs Issue Decision Matrix

AspectSpecIssue
ScopeHigh-level, multi-componentSingle task, agent-scoped
AuthorPrimarily humansHumans or agents
LifecycleLong-lived, evolvesClosed when complete
DetailWHAT and WHYHOW and acceptance criteria
RelationshipsLinks to issues, other specsLinks 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

1

Create the spec

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

Write requirements and design

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

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
4

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
5

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