Spec Index

---
name: spec-index
description: Manage spec registry and generate snapshots.
user-invocable: false
---


# Spec Index Skill

## Commands

The spec commands are available via the sdd-system CLI:

### Generate Index

Generates `changes/INDEX.md` from all change spec files.

```bash
sdd-system spec index --changes-dir changes/
```

### Generate Snapshot

Generates `specs/SNAPSHOT.md` compiling all active specs.

```bash
sdd-system spec snapshot --specs-dir specs/
```

### Validate Spec

Validates spec frontmatter and format.

```bash
# Validate single spec
sdd-system spec validate changes/2026/01/21/my-change/SPEC.md

# Validate all specs
sdd-system spec validate --all --specs-dir specs/
```

---

## Prerequisites

- `sdd-system` CLI available in PATH (installed via the SDD plugin's npm package)

## INDEX.md Format

The index is a registry of all change specs, located at `changes/INDEX.md`:

```markdown
# Change Index

Last updated: YYYY-MM-DD

Total: X specs (Active: Y, Deprecated: Z, Archived: W)

## Active Changes

| Change | Type | Spec | Domain | Issue | Since |
|--------|------|------|--------|-------|-------|
| User Authentication | feature | [SPEC](2025/01/01/user-auth/SPEC.md) | Identity | [PROJ-123](url) | 2025-01-01 |

## Deprecated

| Change | Type | Spec | Domain | Issue | Deprecated |
|--------|------|------|--------|-------|------------|
| Old Auth | feature | [SPEC](2025/01/15/old-auth/SPEC.md) | Identity | [PROJ-100](url) | 2025-02-01 |

## Archived

*None*
```

Note: Links are relative within the `changes/` directory (e.g., `YYYY/MM/DD/...`).

---

## SNAPSHOT.md Format

The snapshot is a compiled view of current product state:

```markdown
# Product Snapshot

Generated: YYYY-MM-DD

This document represents the current active state of the product by compiling all active specifications.

## By Domain

### Identity

#### User Authentication
**Spec:** [changes/2025/01/01/user-auth/SPEC.md](changes/2025/01/01/user-auth/SPEC.md)
**Issue:** [PROJ-123](url)

[Summary of change capabilities]

---

### Billing

...
```

---

## Input

Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)

Accepts index command and directory paths for changes and specs.

## Output

Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)

Returns success status and any validation errors or warnings.

## Workflow

### After Creating a Spec

1. Merge spec to main
2. Run `sdd-system spec index` to update INDEX.md
3. Run `sdd-system spec snapshot` to update SNAPSHOT.md
4. Commit the updated index and snapshot

### Before Release

1. Run `sdd-system spec validate --all` to ensure all specs are valid
2. Review SNAPSHOT.md for completeness
3. Verify all active specs have corresponding implementations

---

## Automation

These scripts can be integrated into CI:

```yaml
# .github/workflows/validate-specs.yaml
name: Validate Specs

on:
  pull_request:
    paths:
      - 'changes/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Validate all specs
        run: npx sdd-system spec validate --all --changes-dir changes/

      - name: Check index is up-to-date
        run: |
          npx sdd-system spec index --changes-dir changes/
          git diff --exit-code changes/INDEX.md
```