specdev_skill

Overview

This skill provides a specification-driven development workflow for AI agents, enabling persistent, structured specs that survive across sessions. It focuses on JSON-first artifacts and token-optimized outputs so agents can implement multi-step features, coordinate cross-file changes, and track progress reliably. Use it to manage complex features, brownfield modifications, and long-running requirements.

How this skill works

The tool creates and maintains a .specs directory with spec.md (requirements), plan.md (technical approach), and tasks.yaml (task breakdown). CLI commands initialize specs, create new specs, show status, return context at different verbosity levels, validate and compact files, and archive completed work. Outputs are JSON-formatted for easy agent consumption and include error codes and hints for consistent automation.

When to use it

• When a task is too large for a single agent session or chat turn.
• When work spans multiple files, features, or engineers and needs persisted requirements.
• When implementing brownfield changes that require deltas (added/modified/removed).
• When you need token-optimized context for LLM-based agents to reduce cost and improve focus.
• When formal progress tracking and archival of completed specs is required.

Best practices

• Start each feature with specdev init, specdev new {name}, then fill spec.md → plan.md → tasks.yaml.
• Use context levels: min for focused implementation, standard for normal work, full for onboarding or planning sessions.
• Compact large files before feeding them to agents to reduce token usage (~60% typical reduction).
• Keep tasks.yaml task IDs and done flags authoritative for progress reporting and automation hooks.
• Create delta.md for brownfield work and reference requirement IDs to avoid ambiguity.

Example use cases

• New feature development: create spec, draft plan, break work into tasks, iterate across sessions.
• Cross-file refactor: document intended changes in delta.md, use tasks.yaml to sequence modifications and tests.
• Long-lived features: persist requirements and checkpoints across days or sprints, resume with context --level min.
• Agent-driven implementation: call context to get current task, run Explore/Plan agents, validate tasks.yaml after edits.
• Archival and compliance: validate and archive completed specs for audit or knowledge reuse.