sudocode spec create

Syntax

sudocode spec create <title> [options]

Description

The spec create command creates a new specification document in your sudocode project. Specs are the first tier in sudocode’s abstraction structure, capturing what you want to build (user intent) rather than how to implement it. When you create a spec, sudocode:

Generates a unique spec ID (e.g., SPEC-001, SPEC-002)
Creates a markdown file in .sudocode/specs/ directory
Adds the spec to the SQLite database
Exports to JSONL for version control
Applies any tags you specify

Specs are version-controlled artifacts that live alongside your code. They evolve based on feedback from implementation.

Arguments

string

required

The title of your specExample: "Authentication System Design"The title should be clear and descriptive. It will be used to generate the markdown filename if --file-path is not specified.

Options

number

default:"2"

Priority level (0-4, where 0 is highest)Example: --priority 1Priority levels:

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

string

Initial description/content for the specExample: --description "This spec defines our OAuth 2.0 implementation"This becomes the markdown content below the frontmatter. You can edit the markdown file later to add more detail.

string

Custom file path for the markdown fileExample: --file-path "auth-oauth2.md"If not provided, sudocode generates a filename based on the title. The path is relative to .sudocode/specs/.

string

Parent spec ID for hierarchical organizationExample: --parent SPEC-001Use this to create child specs under a parent spec, enabling hierarchical organization of related specifications.

string

Comma-separated tags for organizationExample: --tags "auth,security,backend"Tags help with filtering and organizing specs. Use commas to separate multiple tags (no spaces).

Examples

Basic Spec Creation

Create a simple spec with default priority:

sudocode spec create "Authentication System"

Expected output

✓ Created spec SPEC-001
  Title: Authentication System
  File: specs/authentication-system.md

This creates:

Spec ID: SPEC-001
File: .sudocode/specs/authentication-system.md
Priority: 2 (default)
Empty content

Spec with Description and Priority

Create a high-priority spec with initial content:

sudocode spec create "OAuth 2.0 Integration" \
  --priority 1 \
  --description "Implement OAuth 2.0 for third-party authentication"

Expected output

✓ Created spec SPEC-002
  Title: OAuth 2.0 Integration
  File: specs/oauth-20-integration.md

The markdown file will contain:

---
id: SPEC-002
title: OAuth 2.0 Integration
priority: 1
created_at: 2025-10-29T10:00:00Z
---

Implement OAuth 2.0 for third-party authentication

Hierarchical Spec (Child Spec)

Create a child spec under a parent:

sudocode spec create "Session Management" \
  --parent SPEC-001 \
  --priority 1

Expected output

✓ Created spec SPEC-003
  Title: Session Management
  File: specs/session-management.md

This creates a hierarchy:

SPEC-001: Authentication System (parent)
└── SPEC-003: Session Management (child)

Spec with Tags

Create a spec with multiple tags for organization:

sudocode spec create "API Rate Limiting" \
  --priority 2 \
  --tags "api,security,performance"

Expected output

✓ Created spec SPEC-004
  Title: API Rate Limiting
  File: specs/api-rate-limiting.md

The markdown file includes tags in the frontmatter:

---
id: SPEC-004
title: API Rate Limiting
priority: 2
tags: [api, security, performance]
created_at: 2025-10-29T10:00:00Z
---

Custom File Path

Specify a custom filename:

sudocode spec create "Database Schema" \
  --file-path "db-schema-v2.md" \
  --priority 0

Expected output

✓ Created spec SPEC-005
  Title: Database Schema
  File: specs/db-schema-v2.md

After Creating a Spec

After creating your spec, you can:

Edit the Spec

# Edit the markdown file directly
vim .sudocode/specs/SPEC-001.md

View Spec Details

sudocode spec show SPEC-001

Create Implementation Issues

sudocode issue create "Implement login"
sudocode link ISSUE-001 SPEC-001 --type implements

Add to Parent Spec

sudocode spec update SPEC-001 --parent SPEC-005

Spec File Structure

Created specs have this structure:

.sudocode/
├── specs/
│   └── authentication-system.md    # Markdown file (gitignored)
├── specs.jsonl                      # Source of truth (git-tracked)
└── cache.db                         # SQLite cache (gitignored)

The markdown file contains YAML frontmatter + content:

---
id: SPEC-001
title: Authentication System
priority: 2
created_at: 2025-10-29T10:00:00Z
updated_at: 2025-10-29T10:00:00Z
---

# Authentication System

Your spec content goes here. You can use full markdown:

