Quickstart

Get up and running with autospec in 5 minutes.

Prerequisites

Before you begin, ensure you have:

  • Supported CLI agent: Claude Code, Codex CLI, or OpenCode installed and authenticated
  • Git: For version control and branch-based spec detection

Verify your agent is installed:

claude --version
# or
codex --version
# or
opencode --version

If you see command not found, visit the troubleshooting guide.

Cost Warning

Check your agent auth method before long runs. API keys can bill per-token and get expensive. Claude Pro/Max plans include usage at no extra cost for Claude Code; Codex auth is managed by the Codex CLI.

Run claude interactively, then /status to see your login method.

Step 1: Install autospec 

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

Option B: Download Binary

Visit the releases page and download for your platform:

Platform Binary
Linux autospec-linux-amd64
macOS Intel autospec-darwin-amd64
macOS Apple Silicon autospec-darwin-arm64 
chmod +x autospec-*
mkdir -p ~/.local/bin
mv autospec-* ~/.local/bin/autospec

Ensure ~/.local/bin is in your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell config if needed.

Option C: Build from Source 

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

Verify Installation 

autospec version

Expected output:

autospec version 1.0.0

Step 2: Check Dependencies

Run health checks to verify everything is set up:

autospec doctor

Expected output:

✓ CLI agent found
✓ Configuration loaded successfully
✓ Specs directory accessible: ./specs
✓ State directory accessible: ~/.autospec/state
✓ Configuration loaded successfully

All checks passed!

If any checks fail, see the troubleshooting guide.

Step 3: Initialize Configuration

Create the default configuration:

autospec init

This command:

  1. Creates ~/.config/autospec/config.yml with default settings
  2. Installs agent-native prompts for the selected agents
  3. Prompts for the default execution agent when multiple agents are selected
  4. Prompts to create project constitution (say “yes” - required for autospec to work)

Default config:

agent_preset: ""        # Empty falls back to claude; built-in: claude | codex | opencode
max_retries: 0
specs_dir: ./specs
state_dir: ~/.autospec/state
timeout: 2400           # 40 min default, 0 = no timeout
skip_permissions: true  # Autonomous mode for supported agents

See Configuration Reference for customization options.

Security Notice

On your first workflow run with autonomous mode enabled, you’ll see a one-time security notice:

┌───────────────────────────────────────────────────────────────────┐
│ Security Notice                                                   │
├───────────────────────────────────────────────────────────────────┤
│ Running in autonomous permissions mode                            │
│                                                                   │
│ This mode is RECOMMENDED for autospec workflows. Without it,     │
│ supported agents may require manual approval for edits and       │
│ commands, making automation impractical.                         │
│                                                                   │
│ ✓ Sandbox: enabled ✓                                              │
│   OS-level protection active.                                    │
└───────────────────────────────────────────────────────────────────┘

Caution: Autonomous mode gives the selected agent broad access without prompts. Claude sandboxing can limit access to your project; Codex yolo mode bypasses Codex approvals and sandboxing. Use isolated environments for high-risk work. See Configuration - Security for details.

Suppress this notice: autospec config set skip_permissions_notice_shown true or AUTOSPEC_SKIP_PERMISSIONS_NOTICE=1

autospec init installs agent-native prompts for interactive sessions. Claude Code receives project skills under .claude/skills/autospec.*/, preserving /autospec.specify-style invocation. Codex and OpenCode share skills under .agents/skills/autospec-*/. Codex and OpenCode workflow runs receive rendered prompt text directly through codex exec and opencode run; OpenCode init no longer creates .opencode/command files.

Invocation Purpose
/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
$autospec-specify "Add user auth" Codex/OpenCode shared skill syntax
$autospec-plan, $autospec-tasks, $autospec-implement Codex/OpenCode shared skill syntax

Use these in normal agent sessions when you prefer chat-based iteration over autospec’s automated mode.

Step 4: Create Project Constitution (if skipped)

If you said “yes” to “Create constitution?” during autospec init, skip this step - your constitution is already created.

If you skipped constitution creation during init, or need to regenerate it:

autospec constitution

