skills.rest
cristoslc
cristoslcCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

spec-management

Create, validate, and transition specification artifacts through lifecycle phases in a docs directory.

Updated Dec 20, 2025
Search Tags:#documentation#validation#adr#lifecycle#dependency graph#epic#spec management
One-click install
npx skills add https://github.com/cristoslc/LLM-personal-agent-patterns --skill spec-management-cristoslc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec-management
Source: https://github.com/cristoslc/LLM-personal-agent-patterns/tree/main/L3-agents-core/.agents/skills/spec-management
Command: npx skills add https://github.com/cristoslc/LLM-personal-agent-patterns --skill spec-management-cristoslc

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, fswatch, and includes scripts (resource) and references (resource) components.

What problem does it solve? Managing product and engineering documentation (visions, epics, specs, stories, ADRs, bugs) across a repository becomes chaotic as artifacts multiply: references break, lifecycle phases drift out of sync with folder structure, and dependency relationships become untraceable. This Skill provides a canonical artifact model with lifecycle management, cross-reference validation, and dependency graph tooling. ## Core Features & Use Cases - Artifact lifecycle management: Create and transition 11 artifact types (Vision, Journey, Epic, Story, Spec, Spike, ADR, Persona, Runbook, Bug, Design) through defined phase sequences with lifecycle tables and index maintenance. - Stale reference detection: The specwatch.sh script scans markdown links and frontmatter references for broken paths, unresolvable artifact IDs, and phase mismatches, with an optional fswatch-based background watcher. - Dependency graph queries: The specgraph.sh script builds a cached JSON graph from frontmatter and answers questions like what blocks an artifact, what is ready to work on, and renders hierarchy overviews and Mermaid diagrams. - Use Case: When a user asks to implement a spec, the Skill validates dependencies via the graph, chains into execution-tracking to create a tracked plan, and refreshes the lifecycle index after every operation. ## Quick Start Ask the agent to create a new epic under your product vision and show the current artifact dependency overview.

Frequently Asked Questions about spec-management

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a new spec or epic artifact in a docs folder?▼

Scan the target docs/<type> directory for the next available number, read the artifact's definition and template from references/, create it in the first phase subdirectory, populate required frontmatter, initialize the lifecycle table, and refresh the list-<type>.md index.

How do I detect broken links and stale references in markdown documentation?▼

Run scripts/specwatch.sh scan to check markdown link paths and frontmatter artifact references like depends-on, parent-epic, and linked-adrs. Findings are written to .agents/specwatch.log with suggested corrections based on artifact ID lookup.

How do I query artifact dependencies to decide what to work on next?▼

Use scripts/specgraph.sh with commands like ready, next, blocks <ID>, or tree <ID>. The script builds a cached JSON graph from frontmatter and reports unblocked artifacts, transitive dependency chains, and what completing an item would unblock.

Does the stale reference watcher require any external tools?▼

The scan subcommand needs only Python 3 and the filesystem. The background watch mode requires fswatch, installable via brew, apt, or cargo, and uses a sentinel-based inactivity timeout.

When should execution-tracking be invoked for a spec artifact?▼

Execution-tracking is required when a SPEC, STORY, or BUG comes up for implementation, meaning the user intends to start building. For EPIC, VISION, or JOURNEY containers, decompose into implementable children first and track those instead.

What happens if an artifact's folder phase doesn't match its frontmatter status?▼

Run specwatch.sh phase-fix to detect mismatches between frontmatter status and phase subdirectories. It stages git mv operations to relocate artifacts into the correct phase folders, then rescans for stale references caused by the moves.

Related Skills

Explore More Product & Management Skills→
twofourlabstwofourlabs
7

docs-submodule-manager

Automate docs submodule initialization, syncing, and committing with structured directories.

Official
Basic
getcrew44getcrew44
358

brainstorming

Convert user intent into an approved design specification with clarifying questions.

Official
Advanced
swszzswszz
3

ontologian-validate

Validate multi-domain ontology schemas and cross-domain referential integrity.

Community
Advanced
lsst-sqrelsst-sqre
2

github-issues

Synchronize GitHub issues with local .issues directory plans using gh CLI workflows.

Official
Advanced