autospec

Spec-Driven Development Automation

Build features systematically with AI-powered specification workflows.

Stop AI slop. Autospec brings structure to AI coding: spec → plan → tasks → implement - all in one command.

Built with a multi-agent architecture and inspired by GitHub SpecKit, Autospec reimagines the specification workflow with YAML-first artifacts for programmatic access and validation. These principles ensure reliable, performant, and maintainable software that developers can trust for their critical development workflows.

📦 Installation

curl -fsSL https://raw.githubusercontent.com/ariel-frischer/autospec/main/install.sh | sh

🎯 Key Features

• Automated Workflow Orchestration — Runs stages in dependency order with automatic retry on failure
• YAML-First Artifacts — Machine-readable spec.yaml, plan.yaml, tasks.yaml for programmatic access
• Smart Validation — Validates artifacts exist and meet completeness criteria before proceeding
• Cross-Platform — Native binaries for Linux and macOS (Intel/Apple Silicon). Windows users: use WSL
• Flexible Stage Selection — Mix and match stages with intuitive flags (-spti, -a, etc.)
• Shell Completion — Tab completion for bash, zsh, and fish
• OS Notifications — Native desktop notifications with custom sound support
• History Tracking — View and filter command execution history with status, duration, and exit codes
• Auto-Commit — Automatic git commit creation with .gitignore management and conventional commit messages

✨ What Makes Autospec Different?

Originally inspired by GitHub SpecKit, Autospec is now a fully standalone tool with its own embedded commands and workflows.

| Feature | GitHub SpecKit | Autospec | |---------|---------------|----------| | Output Format | Markdown | YAML (machine-readable) | | Validation | Manual review | Automatic with retry logic | | Context Efficiency | Full prompt each time | Smart YAML injection + phase-isolated sessions | | Status Updates | Manual | Auto-updates spec.yaml & tasks.yaml | | Phase Orchestration | Manual | Automated with dependencies | | Session Isolation | Single session | Per-phase/task (80%+ cost savings) | | Implementation | Shell scripts | Go (type-safe, single binary) |

🚀 Quick Start

New to autospec? See the Quickstart Guide or run the interactive demo.

Prerequisites

• Claude Code or OpenCode
• Git

Initialize Your Project

1. Navigate to your git repo/project directory, then check dependencies:

   autospec doctor
   

2. Initialize Autospec (config, commands, and scripts):

   autospec init                    # Interactive agent selection
   autospec init ~/projects/myapp   # Initialize at specific path
   autospec init --ai opencode      # Configure specific agent
   autospec init --ai claude,opencode  # Configure multiple agents
   autospec init --project          # Project-level permissions (default: global)
   

   Permissions write to global config by default: ~/.claude/settings.json (Claude) or ~/.config/opencode/opencode.json (OpenCode). Use --project for project-level config.

3. Create project constitution (once per project, triggers Claude session):

   autospec constitution
   

🎮 Usage

Core Flow Commands

specify → plan → tasks → implement

The core workflow runs four stages in sequence, each creating a YAML artifact:

| Stage | Command | Creates | Description | |-------|---------|---------|-------------| | specify | autospec specify "desc" | specs/001-feature/spec.yaml | Feature specification with requirements | | plan | autospec plan | specs/001-feature/plan.yaml | Implementation design and architecture | | tasks | autospec tasks | specs/001-feature/tasks.yaml | Actionable task breakdown with dependencies | | implement | autospec implement | — | Executes tasks, updates status in tasks.yaml |

Branch creation: specify automatically creates and checks out a new feature branch (e.g., spec/001-user-auth) before generating the spec.

Recommended Workflow

1. Generate the specification
2. Review and edit specs/001-user-auth/spec.yaml as needed
3. Continue with plan → tasks → implement

autospec run -s "Add user authentication with OAuth"
autospec run -pti

This iterative approach lets you review and refine the spec before committing to implementation.

Flexible Stage Selection with run

# All core stages: specify → plan → tasks → implement
autospec run -a "Add user authentication with OAuth"

# Specify + plan
autospec run -sp "Add caching layer"

# Tasks + implement
autospec run -ti --spec 007-feature

# Specify + clarify
autospec run -sr "Add payments"

# All core + checklist
autospec run -a -l

# Tasks + checklist + analyze + implement
autospec run -tlzi

# All core with skip confirmations (-y)
autospec run -a -y "Feature description"

# Use a specific agent (claude or opencode)
autospec run -a --agent opencode "Add REST API endpoints"
autospec run -a --agent claude "Add unit tests"

Shortcut Commands

# All core stages: specify → plan → tasks → implement
autospec all "Add feature description"

# Planning only: specify → plan → tasks (no implementation)
autospec prep "Add feature description"

# Implementation only
autospec implement
autospec implement 003-feature "Focus on tests"

# Show artifacts and task progress
autospec status
autospec st
autospec st -v

Implementation Execution Modes

Control how implementation runs with different levels of context isolation:

# Phase mode (default): 1 session per phase - balanced cost/context
autospec implement
autospec implement --from-phase 3   # Resume from phase 3 onwards
autospec implement --phase 3        # Run only phase 3

# Task mode: 1 session per task - complex tasks, max isolation
autospec implement --tasks
autospec implement --from-task T005 # Resume from task T005 onwards
autospec implement --task T003      # Run only task T003

# Single mode: 1 session for all - small specs, simple tasks
autospec implement --single-session

Set the default mode via config: implement_method: phases | tasks | single-session

--tasks, --phases, and --single-session are mutually exclusive. Task-level execution respects dependency order and validates each task completes before proceeding.

Why isolate sessions? Context accumulation causes LLM performance degradation and higher API costs (each turn bills the entire context). Phase/task isolation can reduce costs by 80%+ on large specs. See FAQ for details.

Optional Stage Commands

# Create/update project principles
autospec constitution "Emphasize security"

# Refine spec with Q&A (interactive mode)
autospec clarify "Focus on edge cases"

# Generate validation checklist
autospec checklist "Include a11y checks"

# Cross-artifact consistency analysis (interactive mode)
autospec analyze "Verify API contracts"

Stage Flags Reference (run command)

| Flag | Stage | Description | |------|-------|-------------| | -s | specify | Generate feature specification | | -p | plan | Generate implementation plan | | -t | tasks | Generate task breakdown | | -i | implement | Execute implementation | | -a | all | All core stages (-spti) | | -n | constitution | Create/update project constitution | | -r | clarify | Refine spec with Q&A (interactive mode) | | -l | checklist | Generate validation checklist | | -z | analyze | Cross-artifact consistency check (interactive mode) |

Stages always execute in canonical order regardless of flag order: constitution → specify → clarify → plan → tasks → checklist → analyze → implement

Task Management

Claude automatically updates task status during implementation. Manual updates:

autospec update-task T001 InProgress
autospec update-task T001 Completed
autospec update-task T001 Blocked

History Tracking

View command execution history with filtering and status tracking. See docs/public/reference.md for details.

autospec history              # View all history
autospec history -n 10        # Last 10 entries
autospec history --status failed

📁 Output Structure

Autospec generates structured YAML artifacts:

specs/
└── 001-user-auth/
    ├── spec.yaml      # Feature specification
    ├── plan.yaml      # Implementation plan
    └── tasks.yaml     # Actionable task breakdown

Example tasks.yaml

feature: user-authentication
tasks:
  - id: T001
    title: Create user model
    status: Completed
    dependencies: []
  - id: T002
    title: Add login endpoint
    status: InProgress
    dependencies: [T001]
  - id: T003
    title: Write authentication tests
    status: Pending
    dependencies: [T002]

⚙️ Configura