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

# Specs (Specifications)

> Capture user intent, requirements, and design decisions

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

<Note>
  **Key Principle:** Specs capture what humans want. Issues (tier 2) capture how agents will implement it.
</Note>

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

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines">
    **User intent** (WHAT)

    * Written by humans
    * Requirements and design
    * Long-lived documentation
    * Evolve with learnings
  </Card>

  <Card title="Issues" icon="list-check">
    **Agent tasks** (HOW)

    * Created from specs
    * Actionable work items
    * Task-level granularity
    * Closed when complete
  </Card>
</CardGroup>

## Spec Lifecycle

Specs progress through a defined lifecycle from creation to completion:

```mermaid theme={null}
graph LR
    A[draft] --> B[review]
    B --> C[approved]
    C --> D[deprecated]
    B -.-> A
    style A fill:#6B9AFF
    style B fill:#A855F7
    style C fill:#10B981
    style D fill:#6B7280
```

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

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

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

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

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

<CodeGroup>
  ```markdown Example Spec theme={null}
  ---
  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)
  ```

  ```yaml Frontmatter Schema theme={null}
  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
  ```
</CodeGroup>

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

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

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

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

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

<Check>
  **Automatic Backlinks:** sudocode automatically tracks all references in both directions for easy graph traversal.
</Check>

## Hierarchical Organization

Specs can be organized hierarchically using parent-child relationships:

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

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

## 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)
```

<AccordionGroup>
  <Accordion title="Markdown Files (.md)">
    **Purpose:** Human-editable interface

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

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

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

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

## Best Practices

### When to Create a Spec

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

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

### Writing Effective Specs

<Steps>
  <Step title="Start with WHY">
    Explain the problem you're solving and why it matters
  </Step>

  <Step title="Define clear requirements">
    Use numbered lists and link to issues as you create them
  </Step>

  <Step title="Make design decisions explicit">
    Document choices and reasoning for future reference
  </Step>

  <Step title="Link related specs">
    Use `[[SPEC-XXX]]` to connect cross-cutting concerns
  </Step>

  <Step title="Keep it evolving">
    Update specs based on feedback from implementation
  </Step>
</Steps>

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

<Warning>
  **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.
</Warning>

## CLI Commands

Quick reference for working with specs:

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

<Card title="Complete CLI Reference" icon="terminal" href="/cli/overview">
  See full documentation for all spec commands and options
</Card>

## Common Workflows

### Creating a Spec-Driven Feature

<Steps>
  <Step title="Create the spec">
    ```bash theme={null}
    sudocode spec create "User Dashboard" \
      --type feature \
      --priority 1 \
      --tags frontend,ux
    ```
  </Step>

  <Step title="Write requirements and design">
    Edit `.sudocode/specs/user-dashboard.md` with your requirements
  </Step>

  <Step title="Create issues from spec">
    Use CLI or let an agent create issues linked to the spec:

    ```bash theme={null}
    sudocode issue create "Build dashboard layout" \
      --priority 1
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Track implementation feedback">
    As agents work on issues, they can provide feedback:

    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --content "Need responsive breakpoints specified" \
      --line 42
    ```
  </Step>

  <Step title="Iterate and refine">
    Update spec based on learnings from implementation
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Issues" icon="list-check" href="/concepts/issues">
    Learn about issues - the actionable work items derived from specs
  </Card>

  <Card title="Relationships" icon="diagram-project" href="/concepts/relationships">
    Understand how specs connect to issues and other specs
  </Card>

  <Card title="Feedback System" icon="comments" href="/concepts/feedback">
    See how agents provide feedback on specs during implementation
  </Card>

  <Card title="Spec Commands" icon="terminal" href="/cli/spec-create">
    Complete CLI reference for managing specs
  </Card>
</CardGroup>