Skip to content
/
Tier B A6 Multi-agent orchestrator

Autospec

autospec · ariel-frischer/autospec · ★ 130 · last commit 2026-05-23

Go CLI that orchestrates spec → plan → tasks → implement in fresh isolated agent sessions with YAML artifacts and programmatic validation.

Best whenContext accumulation is the primary cause of LLM quality degradation; session isolation per stage/task (not model upgrading) is the correct remedy.
Skip ifAccumulating context across all implementation stages, Using Markdown when YAML enables programmatic validation
vs seeds
spec-kit(Archetype 2 — mirror commands+skills with CLI) but with three architectural deltas: YAML instead of Markdown artifacts …
Primitive shape 9 total
Skills 9
00

Summary

Autospec — Summary

Autospec is a Go CLI that automates spec-driven development by orchestrating four sequential stages — specify → plan → tasks → implement — each producing a YAML artifact. Inspired by GitHub SpecKit but distinguishing itself through YAML-first machine-readable artifacts and programmatic validation, it installs a single binary (autospec) that manages feature branches, runs agent sessions with context isolation, and validates artifact completeness before proceeding.

The binary supports Claude Code, Codex CLI, and OpenCode as agents and routes different stages to optionally different agents. Context isolation per phase or per task is its key token-efficiency mechanism: each stage runs in a fresh bounded session, reducing LLM context accumulation and cutting costs by up to 80%.

Auto-commit with conventional commit messages, OS desktop notifications, history tracking, and shell completion make it a polished developer tool rather than a prompt snippet. It ships 9 named agent skills installed into .agents/skills/ and corresponding Claude Code skills in .claude/skills/.

Closest seed match is spec-kit (Archetype 2 — mirror commands+skills with CLI orchestration), but autospec diverges by using YAML artifacts instead of Markdown, running a Go orchestration engine instead of PowerShell/bash helpers, and enforcing programmatic artifact validation rather than agent-driven checklist review.

01

Overview

Autospec — Overview

Origin

Created by Ariel Frischer (GitHub: ariel-frischer). Submitted to the awesome-claude-code repository as issue #391 with the tagline "CLI for Spec Driven Development." Published 2025, written in Go, with semantic versioning and a goreleaser CI pipeline.

Philosophy

The core problem Autospec solves: LLM context accumulation during long implementation sessions degrades output quality and inflates costs. The remedy is stage isolation — each workflow stage runs in its own bounded session so context is always fresh.

The secondary philosophy is YAML-first artifacts: where GitHub SpecKit (the acknowledged inspiration) produces Markdown, Autospec produces spec.yaml, plan.yaml, tasks.yaml. Machine-readable formats enable programmatic validation before each stage proceeds.

Manifesto-style quotes

From the README:

"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."

On session isolation:

"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."

