Claude Code Commands

A structured command system for AI-assisted Spec-Driven Development, enabling rapid feature delivery through systematic specifications, dependency-driven task execution via Beads, and brownfield/greenfield support.

Commands Overview

🎯 Product Commands (/commands/product/)

• /product:init - Initialize project with product documentation
• /product:roadmap - Define and prioritize features
• /product:progress - Track overall product development

📋 Spec Commands (/commands/spec/)

• /spec:create <feature> - Create unified spec (greenfield or brownfield with code detection)
• /spec:work [feature] - Implement next ready task using Beads and layer boundary testing
• /spec:status [feature] - Track feature progress via Beads

🔄 Change Commands (/commands/change/)

• /change:propose <feature> <change> - Propose changes to existing features with delta tracking
• /change:complete <feature> <change> - Merge delta into spec and close Beads epic

🛠️ Code Commands (/commands/code/)

• /code:review [branch] - Comprehensive code review with architecture compliance
• /code:commit - Create smart git commits with conventional format
• /code:validate - Run build, lint, and test pipeline (multi-language)

Quick Start

Greenfield (New Feature)

# 1. Initialize project
/product:init my-project

# 2. Define features
/product:roadmap

# 3. Create & implement feature (unified workflow)
/spec:create authentication  # Detects code, creates unified spec + Beads tasks
/spec:work authentication    # Implements next ready task
/spec:work authentication    # Continue until complete
/spec:status authentication  # Check progress

# 4. Quality assurance
/code:validate
/code:review
/code:commit

Brownfield (Existing Code)

# 1. Create spec from existing code
/spec:create user-profile    # Auto-detects existing code, documents it

# 2. Propose a change
/change:propose user-profile add-avatar  # Creates delta.md with ADDED/MODIFIED/REMOVED

# 3. Implement the change
/spec:work user-profile      # Works on change tasks from Beads

# 4. Complete the change
/change:complete user-profile add-avatar  # Merges delta into spec.md

# 5. Quality assurance
/code:validate
/code:commit

Architecture

Spec-Driven Development

• Lightweight docs over heavy planning
• Dependency-driven task ordering via Beads
• AI-assisted implementation
• Prevention over debugging
• Greenfield & Brownfield support with code detection

Technical Standards

• Layered Architecture: Router → Service → Repository → Entity
• Layer Boundary Testing: Test at component boundaries, not every method
• Stub→Test→Fix Pattern: Create stubs → Write tests → Implement
• Contextual Layer Detection: Only create tasks for layers actually needed
• Agent Specialization: Focused roles for complex tasks

File Organization

docs/
├── product/           # Product vision & roadmap
├── spec/{feature}/    # Unified specs (requirements + design)
├── changes/           # Change proposals and deltas
│   └── {feature}/
│       └── {change}/
│           ├── proposal.md
│           └── delta.md
└── standards/         # Technical patterns & practices

commands/
├── product/          # Product management commands
├── spec/            # Feature development commands (unified workflow)
├── change/          # Change management commands
├── code/            # Code quality and git commands
└── README.md        # Command documentation

agents/
├── analyst.md       # Requirements gathering (code-aware)
├── architect.md     # Technical design with Beads task generation
├── coder.md         # Layer boundary testing implementation
├── scaffold.md      # File scaffolding
├── context.md       # Context retrieval
└── product.md       # Progress tracking via Beads

.beads/              # Beads task tracking (git-backed)
└── beads.jsonl      # Task and dependency data

Key Features

• Beads Integration: Dependency-aware task tracking with bd CLI
• Code Detection: Auto-detects existing code in greenfield/brownfield modes
• Unified Specs: Single spec.md file with Requirements + Technical Design + Implementation Notes
• Change Management: Delta tracking with ADDED/MODIFIED/REMOVED structure
• Layer Boundary Testing: Test at component interfaces, not every method
• Contextual Tasks: Only create Beads tasks for layers actually needed
• Multi-Language: Auto-detects Node.js, Python, Rust, Go, Make projects
• Architecture Compliance: Automated pattern validation
• Smart Commits: Context-aware git messages

Beads Integration

This system uses Beads for dependency-aware task management:

# Install Beads
npm install -g @beads/bd

# Initialize in project
bd init

# Common operations (handled by commands)
bd ready                  # Find next ready task
bd create "task" -l feat  # Create task with labels
bd dep add <task> <blocks> --type blocks  # Add dependency
bd close <task>           # Mark complete

Beads provides:

• Git-backed task storage (.beads/beads.jsonl)
• Dependency tracking (technical blocking relationships)
• Ready task detection (find unblocked work)
• JSON output for agent consumption

Best Practices

1. Use unified workflow: /spec:create → /spec:work → /spec:status
2. Leverage Beads: Let dependency tracking guide implementation order
3. Detect existing code: /spec:create works for both greenfield and brownfield
4. Use change workflow: /change:propose → /spec:work → /change:complete for modifications
5. Test at boundaries: Focus on layer interfaces, not internal methods
6. Validate frequently: Use /code:validate before commits
7. Track progress: Use /spec:status to monitor Beads tasks

This system transforms AI from requiring constant prompting into a team member that understands your standards, business context, implementation approach, and can handle both new features and changes to existing code.