# Spec Schema Documentation

This document describes the JSON structure of SDD specification files.

## Overview

A specification file is a JSON document that defines:
- **Frontmatter**: Metadata about the spec (title, version, status)
- **Phases**: Major work stages containing tasks
- **Tasks**: Individual work items with status tracking
- **Hierarchy**: Parent-child relationships and dependencies

## File Location

Specs are stored in the `specs/` directory organized by lifecycle status:

```
specs/
├── pending/           # Not yet started
├── active/            # Currently in progress
├── completed/         # Finished successfully (all tasks done)
└── archived/          # Abandoned, superseded, or deprioritized
```

### Folder Semantics

| Folder | Status | Meaning |
|--------|--------|---------|
| `pending/` | `pending` | Spec created but work not started |
| `active/` | `in_progress` | Work is actively being done |
| `completed/` | `completed` | All work finished successfully |
| `archived/` | `archived` | Decided not to pursue (abandoned, superseded, deprioritized) |

**Key distinction**: Use `completed/` when all tasks are done. Use `archived/` when you decide not to finish the spec, regardless of progress.

## Spec ID Format

Spec IDs follow the pattern: `{name}-{date}-{sequence}`

Example: `user-authentication-2025-01-15-001`

---

## Top-Level Structure

```json
{
  "id": "my-feature-2025-01-15-001",
  "title": "My Feature Implementation",
  "description": "Brief description of the feature",
  "version": "1.0.0",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:22:00Z",
  "author": "developer@example.com",
  "category": "implementation",
  "mission": "Optional mission statement",
  "tags": ["feature", "api"],
  "hierarchy": { ... },
  "assumptions": [ ... ],
  "revisions": [ ... ],
  "metadata": { ... }
}
```

### Frontmatter Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique identifier |
| `title` | string | Yes | Human-readable title |
| `description` | string | No | Brief description |
| `version` | string | No | Semantic version |
| `status` | string | Yes | Current status |
| `created_at` | datetime | Yes | Creation timestamp (ISO 8601) |
| `updated_at` | datetime | Yes | Last update timestamp |
| `author` | string | No | Creator identifier |
| `category` | string | No | Default task category |
| `mission` | string | No | Mission statement |
| `tags` | array | No | Categorization tags |

### Status Values

| Status | Description |
|--------|-------------|
| `draft` | Initial creation, not validated |
| `pending` | Ready to start, not yet active |
| `active` | Currently in progress |
| `completed` | All tasks finished |
| `archived` | Historical, no longer active |

---

## Hierarchy Structure

The `hierarchy` object contains all phases, tasks, and their relationships.

### Node Types

| Type | Description |
|------|-------------|
| `spec-root` | Root node (auto-created) |
| `phase` | Major work stage |
| `task` | Work item |
| `subtask` | Child of a task |
| `verify` | Verification step |

### Phase Node

```json
{
  "phase-1": {
    "type": "phase",
    "title": "Phase 1: Setup",
    "description": "Initial setup and configuration",
    "status": "pending",
    "parent": "spec-root",
    "position": 1,
    "children": ["task-1-1", "task-1-2"],
    "metadata": {
      "priority": "high"
    }
  }
}
```

### Task Node

```json
{
  "task-1-1": {
    "type": "task",
    "title": "Create database schema",
    "description": "Design and implement the database schema",
    "status": "pending",
    "parent": "phase-1",
    "position": 1,
    "children": [],
    "category": "implementation",
    "acceptance_criteria": [
      "Schema supports all required entities",
      "Migrations are reversible"
    ],
    "dependencies": {
      "blocked_by": [],
      "blocks": ["task-1-2"]
    },
    "verification": {
      "type": "test",
      "command": "pytest tests/test_schema.py"
    },
    "metadata": {
      "complexity": "medium",
      "owners": ["backend-team"]
    }
  }
}
```

### Node Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Node type |
| `title` | string | Yes | Display title |
| `description` | string | No | Detailed description |
| `status` | string | Yes | Current status |
| `parent` | string | Yes | Parent node ID |
| `position` | integer | Yes | Order within parent (1-based) |
| `children` | array | Yes | Child node IDs |

### Task-Specific Fields

| Field | Type | Description |
|-------|------|-------------|
| `category` | string | Task category |
| `acceptance_criteria` | array | Completion requirements |
| `dependencies` | object | Dependency relationships |
| `verification` | object | Verification definition |
| `metadata` | object | Custom metadata |

---

## Task Status

| Status | Description |
|--------|-------------|
| `pending` | Not started |
| `in_progress` | Currently being worked on |
| `completed` | Finished successfully |
| `blocked` | Cannot proceed (has blocker) |
| `archived` | Abandoned or deprioritized (spec-root only) |

### Valid Transitions