From the issue submission (awesome-claude-code #391):

"Best for: Features with 3+ design decisions, 3-10 files — not trivial fixes, not multi-week projects."

Comparison with SpecKit (README)

Feature GitHub SpecKit Autospec
Output Format Markdown YAML (machine-readable)
Workflow UX Repetitive, non-composable One-command end-to-end
Validation Checklist/agent-driven Programmatic validation with retry
Token Efficiency Context accumulates Fresh sessions per phase/task
Phase Orchestration Agent-driven commands CLI-orchestrated
Workflow Engine Prompt files + shell helpers Typed Go orchestration
02

Architecture

Autospec — Architecture

Distribution

  • Type: cli-tool (Go binary)
  • Install: Shell script downloads a single Go binary to ~/.local/bin/autospec
  • Install complexity: one-liner

Install commands

curl -fsSL https://raw.githubusercontent.com/ariel-frischer/autospec/main/install.sh | sh
# or via goreleaser releases (Linux/macOS Intel/Apple Silicon)

Windows: WSL only (no native Windows binary).

Directory tree

autospec/
├── cmd/autospec/main.go        ← CLI entry point
├── internal/                   ← Go packages (orchestration, validation, artifacts)
├── .autospec/
│   └── constitution.yaml       ← Project-level coding standards (once per project)
├── .agents/
│   └── skills/                 ← Agent skills (9 named skills, shared across agents)
│       ├── autospec-specify/SKILL.md
│       ├── autospec-plan/SKILL.md
│       ├── autospec-tasks/SKILL.md
│       ├── autospec-implement/SKILL.md
│       ├── autospec-constitution/SKILL.md
│       ├── autospec-clarify/SKILL.md
│       ├── autospec-analyze/SKILL.md
│       ├── autospec-checklist/SKILL.md
│       └── autospec-worktree-setup/SKILL.md
├── specs/
│   └── NNN-feature-name/       ← Per-feature directory (auto-created)
│       ├── spec.yaml
│       ├── plan.yaml
│       └── tasks.yaml
├── CLAUDE.md                   ← Guidance for Claude Code in this repo
├── AGENTS.md                   ← Shared agent guidance
├── docs/
│   ├── public/                 ← User-facing docs (quickstart, reference, FAQ)
│   └── internal/               ← Architecture, internals, Go best practices
├── site/                       ← Astro documentation site source
├── install.sh
├── go.mod / go.sum
├── Makefile
└── .goreleaser.yml

Required runtime

  • No runtime required for end users — self-contained Go binary
  • Development: Go 1.25+, make, golangci-lint
  • Agents: Claude Code, Codex CLI, or OpenCode (at least one required)
  • Git (for branch creation and commit automation)

Target AI tools

  • Claude Code (primary, most tested)
  • Codex CLI
  • OpenCode

Config files

File Purpose
.autospec/constitution.yaml Project coding standards (generated once per project)
~/.config/autospec/config.yml Global config (implement_method default, agent preference)
.autospec/config.yml Project-level config override
03

Components

Autospec — Components

CLI Binary: autospec

The primary interface. All commands are subcommands of autospec.

Subcommand Purpose
init Initialize project (config + agent skills + constitution prompt)
doctor Check dependencies (agent, git, binary version)
specify / run -s Stage 1: generate spec.yaml from description
plan / run -p Stage 2: generate plan.yaml from spec.yaml
tasks / run -t Stage 3: generate tasks.yaml from plan.yaml
implement / run -i Stage 4: execute tasks, update status in tasks.yaml
constitution Create/update project constitution (coding standards)
clarify Optional clarification stage before specify
analyze Optional codebase analysis before specify
checklist Generate implementation checklist
new-feature Create feature branch + directory (internal, called by specify)
all Shortcut: all four core stages
prep Shortcut: specify → plan → tasks (no implement)
run Composable: select stages with flags (-s, -p, -t, -i, -a, -r, -l, -z)
st / status Show spec and task progress
history View command execution history with status and duration
sync Sync/regenerate agent skills after upgrade
completion Generate shell completion (bash, zsh, fish)
version Show binary version

Agent Skills (9)

Installed into .agents/skills/ (shared across agents) and .claude/skills/ (Claude Code):

Skill Purpose
autospec-specify Generate spec.yaml from natural language description
autospec-plan Generate plan.yaml from spec.yaml
autospec-tasks Generate tasks.yaml from plan.yaml
autospec-implement Execute tasks from tasks.yaml
autospec-constitution Create/update project constitution (coding standards)
autospec-clarify Ask clarifying questions before specification
autospec-analyze Analyze codebase before specification
autospec-checklist Generate and validate implementation checklist
autospec-worktree-setup Set up git worktree for parallel execution

Hooks

None in .claude/settings.json. Autospec does not use Claude Code lifecycle hooks.

Scripts

Script Purpose
install.sh Download and install binary to ~/.local/bin/
scripts/quickstart-demo.sh Interactive demo script

Templates

Artifact Format
spec.yaml YAML schema (user_stories, requirements, success_criteria, risks, etc.)
plan.yaml YAML schema (architecture, components, risks, implementation approach)
tasks.yaml YAML schema (phases, tasks with dependencies, priority, status tracking)
.autospec/constitution.yaml YAML (coding standards, project conventions)

MCP Servers

None.

05

Prompts

Autospec — Prompts

Excerpt 1 — autospec-specify SKILL.md (verbatim excerpt)

---
name: autospec-specify
description: "Generate YAML feature specification from natural language description."
---

# autospec-specify

...

Given that feature description, do this:

1. **Generate a concise short name** (2-4 words) for the branch:
   - Analyze the feature description and extract the most meaningful keywords
   - Create a 2-4 word short name that captures the essence of the feature
   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)

