auto-claude-spec

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

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

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

Interactive Mode (Recommended)

```bash

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

```bash

# 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

```bash

# Resume from where it stopped

python spec_runner.py --continue 001-feature-name

```

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

```markdown

# Feature: [Feature Name]

[Description of what this feature does]

• [ ] Criterion 1
• [ ] Criterion 2
• [ ] Criterion 3

[How the feature will be implemented]

• Component 1: [changes]
• Component 2: [changes]

• [External dependencies if any]

[How to verify the feature works]

```

requirements.json Format

```json

{

"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

```json

{

"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

}

```

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?

List All Specs

```bash

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

```bash

# 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:

```bash

# 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

```bash

# Remove spec directory

rm -rf .auto-claude/specs/001-feature

# Or discard via CLI (includes worktree cleanup)

python run.py --spec 001 --discard

```

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

```bash

# 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):

```bash

mkdir -p templates

cat > templates/api-feature.md << 'EOF'

# API Feature: {{name}}

• GET /api/{{resource}}
• POST /api/{{resource}}

[Define schema]

[Required auth level]

EOF

```

Spec Creation Fails

```bash

# Enable debug mode

DEBUG=true python spec_runner.py --interactive

# Check logs

cat .auto-claude/logs/spec_runner.log

```

Invalid Requirements

```bash

# Validate spec structure

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

```

Context Discovery Issues

```bash

# Re-run context analysis

python spec_runner.py --continue 001-feature

# Or manually trigger context phase

# (Edit implementation_plan.json to reset context phase)

```

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