```
pending → in_progress → completed
pending → blocked → pending → in_progress
in_progress → blocked → in_progress
```

---

## Dependencies

Dependencies define relationships between tasks.

```json
{
  "dependencies": {
    "blocked_by": ["task-1-1"],
    "blocks": ["task-1-3", "task-2-1"]
  }
}
```

| Field | Description |
|-------|-------------|
| `blocked_by` | Tasks that must complete first |
| `blocks` | Tasks waiting for this task |

### Dependency Rules

1. A task with `blocked_by` items cannot start until all are completed
2. Circular dependencies are invalid
3. The system validates dependency integrity on save

---

## Verification

Verification defines how to confirm task completion.

```json
{
  "verification": {
    "type": "test",
    "command": "pytest tests/test_feature.py",
    "expected_output": "All tests passed"
  }
}
```

### Verification Types

| Type | Description |
|------|-------------|
| `test` | Run automated tests |
| `manual` | Manual verification required |
| `review` | Code review required |
| `build` | Build must succeed |
| `deploy` | Deployment verification |

---

## Categories

Task categories help classify work:

| Category | Description |
|----------|-------------|
| `investigation` | Research and analysis |
| `implementation` | Code implementation |
| `refactoring` | Code improvement |
| `decision` | Decision point |
| `research` | External research |
| `documentation` | Documentation work |
| `testing` | Test creation |

---

## Assumptions and Revisions

### Assumptions

```json
{
  "assumptions": [
    {
      "id": "assumption-1",
      "text": "Database supports JSON columns",
      "type": "technical",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}
```

### Revisions

```json
{
  "revisions": [
    {
      "version": "1.1.0",
      "date": "2025-01-16T09:00:00Z",
      "author": "developer@example.com",
      "changes": "Added phase 3 for deployment"
    }
  ]
}
```

---

## Metadata

Custom metadata can be added at any level:

```json
{
  "metadata": {
    "complexity": "high",
    "priority": "p1",
    "owners": ["alice", "bob"],
    "labels": {
      "team": "platform",
      "quarter": "Q1"
    }
  }
}
```

Common metadata fields:

| Field | Type | Description |
|-------|------|-------------|
| `actual_hours` | number | Time spent |
| `complexity` | string | `low`, `medium`, `high` |
| `priority` | string | `p0`-`p4` |
| `owners` | array | Responsible parties |
| `labels` | object | Custom labels |

---

## Example: Complete Spec

```json
{
  "id": "user-auth-2025-01-15-001",
  "title": "User Authentication System",
  "description": "Implement JWT-based authentication",
  "version": "1.0.0",
  "status": "active",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T14:30:00Z",
  "author": "alice@example.com",
  "category": "implementation",
  "tags": ["auth", "security", "api"],
  "hierarchy": {
    "spec-root": {
      "type": "spec-root",
      "children": ["phase-1", "phase-2"]
    },
    "phase-1": {
      "type": "phase",
      "title": "Phase 1: Core Auth",
      "status": "in_progress",
      "parent": "spec-root",
      "position": 1,
      "children": ["task-1-1", "task-1-2"]
    },
    "task-1-1": {
      "type": "task",
      "title": "Implement JWT token generation",
      "status": "completed",
      "parent": "phase-1",
      "position": 1,
      "children": [],
      "category": "implementation",
      "dependencies": {
        "blocked_by": [],
        "blocks": ["task-1-2"]
      }
    },
    "task-1-2": {
      "type": "task",
      "title": "Add token validation middleware",
      "status": "in_progress",
      "parent": "phase-1",
      "position": 2,
      "children": [],
      "category": "implementation",
      "dependencies": {
        "blocked_by": ["task-1-1"],
        "blocks": []
      }
    },
    "phase-2": {
      "type": "phase",
      "title": "Phase 2: User Management",
      "status": "pending",
      "parent": "spec-root",
      "position": 2,
      "children": ["task-2-1"]
    },
    "task-2-1": {
      "type": "task",
      "title": "Create user registration endpoint",
      "status": "pending",
      "parent": "phase-2",
      "position": 1,
      "children": [],
      "category": "implementation"
    }
  },
  "assumptions": [
    {
      "id": "assumption-1",
      "text": "Using RS256 for JWT signing",
      "type": "technical"
    }
  ]
}
```

---

## Validation

Use the `validate` command to check spec validity:

```bash
foundry-cli validate check my-spec
foundry-cli validate fix my-spec --dry-run
```

Common validation issues:
- Missing required fields
- Invalid status values
- Circular dependencies
- Orphaned nodes
- Invalid parent references

---

## Related

- [CLI Command Reference](../04-cli-command-reference.md) - Spec commands
- [MCP Tool Reference](../05-mcp-tool-reference.md) - spec/authoring tools
- [Workflow Guide](../03-workflow-guide.md) - Using specs in practice