2. **Create feature branch and directory**: Run the Go command with your generated short-name:
   ```bash
   autospec new-feature --json --short-name "<short-name>" "$ARGUMENTS"

Parse the JSON output for: BRANCH_NAME, SPEC_FILE, FEATURE_NUM, AUTOSPEC_VERSION, CREATED_DATE

  1. Generate spec.yaml: Create the YAML specification file with this exact structure. Schema reference: Run autospec artifact spec --schema to see the full schema if unsure.

**Prompting technique**: CLI-anchored prompt chaining. The skill receives the feature description, runs a Go binary to get structured JSON (branch name, feature number), then uses that JSON to populate the YAML artifact. The LLM serves as a semantic extraction engine; the CLI handles deterministic operations.

## Excerpt 2 — autospec CLAUDE.md (verbatim excerpt)

```markdown
## Core Workflow

### Stage Dependencies (MUST follow this order)

constitution → specify → plan → tasks → implement
     ↓            ↓        ↓       ↓
constitution.yaml spec.yaml plan.yaml tasks.yaml

| Stage | Requires | Produces |
|-------|----------|----------|
| constitution | — | .autospec/constitution.yaml |
| specify | constitution | specs/NNN-feature/spec.yaml |
| plan | spec.yaml | plan.yaml |
| tasks | plan.yaml | tasks.yaml |
| implement | tasks.yaml | code changes |

**Constitution is REQUIRED before any workflow stage.**

Prompting technique: Strict dependency enforcement through MUST language. The CLAUDE.md for the autospec repo itself enforces stage ordering as an Iron Law, preventing Claude from attempting any stage without the prerequisite artifact.

Excerpt 3 — Post-change automation instruction (CLAUDE.md)

## Post-Change Polish (REQUIRED)

After significant code changes, automatically invoke the repo-local `polish` skill before final handoff. Use it to update changelog/docs and run the required validation targets. Do not wait for an explicit `/polish` request unless the change is trivial or docs-only.

Prompting technique: Automatic post-action behavior. Claude is instructed to proactively invoke the polish skill without being asked, making quality maintenance a default behavior rather than a manual step.

09

Uniqueness

Autospec — Uniqueness

differs_from_seeds

Closest to spec-kit (Archetype 2 — mirror commands+skills with CLI orchestration), but with three substantial architectural deltas. First: artifact format is YAML instead of Markdown, enabling programmatic validation before each stage proceeds — spec-kit relies on agent-driven checklist review, not schema validation. Second: the orchestration engine is a typed Go binary rather than PowerShell/bash helpers, giving autospec retry logic, dependency ordering, and structured JSON output from stage execution. Third: context isolation is a first-class design principle — each stage runs in a fresh bounded agent session (reducing costs ~80%), whereas spec-kit accumulates context across the workflow. Autospec also explicitly acknowledges SpecKit as its inspiration while positioning itself as a reimagination rather than a copy. Compared to spec-driver (Archetype 1 — skills-only, CLI for humans and agents), autospec is CLI-orchestrated rather than agent-driven: the binary manages stage sequencing rather than relying on the agent to invoke skill chains.

Positioning

The most feature-complete Go CLI in this batch. Targets developers who want one-command end-to-end runs with minimal setup. Best fit: individual developers or small teams building features with 3+ design decisions and 3-10 files. The YAML-first artifact format enables downstream tooling (CI validation, linting, custom reporting).

