Spec Lifecycle

Manages the state machine for feature specs in .context/specs/. Keeps the active specs directory clean and ensures completed work is properly archived.

When to Use This Skill

Creating a new feature spec
Updating spec status during development
Completing and archiving a feature spec
Reviewing active specs for staleness

Spec States

┌──────────┐     ┌──────────────┐     ┌───────────┐     ┌──────────┐
│ Created  │────▶│ In Progress  │────▶│ Completed │────▶│ Archived │
└──────────┘     └──────────────┘     └───────────┘     └──────────┘
     │                  │                                      ▲
     │                  ▼                                      │
     │           ┌──────────┐                                  │
     └──────────▶│ Blocked  │──────────────────────────────────┘
                 └──────────┘

State	Marker	Location
Created	`Status: [ ] Not Started`	`.context/specs/`
In Progress	`Status: [/] In Progress`	`.context/specs/`
Blocked	`Status: [!] Blocked`	`.context/specs/`
Completed	`Status: [x] Completed`	`.context/specs/`
Archived	(moved)	`.context/specs/.archive/`

Operations

Create a Spec

Copy .context/specs/_template.md to .context/specs/feat-{name}.md or fix-{name}.md
Fill in: Goal, User Story, Requirements
Set status to [ ] Not Started
Set priority and date

Naming convention:

Features: feat-{short-description}.md (e.g., feat-user-auth.md)
Bug fixes: fix-{short-description}.md (e.g., fix-payment-timeout.md)
Performance: perf-{short-description}.md (e.g., perf-query-optimization.md)

Start Work on a Spec

Change status marker from [ ] to [/]
Update the Last Updated field
Ensure the Implementation Plan section is filled in

Complete a Spec

Change status marker from [/] to [x]
Update the Last Updated field
Verify all acceptance criteria are checked [x]
Trigger context-sync to update project.md

Archive a Spec

Move the completed spec file to .context/specs/.archive/
Remove any references to it from active documentation

git mv .context/specs/feat-{name}.md .context/specs/.archive/

Staleness Detection

A spec is considered stale if:

Status is [/] In Progress for more than 14 days without updates
Status is [ ] Not Started for more than 30 days
Status is [!] Blocked with no blocker description

When detected, report:

⚠️ STALE SPECS DETECTED:
- feat-dashboard-api.md — In Progress for 21 days (last updated: 2026-01-28)
- fix-cache-invalidation.md — Not Started for 35 days

Recommended action: Review and update or archive these specs.

Dashboard View

When asked for spec status, produce:

📋 SPEC DASHBOARD
─────────────────
Active:    2 specs
Blocked:   0 specs
Completed: 1 spec (pending archive)
Archived:  8 specs

ACTIVE SPECS:
  [/] feat-user-auth.md      — Priority: High — 5 days in progress
  [ ] feat-dashboard-api.md  — Priority: Medium — Not started

PENDING ARCHIVE:
  [x] fix-payment-timeout.md — Completed 3 days ago

spec-lifecycle