## Requirements

1. Support OAuth 2.0 [[@ISSUE-001]]
2. Session management [[@ISSUE-002]]

## Design Decisions

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

Common Workflows

Creating a Feature Spec

Create the spec

sudocode spec create "User Dashboard" \
  --priority 1 \
  --tags "frontend,ux" \
  --description "Design and implement the user dashboard interface"

Edit with details

Edit .sudocode/specs/user-dashboard.md to add:

Requirements
Design decisions
Open questions

Create implementation issues

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

Creating an Architecture Spec

Create parent spec

sudocode spec create "Microservices Architecture" \
  --priority 0 \
  --tags "architecture,design"

Create child specs

sudocode spec create "Service Communication" --parent SPEC-001
sudocode spec create "Data Storage Strategy" --parent SPEC-001
sudocode spec create "Deployment Pipeline" --parent SPEC-001

View hierarchy

sudocode spec show SPEC-001

JSON Output

Use the global --json flag for machine-readable output:

sudocode --json spec create "Test Spec" --priority 1

JSON output

{
  "id": "SPEC-001",
  "title": "Test Spec",
  "file_path": "specs/test-spec.md"
}

Common Questions

Can I change the spec ID after creation?

No, spec IDs are immutable and generated sequentially. They ensure stable references across the system.

What's the difference between description and editing the file?

The --description flag sets initial content when creating the spec. After creation, you typically edit the markdown file directly for more detailed content.

Should I create a spec or an issue?

Create a spec if:

It requires multiple independent tasks
It’s strategic/architectural
It captures WHAT to build

Create an issue if:

It’s a single actionable task
It captures HOW to implement
An agent can complete it in one session

Can I have specs without issues?

Yes! Specs can exist independently. You create issues from specs as you plan implementation.

How do I link specs to other specs?

Use Obsidian-style syntax in the markdown content:

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

Or create explicit relationships:

sudocode link SPEC-001 SPEC-010 --type references

Troubleshooting

Error: sudocode not initialized

Cause: No .sudocode/ directory foundSolution:

sudocode init

Error: Invalid priority value

Cause: Priority must be 0-4Solution:

# Use a valid priority
sudocode spec create "My Spec" --priority 2

Spec created but file not found

Cause: The markdown file is created in .sudocode/specs/, not the current directorySolution:

ls .sudocode/specs/
# or
sudocode spec show SPEC-001

spec list

List all specs with filtering

spec show

View spec details

spec update

Update existing spec

issue create

Create implementation issues

link

Link specs to issues

init

Initialize sudocode project

Next Steps

Create your first spec

sudocode spec create "My Feature" --priority 1

Edit the spec content

Add requirements, design decisions, and questions

Create implementation issues

sudocode issue create "Implement X"
sudocode link ISSUE-001 SPEC-001 --type implements

Track implementation

sudocode spec show SPEC-001

Specs Concept Guide

Learn more about specs and their role in sudocode’s abstraction structure

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

sudocode spec create

Syntax

Description

Arguments

Options

Examples

Basic Spec Creation

Spec with Description and Priority

Hierarchical Spec (Child Spec)

Spec with Tags

Custom File Path

After Creating a Spec

Edit the Spec

View Spec Details

Create Implementation Issues

Add to Parent Spec

Spec File Structure

Common Workflows

Creating a Feature Spec

Creating an Architecture Spec

JSON Output

Common Questions

Troubleshooting

spec list

spec show

spec update

issue create

link

init

Next Steps

Specs Concept Guide

​Syntax

​Description

​Arguments

​Options

​Examples

​Basic Spec Creation

​Spec with Description and Priority

​Hierarchical Spec (Child Spec)

​Spec with Tags

​Custom File Path

​After Creating a Spec

Edit the Spec

View Spec Details

Create Implementation Issues

Add to Parent Spec

​Spec File Structure

​Common Workflows

​Creating a Feature Spec

​Creating an Architecture Spec

​JSON Output

​Common Questions

​Troubleshooting

​Related Commands

spec list

spec show

spec update

issue create

link

init

​Next Steps

Specs Concept Guide

Syntax

Description

Arguments

Options

Examples

Basic Spec Creation

Spec with Description and Priority

Hierarchical Spec (Child Spec)

Spec with Tags

Custom File Path

After Creating a Spec

Spec File Structure

Common Workflows

Creating a Feature Spec

Creating an Architecture Spec

JSON Output

Common Questions

Troubleshooting

Related Commands

Next Steps