Observable failure modes

  1. Go binary single-platform limitation: No native Windows binary — WSL required, which adds friction for Windows-only teams.
  2. YAML friction for non-technical stakeholders: YAML artifacts are machine-readable but less immediately editable than Markdown for product managers or designers reviewing requirements.
  3. Agent dependency: Requires at least one of Claude Code, Codex CLI, or OpenCode to be installed and authenticated — adding an external dependency on top of the binary itself.
  4. Constitution required: Every new project must run autospec constitution before any workflow stage — forgetting this blocks all subsequent commands.
  5. Sequential stage lock: Stages strictly depend on prior artifacts; if a stage fails validation, the entire workflow is blocked until the prior artifact is fixed.
  6. Single feature branch: Unlike worktree-per-feature patterns (superpowers, spec-driver), autospec uses one branch per feature — no parallel feature development in isolation.
04

Workflow

Autospec — Workflow

Core phases

constitution (once per project) → specify → plan → tasks → implement
Phase Command Artifact Validation
0. Constitution autospec constitution .autospec/constitution.yaml Programmatic schema check
1. Specify autospec specify "desc" specs/NNN-feature/spec.yaml Completeness criteria check
2. Plan autospec plan specs/NNN-feature/plan.yaml Completeness criteria check
3. Tasks autospec tasks specs/NNN-feature/tasks.yaml Completeness criteria check
4. Implement autospec implement code changes + tasks.yaml status Task completion status

Specify stage detail

  • specify auto-creates a feature branch (e.g., spec/008-user-auth)
  • Generates spec.yaml with: feature metadata, user stories (id, priority, acceptance scenarios), functional requirements (FR-xxx), non-functional requirements (NFR-xxx), success criteria, risks
  • The branch is checked out before the agent session begins

Implement execution modes

Three modes (mutually exclusive):

Mode Flag Behavior
Phase mode (default) 1 agent session per phase — balanced cost/context
Task mode --tasks 1 agent session per task — max isolation
Single mode --single-session 1 session for all tasks

Resumption flags:

  • --from-phase N — resume from phase N
  • --from-task T005 — resume from task T005
  • --phase N / --task T003 — run only that phase/task

Approval gates

Gate Type When
Spec review file-review After specify — user edits spec.yaml before continuing
Artifact validation programmatic Before each stage — CLI validates prior artifact's completeness
Stage confirmation yes-no By default, CLI prompts before each stage (skip with -y)
Checklist gate file-review Optional: autospec checklist before implement

Shortcut commands

autospec all "description"   # specify → plan → tasks → implement
autospec prep "description"  # specify → plan → tasks (no implement)
autospec run -a "description" # same as all
autospec run -sp "description" # specify + plan only
autospec run -ti              # tasks + implement only

Git automation

  • specify creates feature branch (spec/NNN-name)
  • implement writes conventional-commit messages and can auto-commit
  • PR creation: referenced in README but not auto-invoked
06

Memory Context

Autospec — Memory & Context

State storage

File-based YAML artifacts. Each feature's state lives in its own directory:

specs/NNN-feature/
├── spec.yaml      ← Stage 1 output (immutable after approval)
├── plan.yaml      ← Stage 2 output
└── tasks.yaml     ← Stage 3 output + running status (updated during implement)

Global state:

.autospec/
└── constitution.yaml  ← Project coding standards (written once, read every session)

User-global config:

~/.config/autospec/config.yml  ← Default agent, implement_method, notification settings

Persistence

  • Project level: specs/ directory — per-feature, persists across sessions
  • Global: ~/.config/autospec/config.yml — user preferences

Context isolation strategy

Autospec's key memory architecture decision: isolation by session boundary. Rather than accumulating context across all implementation work, each phase or task runs in a fresh agent session. The prior stage's YAML artifact is the only context injected into the new session.

This is documented as reducing costs by "80%+" because each turn bills only that session's context, not the full accumulated history.

Cross-session handoff

