Spec-Driven Development

A CLI tool for managing structured specifications that persist across sessions, with JSON output designed for AI agents.

1. CLI Discovery

The CLI is located at ./scripts/specdev-cli/ relative to this SKILL.md file.

Platform Script

Unix/Linux/macOS specdev

Windows specdev.ps1

Claude Code: Use ${CLAUDE_PLUGIN_ROOT}/skills/specdev/scripts/specdev-cli/specdev (or specdev.ps1 on Windows).

2. Commands

Command Description

init

Initialize .specs/ structure (idempotent)

new <name>

Create new spec with templates

list

List all active specs and progress

context <spec>

Get spec context (--level min|standard|full )

path <spec>

Get spec directory path

archive <spec>

Move completed spec to archived

validate <path>

Check spec file completeness

hook <event>

Run hook for event

3. Workflows

3.1 Creating Specs

Use when starting a new feature or complex task.

• Run specdev init (if no .specs/ exists)

• Run specdev new <name> to create spec structure with templates

• Write draft spec.md , plan.md , and tasks.yaml based on initial understanding

• Use AskUserQuestion to clarify ambiguities or validate assumptions

• Update spec files to reflect user answers

• Repeat steps 4-5 until spec is complete and clear

• Run specdev validate <name> to verify spec structure

• Present spec to user for final review before implementation

Tip: Always include verification methods in tasks (tests, assertions, manual checks). This creates feedback loops that catch errors early. Ask user for preferred verification approach if unclear.

3.2 Implementing Specs

Use when working on an existing spec.

• Run specdev list to see active specs

• Run specdev context <spec> --level standard to get current task

• Read referenced files, implement the task

• Run tests, verify implementation

• Update tasks.yaml

• mark task done: true

• Repeat from step 2 until all tasks complete

• Run specdev archive <spec> when 100% complete

References

Templates and patterns available in references/ directory:

• spec-template.md

• Specification format

• plan-template.md

• Planning format

• tasks-template.md

• Task breakdown format

• patterns.md

• Best practices