autospec

autospec copied to clipboard

▄▀█ █ █ ▀█▀ █▀█ █▀ █▀█ █▀▀ █▀▀
█▀█ █▄█  █  █▄█ ▄█ █▀▀ ██▄ █▄▄

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.

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

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)

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]

⚙️ Configuration

Config Files (YAML format)

• User config: ~/.config/autospec/config.yml (XDG compliant)
• Project config: .autospec/config.yml

Priority: Environment vars > Project config > User config > Defaults

All Settings

# .autospec/config.yml

# Agent configuration
agent_preset: claude                  # Built-in: claude | opencode
skip_permissions: false               # Add --dangerously-skip-permissions flag (Claude only)
custom_agent_cmd: ""                  # Custom command template with {{PROMPT}} placeholder
# custom_agent:                       # Structured agent config (alternative to custom_agent_cmd)
#   command: claude
#   args:
#     - -p
#     - --dangerously-skip-permissions
#     - --verbose
#     - --output-format
#     - stream-json
#     - "{{PROMPT}}"

# Workflow settings
max_retries: 0                        # Max retry attempts per stage (0-10)
specs_dir: ./specs                    # Directory for feature specs
state_dir: ~/.autospec/state          # Directory for state files
skip_preflight: false                 # Skip preflight checks
timeout: 2400                         # Timeout in seconds (40 min default, 0 = no timeout)
skip_confirmations: false             # Skip confirmation prompts
implement_method: phases              # Default: phases | tasks | single-session
auto_commit: false                    # Auto-create git commit after workflow (default: false)
enable_risk_assessment: false         # Enable risk section in plan.yaml (opt-in)

# Output formatting (Claude agent only)
cclean:
  style: default                      # Output style: default | minimal | detailed
  verbose: false                      # Show verbose output
  linenumbers: false                  # Show line numbers in output

# Notifications (all platforms)
notifications:
  enabled: false                      # Enable notifications (opt-in)
  type: both                          # sound | visual | both
  sound_file: ""                      # Custom sound file (empty = system default)
  on_command_complete: true           # Notify when command finishes
  on_stage_complete: false            # Notify on each stage
  on_error: true                      # Notify on failures
  on_long_running: false              # Notify after threshold
  long_running_threshold: 2m          # Duration threshold

Custom Agent Configuration

For full control over agent invocation, use custom_agent:

custom_agent:
  command: claude
  args:
    - -p
    - --model
    - claude-sonnet-4-5-20250929
    - "{{PROMPT}}"

Or as a single command string:

custom_agent_cmd: "claude -p --model claude-sonnet-4-5-20250929 {{PROMPT}}"

See Agent Configuration for complete details including OpenCode setup and environment variables.

Commands

autospec init
autospec init --project
autospec config show
autospec config show --json
autospec config sync              # Add new options, remove deprecated ones
autospec config migrate
autospec config migrate --dry-run

🐚 Shell Completion

The easiest way to set up shell completions (auto-detects your shell):

autospec completion install

Or install for a specific shell:

autospec completion install bash
autospec completion install zsh
autospec completion install fish

See docs/public/SHELL-COMPLETION.md for detailed setup and manual instructions.

🔧 Exit Codes

Uses standardized exit codes (0-5) for CI/CD integration. See docs/public/reference.md for full details.

autospec run -a "feature" && echo "Success" || echo "Failed: $?"

🔍 Troubleshooting

autospec doctor
autospec --debug run -a "feature"
autospec config show

See docs/public/troubleshooting.md for common issues and solutions.

📝 Slash Commands for Interactive Sessions

autospec init installs slash commands to .claude/commands/autospec.*.md for use in normal Claude Code sessions:

/autospec.specify    # Generate spec.yaml interactively
/autospec.plan       # Generate plan.yaml
/autospec.tasks      # Generate tasks.yaml
/autospec.implement  # Execute implementation
/autospec.clarify    # Refine specifications
/autospec.analyze    # Cross-artifact analysis
/autospec.checklist  # Generate quality checklist
/autospec.constitution  # Create project constitution

Use these when you prefer chat-based iteration over autospec's automated (-p) mode.

📚 Documentation

Full documentation: ariel-frischer.github.io/autospec

📥 Build from Source

Requires Go 1.21+

git clone https://github.com/ariel-frischer/autospec.git
cd autospec
make install

🤝 Contributing

Contributions welcome! See CONTRIBUTORS.md for development guidelines.

📄 License

MIT License — see LICENSE for details.

Documentation: autospec --help

Issues: github.com/ariel-frischer/autospec/issues

⭐ Star us on GitHub if you find Autospec useful!