tasks.yaml carries status fields per task (pending, in-progress, completed, failed). The --from-phase and --from-task flags allow resumption from the last incomplete step. The autospec st command shows current progress.

Compaction handling

Not applicable — context compaction is avoided by design through session isolation. There is no long-running session to compact.

History tracking

autospec history          # show all past runs
autospec history -v       # verbose (show exit codes, durations)

The history file records command, status, duration, and exit code for every autospec invocation.

Audit log

Yes — history file provides a lightweight audit trail of all autospec command executions. Format is structured (not JSONL — CLI table output).

07

Orchestration

Autospec — Orchestration

Multi-agent support

Yes, in a limited sense. Different stages can be routed to different agents:

autospec run -s --agent claude "description"   # specify with Claude Code
autospec run -ti --agent codex                  # tasks+implement with Codex

This is runtime agent selection per stage, not a formal multi-agent coordination protocol.

Orchestration pattern

Sequential with optional parallelism at task level. The default flow (specify → plan → tasks → implement) is strictly sequential with artifact dependencies. Within implement, task-mode execution respects dependency order but tasks with no dependencies could theoretically run in parallel (not currently implemented).

Isolation mechanism

Per-session context isolation. Each stage or task runs as a fresh bounded agent session. No git worktrees per feature — instead, a single feature branch is created at specify time and all stages work within it.

The autospec-worktree-setup skill exists but is an optional advanced capability for parallel task execution.

Execution mode

One-shot per stage invocation, chained by the CLI orchestrator. The binary drives each agent session as a subprocess and validates the output before proceeding.

Multi-model routing

Yes — different agents can be configured for different stages. The --agent flag accepts claude, codex, or opencode per invocation. A project config can set a default.

Prompt chaining

Yes, explicit. Each stage's YAML artifact IS the input to the next stage's agent session. The specify stage produces spec.yaml, which is injected as context for the plan stage, which produces plan.yaml, which is injected for tasks, etc.

Crash recovery

Yes — --from-phase N and --from-task T005 allow resumption after failure without re-running completed stages.

Consensus mechanism

None.

Parallel execution

Not currently available at stage level. At task level, task-mode implementation respects dependency order but executes sequentially.

Auto-validators

  • Artifact completeness validation before each stage (programmatic, built into CLI)
  • autospec doctor — pre-flight dependency check
  • Optional checklist validation (autospec checklist) before implement
08

Ui Cli Surface

Autospec — UI / CLI Surface

Dedicated CLI binary

Yes.

  • Name: autospec
  • Language: Go
  • Location after install: ~/.local/bin/autospec
  • Is thin wrapper: No — it is a native Go orchestration engine, not a wrapper around agent CLIs. It invokes agents as subprocesses but contains its own artifact management, validation, and state tracking logic.
  • Subcommands: ~17+ (specify, plan, tasks, implement, constitution, clarify, analyze, checklist, all, prep, run, st/status, history, init, doctor, sync, new-feature, completion, version)

Local web dashboard

None.

IDE integration

No IDE plugin. Autospec integrates with Claude Code, Codex CLI, and OpenCode via their CLI interfaces and skill/command installation.

After autospec init, agent-native skills are installed:

  • Claude Code: .claude/skills/autospec.*/SKILL.md (slash-command style: /autospec.specify, /autospec.plan, etc.)
  • Codex / OpenCode: .agents/skills/autospec-*/SKILL.md ($autospec-specify, etc.)

Observability

  • History: autospec history / autospec history -v — shows all past command runs with status, duration, exit code
  • Status: autospec st / autospec st -v — shows current spec progress and task completion
  • OS notifications: Native desktop notifications with custom sound support on stage completion
  • Shell completion: autospec completion [bash|zsh|fish]

Documentation site

An Astro-based documentation site lives in site/. Published to GitHub Pages / ariel-frischer.github.io/autospec/.

Installation surface

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

Downloads a pre-built binary from GitHub Releases. No npm, no pip, no Go toolchain required for end users.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…