adaptationio/auto-claude-spec

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:

1. Ask about your feature/task
2. Clarify requirements
3. Analyze your codebase
4. 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:

1. Check acceptance criteria - Are they testable?
2. Review affected components - Are all files identified?
3. Validate dependencies - Are external services available?
4. 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