/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 system CLI:

Generate Index

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

<plugin-root>/system/system-run.sh spec index --changes-dir changes/

Generate Snapshot

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

<plugin-root>/system/system-run.sh spec snapshot --specs-dir specs/

Validate Spec

Validates spec frontmatter and format.

# Validate single spec
<plugin-root>/system/system-run.sh spec validate changes/2026/01/21/my-change/SPEC.md

# Validate all specs
<plugin-root>/system/system-run.sh spec validate --all --specs-dir specs/

---

INDEX.md Format

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

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

# 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 `<plugin-root>/system/system-run.sh spec index` to update INDEX.md 3. Run `<plugin-root>/system/system-run.sh spec snapshot` to update SNAPSHOT.md 4. Commit the updated index and snapshot

Before Release

1. Run `<plugin-root>/system/system-run.sh spec validate --all` to ensure all specs are valid 2. Review SNAPSHOT.md for completeness 3. Verify all active specs have corresponding implementations

---