Spec Task System

The Spec Task System is agentcmd's implementation of spec-driven development—a structured approach to managing feature specifications with built-in lifecycle tracking and workflow automation.

What is a Spec?

A spec is a markdown file with metadata about a feature:

# User Authentication Feature

**Status**: todo
**Created**: 2025-01-15
**Complexity**: 35 points
**Phases**: 4

## Overview

Implement JWT-based authentication...

## Tasks

- [ ] Create auth service
- [ ] Add login endpoint
- [ ] Implement token validation

Specs live in .agent/specs/{folder}/{timestamp-id}-{name}/spec.md and are organized by status folder (backlog, todo, done).

Spec Lifecycle

Specs flow through a simple workflow:

• backlog/ - Future work, not prioritized
• todo/ - Ready to work on
• doing - Currently implementing (stays in todo/ folder)
• done/ - Completed

Move specs between folders:

/cmd:move-spec auth-system todo
/cmd:move-spec auth-system done

Spec Types

agentcmd supports three built-in spec types:

You can also create custom spec types (e.g., "Refactor", "Security", "Performance") by adding files to .claude/commands/cmd/. See Creating Specs for a complete tutorial.

Generating Specs

Generate specs via slash commands:

/cmd:generate-feature-spec "User authentication system"
/cmd:generate-bug-spec "Login page crashes on mobile"
/cmd:generate-issue-spec "Refactor auth service for testability"

For the complete workflow—from planning conversations to custom spec types—see the Creating Specs tutorial.

Implementing Specs

Manual Implementation

# 1. Move spec to todo (if not already there)
/cmd:move-spec auth-system todo

# 2. Implement according to spec
# (code, test, etc.)

# 3. Move to done
/cmd:move-spec auth-system done

System Architecture

Behind the scenes, agentcmd maintains:

• Spec folders - Organized by status (backlog/todo/done)
• Index file - JSON registry tracking all specs for fast lookup
• Metadata - Complexity scores, timestamps, package info
• Tasks - Markdown checkboxes for progress tracking

See Spec System Reference for technical details on folder structure, metadata format, complexity scoring, and the index.json schema.

Next Steps