This launches the configured agent to analyze your codebase and create .autospec/constitution.yaml containing your project’s:

  • Coding standards and conventions
  • Architectural principles
  • Testing requirements
  • Documentation standards

The constitution ensures the agent follows your project’s patterns during implementation.

Step 5: Create Your First Specification

Navigate to your project and create a specification:

cd your-project

# Generate spec.yaml only (also creates feature branch via git checkout)
autospec run -s "Add a health check endpoint at /health"

What happens:

Creates specs/add-health-check-endpoint/ with your specification:

File Contents
spec.yaml Requirements, acceptance criteria, success metrics

Expected output:

→ Executing specify stage...
✓ Specification created: specs/add-health-check-endpoint/spec.yaml
✓ Validation passed

To continue with planning and implementation, run additional stages:

# Continue with plan + tasks + implement
autospec run -pti

Step 6: Review Generated Artifacts

Check what was created:

ls specs/001-health-check/

Output:

spec.yaml  plan.yaml  tasks.yaml
File Purpose
spec.yaml Requirements, acceptance criteria, success metrics
plan.yaml Technical architecture, design decisions, file structure
tasks.yaml Ordered tasks with dependencies and status tracking

Check progress with:

autospec st

Alternative Workflows

Review and refine between stages:

# Step 1: Generate spec only
autospec run -s "Add rate limiting to API endpoints"

# Step 2: Review and edit specs/001-rate-limiting/spec.yaml

# Step 3: Continue with remaining stages
autospec run -pti

Planning Only (No Implementation)

Generate artifacts for review before implementing:

autospec prep "Add caching layer for database queries"

# Review the generated artifacts...

# Then implement when ready:
autospec implement

Stage Flags Reference

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)
-r clarify Refine spec with Q&A
-l checklist Generate validation checklist
-z analyze Cross-artifact consistency check
-y — Skip confirmation prompts

Common combinations:

# All core stages
autospec run -a "feature"

# Planning only (specify + plan + tasks)
autospec run -spt "feature"   # or: autospec prep "feature"

# Specify + clarify (refine spec with questions)
autospec run -sr "feature"

# All stages + checklist + analyze
autospec run -alz "feature"

Monitoring Progress 

# Quick status check
autospec st

# Verbose status with task details
autospec st -v

# View command history
autospec history
autospec history -n 10

Implementation Modes 

# Default: One session per phase
autospec implement

# Per-task isolation (recommended for complex features)
autospec implement --tasks

# Single session (for small/simple specs)
autospec implement --single-session

# Resume from specific point
autospec implement --from-phase 3
autospec implement --from-task T005
autospec implement --task T003  # Single task only

Example Feature Descriptions 

# API Features
autospec run -a "Add a health check endpoint at /health that returns JSON status"
autospec run -a "Add rate limiting middleware with configurable limits per route"
autospec run -a "Implement pagination for all list endpoints"

# Authentication
autospec run -a "Add JWT authentication with refresh token support"
autospec run -a "Add OAuth2 login with Google and GitHub providers"

# Database
autospec run -a "Add database connection pooling with configurable pool size"
autospec run -a "Implement soft delete for user records with restore functionality"

# Testing
autospec run -a "Add integration tests for the payment processing module"

# DevOps
autospec run -a "Add Dockerfile with multi-stage build for production"
autospec run -a "Create GitHub Actions CI pipeline with test and lint stages"

Troubleshooting

“agent: command not found”

The selected agent CLI is not installed or not in PATH.

Solution: Install Claude Code, Codex CLI, or OpenCode, then verify with claude --version, codex --version, or opencode --version.

“autospec: command not found”

autospec binary is not in PATH.

Solution: Run sudo make install or add ~/.local/bin to your PATH.

“Validation failed: spec file not found”

Workflow stage failed to create expected output file.

Solution: Check error messages. If retry limit exhausted, reset retry state:

rm ~/.autospec/state/retry.json

“Spec not detected”

Auto-detection failed to find current feature.

Solution: Ensure you’re on a feature branch with format NNN-feature-name (e.g., 001-health-check), or explicitly specify the spec:

autospec implement 001-health-check

For more solutions, see the full troubleshooting guide.

Next Steps

Getting Help

Back to top

autospec - AI-powered software specification and implementation workflows