Auto-Claude Spec Creation

Master the spec creation pipeline for autonomous builds.

Overview

Specs are the foundation of Auto-Claude builds. They define:

What needs to be built
Acceptance criteria
Context from existing codebase
Implementation plan

Spec Pipeline Phases

Dynamic Phase Selection

Auto-Claude automatically selects phases based on task complexity:

Complexity	Phases	Description
SIMPLE	3	Discovery → Quick Spec → Validate
STANDARD	6-7	Discovery → Requirements → [Research] → Context → Spec → Plan → Validate
COMPLEX	8	Full pipeline with Research and Self-Critique phases

Phase Breakdown

1. Discovery Phase

Gathers user requirements interactively
Asks clarifying questions
Identifies scope and constraints

2. Requirements Phase

Structures requirements into JSON format
Defines acceptance criteria
Lists technical constraints

3. Research Phase (Standard/Complex)

Validates external integrations
Checks API compatibility
Researches best practices

4. Context Phase

Analyzes existing codebase
Identifies relevant files
Maps dependencies

5. Spec Writing Phase

Creates detailed spec.md
Documents technical approach
Lists affected components

6. Planning Phase

Creates implementation plan
Breaks work into subtasks
Defines phase dependencies

7. Critique Phase (Complex only)

Self-review using ultrathink
Identifies potential issues
Suggests improvements

8. Validation Phase

Validates all artifacts
Checks completeness
Prepares for build

Creating Specs

Interactive Mode (Recommended)

cd apps/backend
python spec_runner.py --interactive

The system will:

Ask about your feature/task
Clarify requirements
Analyze your codebase
Generate complete spec

From Task Description

# Quick spec creation
python spec_runner.py --task "Add dark mode toggle to settings page"

# With forced complexity
python spec_runner.py --task "Add payment integration" --complexity complex

Continue Interrupted Spec

# Resume from where it stopped
python spec_runner.py --continue 001-feature-name

Spec Structure

Directory Layout

.auto-claude/specs/001-feature-name/
├── spec.md                    # Main specification document
├── requirements.json          # Structured requirements
├── context.json               # Codebase context
├── implementation_plan.json   # Subtask-based plan
├── discovery.json             # Initial discovery data
├── research.json              # Research findings (if applicable)
└── validation_report.json     # Validation results

spec.md Format

# Feature: [Feature Name]

## Overview
[Description of what this feature does]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Approach
[How the feature will be implemented]

## Affected Components
- Component 1: [changes]
- Component 2: [changes]

## Dependencies
- [External dependencies if any]

## Testing Strategy
[How to verify the feature works]

requirements.json Format

{
  "title": "Feature Title",
  "description": "Detailed description",
  "acceptance_criteria": [
    "User can do X",
    "System responds with Y"
  ],
  "constraints": [
    "Must work on mobile",
    "Must be accessible"
  ],
  "priority": "high",
  "complexity": "standard"
}

implementation_plan.json Format

{
  "spec_id": "001-feature-name",
  "subtasks": [
    {
      "id": 1,
      "title": "Create data model",
      "description": "Add User schema to database",
      "status": "pending",
      "dependencies": [],
      "files": ["src/models/user.ts"]
    },
    {
      "id": 2,
      "title": "Implement API endpoint",
      "description": "Create /api/users route",
      "status": "pending",
      "dependencies": [1],
      "files": ["src/routes/users.ts"]
    }
  ],
  "total_subtasks": 2,
  "completed": 0
}

Best Practices

Writing Good Requirements

Good:

"Add user authentication using Google OAuth with:
- Login button in header
- Protected routes for /dashboard/*
- User profile stored in database
- Session management with cookies"

Bad:

"Add login feature"

Complexity Selection

Choose	When
Simple	1-2 files, UI tweaks, text changes, simple bug fixes
Standard	3-10 files, new features, component additions
Complex	10+ files, external integrations, architectural changes

Spec Review Tips

Before running build:

Check acceptance criteria - Are they testable?
Review affected components - Are all files identified?
Validate dependencies - Are external services available?
Confirm scope - Is the scope appropriate?

Managing Specs

List All Specs

python run.py --list

Output:

Specs:
  001-user-auth [COMPLETE] - User authentication
  002-dark-mode [BUILDING] - Dark mode toggle
  003-search [PENDING] - Search functionality

View Spec Status

# Check spec details
cat .auto-claude/specs/001-feature/spec.md

# Check implementation progress
cat .auto-claude/specs/001-feature/implementation_plan.json

Modify Spec

Edit the spec.md file directly:

# Edit spec
nano .auto-claude/specs/001-feature/spec.md

# Re-validate
python validate_spec.py --spec-dir .auto-claude/specs/001-feature --checkpoint all

Delete Spec

# Remove spec directory
rm -rf .auto-claude/specs/001-feature

# Or discard via CLI (includes worktree cleanup)
python run.py --spec 001 --discard

Advanced Usage

Custom Prompts

Modify prompts in apps/backend/prompts/:

spec_gatherer.md - Discovery phase
spec_researcher.md - Research phase
spec_writer.md - Spec writing
spec_critic.md - Self-critique
spec_quick.md - Simple spec creation

Batch Spec Creation

# Create specs from a file
while IFS= read -r task; do
  python spec_runner.py --task "$task" --complexity standard
done < tasks.txt

Spec Templates

Create custom templates in apps/backend/templates/ (if needed):

mkdir -p templates
cat > templates/api-feature.md << 'EOF'
# API Feature: {{name}}

## Endpoints
- GET /api/{{resource}}
- POST /api/{{resource}}

## Data Model
[Define schema]

## Authentication
[Required auth level]
EOF

Troubleshooting

Spec Creation Fails

# Enable debug mode
DEBUG=true python spec_runner.py --interactive

# Check logs
cat .auto-claude/logs/spec_runner.log

Invalid Requirements

# Validate spec structure
python validate_spec.py --spec-dir .auto-claude/specs/001-feature --checkpoint requirements

Context Discovery Issues

# Re-run context analysis
python spec_runner.py --continue 001-feature

# Or manually trigger context phase
# (Edit implementation_plan.json to reset context phase)

Related Skills

auto-claude-cli: CLI command reference
auto-claude-build: Running builds
auto-claude-workspace: Workspace management

auto-claude-spec