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

Accepts index command and directory paths for changes and specs.

Output

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