> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode spec create

> Create a new spec to capture user intent, requirements, and design decisions

## Syntax

```bash theme={null}
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

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

## Arguments

<ParamField path="title" type="string" required>
  The title of your spec

  **Example:** `"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.
</ParamField>

## Options

<ParamField path="-p, --priority" type="number" default="2">
  Priority level (0-4, where 0 is highest)

  **Example:** `--priority 1`

  Priority levels:

  * **0** - Critical (highest priority)
  * **1** - High
  * **2** - Medium (default)
  * **3** - Low
  * **4** - Lowest
</ParamField>

<ParamField path="-d, --description" type="string">
  Initial description/content for the spec

  **Example:** `--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.
</ParamField>

<ParamField path="--file-path" type="string">
  Custom file path for the markdown file

  **Example:** `--file-path "auth-oauth2.md"`

  If not provided, sudocode generates a filename based on the title. The path is relative to `.sudocode/specs/`.
</ParamField>

<ParamField path="--parent" type="string">
  Parent spec ID for hierarchical organization

  **Example:** `--parent SPEC-001`

  Use this to create child specs under a parent spec, enabling hierarchical organization of related specifications.
</ParamField>

<ParamField path="--tags" type="string">
  Comma-separated tags for organization

  **Example:** `--tags "auth,security,backend"`

  Tags help with filtering and organizing specs. Use commas to separate multiple tags (no spaces).
</ParamField>

## Examples

### Basic Spec Creation

Create a simple spec with default priority:

```bash theme={null}
sudocode spec create "Authentication System"
```

<Accordion title="Expected output">
  ```
  ✓ Created spec SPEC-001
    Title: Authentication System
    File: specs/authentication-system.md
  ```
</Accordion>

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:

```bash theme={null}
sudocode spec create "OAuth 2.0 Integration" \
  --priority 1 \
  --description "Implement OAuth 2.0 for third-party authentication"
```

<Accordion title="Expected output">
  ```
  ✓ Created spec SPEC-002
    Title: OAuth 2.0 Integration
    File: specs/oauth-20-integration.md
  ```
</Accordion>

The markdown file will contain:

```markdown theme={null}
---
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:

```bash theme={null}
sudocode spec create "Session Management" \
  --parent SPEC-001 \
  --priority 1
```

<Accordion title="Expected output">
  ```
  ✓ Created spec SPEC-003
    Title: Session Management
    File: specs/session-management.md
  ```
</Accordion>

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:

```bash theme={null}
sudocode spec create "API Rate Limiting" \
  --priority 2 \
  --tags "api,security,performance"
```

<Accordion title="Expected output">
  ```
  ✓ Created spec SPEC-004
    Title: API Rate Limiting
    File: specs/api-rate-limiting.md
  ```
</Accordion>

The markdown file includes tags in the frontmatter:

```yaml theme={null}
---
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:

```bash theme={null}
sudocode spec create "Database Schema" \
  --file-path "db-schema-v2.md" \
  --priority 0
```

<Accordion title="Expected output">
  ```
  ✓ Created spec SPEC-005
    Title: Database Schema
    File: specs/db-schema-v2.md
  ```
</Accordion>

## After Creating a Spec

After creating your spec, you can:

<CardGroup cols={2}>
  <Card title="Edit the Spec" icon="pen-to-square">
    ```bash theme={null}
    # Edit the markdown file directly
    vim .sudocode/specs/SPEC-001.md
    ```
  </Card>

  <Card title="View Spec Details" icon="eye" href="/cli/spec-show">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Card>

  <Card title="Create Implementation Issues" icon="list-check" href="/cli/issue-create">
    ```bash theme={null}
    sudocode issue create "Implement login"
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Card>

  <Card title="Add to Parent Spec" icon="sitemap">
    ```bash theme={null}
    sudocode spec update SPEC-001 --parent SPEC-005
    ```
  </Card>
</CardGroup>

## 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:

```markdown theme={null}
---
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

<Steps>
  <Step title="Create the spec">
    ```bash theme={null}
    sudocode spec create "User Dashboard" \
      --priority 1 \
      --tags "frontend,ux" \
      --description "Design and implement the user dashboard interface"
    ```
  </Step>

  <Step title="Edit with details">
    Edit `.sudocode/specs/user-dashboard.md` to add:

    * Requirements
    * Design decisions
    * Open questions
  </Step>

  <Step title="Create implementation issues">
    ```bash theme={null}
    sudocode issue create "Build dashboard layout"
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>
</Steps>

### Creating an Architecture Spec

<Steps>
  <Step title="Create parent spec">
    ```bash theme={null}
    sudocode spec create "Microservices Architecture" \
      --priority 0 \
      --tags "architecture,design"
    ```
  </Step>

  <Step title="Create child specs">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="View hierarchy">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>
</Steps>

## JSON Output

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

```bash theme={null}
sudocode --json spec create "Test Spec" --priority 1
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "id": "SPEC-001",
    "title": "Test Spec",
    "file_path": "specs/test-spec.md"
  }
  ```
</Accordion>

## Common Questions

<AccordionGroup>
  <Accordion title="Can I change the spec ID after creation?">
    No, spec IDs are immutable and generated sequentially. They ensure stable references across the system.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Can I have specs without issues?">
    Yes! Specs can exist independently. You create issues from specs as you plan implementation.
  </Accordion>

  <Accordion title="How do I link specs to other specs?">
    Use Obsidian-style syntax in the markdown content:

    ```markdown theme={null}
    See also [[SPEC-010]] for API patterns.
    ```

    Or create explicit relationships:

    ```bash theme={null}
    sudocode link SPEC-001 SPEC-010 --type references
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: sudocode not initialized">
    **Cause:** No `.sudocode/` directory found

    **Solution:**

    ```bash theme={null}
    sudocode init
    ```
  </Accordion>

  <Accordion title="Error: Invalid priority value">
    **Cause:** Priority must be 0-4

    **Solution:**

    ```bash theme={null}
    # Use a valid priority
    sudocode spec create "My Spec" --priority 2
    ```
  </Accordion>

  <Accordion title="Spec created but file not found">
    **Cause:** The markdown file is created in `.sudocode/specs/`, not the current directory

    **Solution:**

    ```bash theme={null}
    ls .sudocode/specs/
    # or
    sudocode spec show SPEC-001
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="spec list" icon="list" href="/cli/spec-list">
    List all specs with filtering
  </Card>

  <Card title="spec show" icon="eye" href="/cli/spec-show">
    View spec details
  </Card>

  <Card title="spec update" icon="pen-to-square" href="/cli/spec-update">
    Update existing spec
  </Card>

  <Card title="issue create" icon="plus" href="/cli/issue-create">
    Create implementation issues
  </Card>

  <Card title="link" icon="link" href="/cli/link">
    Link specs to issues
  </Card>

  <Card title="init" icon="folder-plus" href="/cli/init">
    Initialize sudocode project
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Create your first spec">
    ```bash theme={null}
    sudocode spec create "My Feature" --priority 1
    ```
  </Step>

  <Step title="Edit the spec content">
    Add requirements, design decisions, and questions
  </Step>

  <Step title="Create implementation issues">
    ```bash theme={null}
    sudocode issue create "Implement X"
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Track implementation">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>
</Steps>

<Card title="Specs Concept Guide" icon="book" href="/concepts/specs">
  Learn more about specs and their role in sudocode's abstraction structure
</Card>