Autospec: Spec-Driven Development for AI Coding Agents

AI agents from unpredictable generators into reliable execution engines bound by explicit contracts.

Core Solution

Implementing a spec-driven AI workflow requires establishing a repeatable pipeline that separates intent, strategy, decomposition, and execution. The autospec CLI provides the orchestration layer, but the architectural value comes from how teams structure their artifacts and validation gates.

Step 1: Project Initialization & Guardrail Definition

Before generating any feature artifacts, establish project-level constraints. These guardrails prevent agents from introducing anti-patterns or violating architectural boundaries.

# Verify environment dependencies
autospec doctor

# Initialize project configuration
autospec init --engine codex

# Generate architectural constitution
autospec constitution --template strict

The constitution file defines non-negotiable rules: preferred dependency injection patterns, error handling standards, testing requirements, and forbidden libraries. This file is injected into every subsequent spec generation request, ensuring consistent output across multiple agents and sessions.

Step 2: Spec Generation & Validation

Generate the feature specification in isolation. This forces explicit requirement definition before any implementation logic is considered.

autospec run --phase spec --feature "inventory-sync-pipeline"

The CLI creates a structured directory:

specs/
  004-inventory-sync-pipeline/
    spec.yaml

The generated spec.yaml contains outcome-focused requirements, not implementation details:

feature: inventory-sync-pipeline
version: 1.0.0
objectives:
  - synchronize warehouse stock levels with e-commerce platform
  - handle partial sync failures with idempotent retries
  - expose health check endpoint for monitoring
constraints:
  max_payload_size: "5MB"
  retry_policy: exponential_backoff
  data_format: json_schema_v7
acceptance_criteria:
  - sync completes within 30s for payloads under 1MB
  - failed batches are logged to audit queue
  - endpoint returns 200 when all downstream services are reachable

Review this artifact with stakeholders. Validate that objectives align with business goals and constraints match infrastructure capabilities. Use JSON Schema validation to ensure structural integrity before proceeding.

Step 3: Strategic Planning & Task Decomposition

Once the spec is approved, generate the implementation strategy and break it into discrete, executable units.

autospec run --phase plan-tasks --feature "inventory-sync-pipeline"

This produces plan.yaml and tasks.yaml:

# plan.yaml
strategy: event-driven synchronization with dead-letter queue fallback
components:
  - inventory_listener: consumes warehouse update events
  - sync_engine: transforms and validates payloads
  - retry_handler: manages exponential backoff and audit logging
  - health_monitor: exposes liveness and readiness probes
dependencies:
  - redis_streams
  - postgres_audit_log
  - prometheus_metrics

# tasks.yaml
task_sequence:
  - T001: scaffold event listener with Redis stream consumer
  - T002: implement payload transformer with JSON schema validation
  - T003: configure retry handler with dead-letter queue routing
  - T004: add Prometheus metrics and health check endpoint
  - T005: write integration tests with mocked warehouse API

The plan defines architectural boundaries and component interactions. Tasks are ordered by dependency graph, ensuring that foundational modules are implemented before dependent services. This decomposition prevents agents from attempting monolithic generation, which frequently exceeds context limits and produces inconsistent code.

Step 4: Phased Implementation & Resumption

Execute implementation in controlled batches. Use agent-specific routing when multiple models are available.

# Run all phases sequentially
autospec run --phase implement --feature "inventory-sync-pipeline" --agent claude

# Resume from specific task if execution fails
autospec run --phase implement --from-task T003 --feature "inventory-sync-pipeline"

The implementation phase consumes the task list and generates code within the constraints defined in the spec and plan. If a task fails or produces invalid output, the pipeline halts. Developers can inspect the generated code, adjust the task definition, and resume from the exact failure point without regenerating upstream work.

Architecture Decisions & Rationale

Why YAML-first artifacts? YAML provides a human-readable, machine-parsable format that integrates with existing toolchains. Unlike markdown or conversational transcripts, YAML supports schema validation, programmatic diffing, and automated linting. CI pipelines can reject specs that violate architectural rules before any code is generated.

Why phased execution? LLMs degrade in quality when asked to handle multiple concerns simultaneously. Separating spec, plan, tasks, and implementation reduces cognitive load on the model and provides explicit review gates. Each phase produces a verifiable artifact that can be version-controlled, peer-reviewed, and rolled back independently.

Why agent routing? Different models excel at different phases. Claude Code demonstrates strong architectural reasoning for planning. Codex CLI shows superior code generation for task execution. OpenCode provides fast iteration for spec drafting. Explicit routing ensures each phase uses the optimal model, reducing token costs and improving output quality.

Pitfall Guide

1. Over-Specifying Implementation Details

Explanation: Including specific library choices, function signatures, or database schemas in the spec forces the agent into rigid patterns that may conflict with actual codebase constraints. Fix: Keep specs outcome-focused. Define what the system must achieve, not how it must be built. Move implementation details to the plan or task definitions.

2. Skipping Constitution Validation

Explanation: Without architectural guardrails, agents introduce inconsistent patterns, deprecated dependencies, or security anti-patterns across features. Fix: Run autospec constitution early and enforce it via pre-commit hooks. Validate generated specs against the constitution before proceeding to planning.

3. Ignoring Task Dependency Ordering

Explanation: Executing tasks out of sequence causes compilation failures, missing imports, and broken integration points. Agents cannot infer implicit dependencies without explicit ordering. Fix: Generate tasks using dependency-aware decomposition. Validate the sequence with a topological sort before execution. Use --from-task flags to resume safely after failures.

4. Context Window Overflow During Implementation

Explanation: Long task lists or complex specs exceed agent context limits, causing silent truncation or degraded output quality. Fix: Chunk tasks into batches of 3-5 units. Monitor token usage per phase. Use incremental resumption (--from-phase) instead of regenerating entire pipelines.

5. Treating AI Output as Production-Ready

Explanation: Generated code often lacks edge case handling, proper error propagation, or security hardening. Blindly merging AI output introduces vulnerabilities. Fix: Implement mandatory review gates. Require static analysis, security scanning, and integration testing before merging. Use AI output as a draft, not a final artifact.

6. Mixing Agents Without Explicit Routing

Explanation: Running different models on the same pipeline without configuration causes inconsistent output styles, conflicting architectural decisions, and unpredictable behavior. Fix: Define agent profiles in the project configuration. Route each phase to the optimal model. Document routing decisions in the constitution.

7. Neglecting Artifact Version Control

Explanation: Storing specs and plans locally without committing them to version control breaks traceability and prevents team collaboration. Fix: Commit all YAML artifacts alongside generated code. Use semantic versioning for feature directories. Tag releases with corresponding spec versions.

Production Bundle

Action Checklist

• Initialize project constitution with architectural guardrails before generating any features
• Validate spec artifacts against JSON Schema to ensure structural integrity
• Decompose features into dependency-ordered task sequences before execution
• Route each pipeline phase to the optimal AI agent based on capability profiling
• Implement mandatory review gates between spec, plan, and implementation phases
• Configure CI/CD pipelines to lint YAML artifacts and reject non-compliant specs
• Use incremental resumption flags to recover from failed tasks without regenerating upstream work
• Commit all spec, plan, and task artifacts to version control alongside generated code

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small feature (< 3 tasks)	Single-command full pipeline (--all)	Reduces overhead for straightforward implementations	Low (minimal token usage)
Complex refactor (> 8 tasks)	Phased execution with intermediate reviews	Prevents context overflow and enables architectural validation	Medium (higher review time, lower rework)
Multi-agent team	Explicit agent routing per phase	Optimizes model strengths and reduces inconsistent output	Low (better token efficiency)
CI/CD integration	YAML schema validation + automated linting	Enforces standards before code generation begins	Low (shifts cost left, reduces deployment failures)
Legacy codebase migration	Spec-first with strict constitution constraints	Prevents agents from introducing anti-patterns into old systems	High (initial setup cost, long-term stability gain)

Configuration Template

# autospec.config.yaml
project:
  name: platform-services
  version: 2.1.0
  repository: git@github.com:org/platform-services.git

guardrails:
  constitution: .autospec/constitution.yaml
  schema_version: v3
  max_context_tokens: 120000
  retry_on_failure: true
  max_retries: 2

agent_routing:
  spec_generation: opencode
  planning: claude_code
  task_decomposition: codex_cli
  implementation: claude_code

validation:
  pre_spec:
    - schema_check
    - constitution_compliance
  pre_plan:
    - dependency_graph_validation
    - token_budget_check
  pre_implementation:
    - task_sequence_verification
    - agent_capability_match

output:
  artifact_directory: specs/
  naming_convention: sequential_number-feature_slug
  versioning: semantic

Quick Start Guide

1. Verify Dependencies: Ensure Git is installed and at least one supported AI agent (Claude Code, Codex CLI, or OpenCode) is configured with valid credentials. Run autospec doctor to validate the environment.
2. Initialize Project: Execute autospec init in your repository root. This creates the configuration file and artifact directory structure. Run autospec constitution to generate architectural guardrails tailored to your stack.
3. Generate First Spec: Use autospec run --phase spec --feature "your-feature-name" to create an initial specification. Review the generated YAML, adjust objectives and constraints, and commit the artifact.
4. Execute Pipeline: Run autospec run --phase plan-tasks --feature "your-feature-name" to generate the strategy and task sequence. Validate the dependency order, then execute implementation with autospec run --phase implement --feature "your-feature-name".
5. Integrate with CI: Add YAML schema validation and constitution compliance checks to your pipeline. Configure automated linting to reject non-compliant specs before they trigger agent execution. Commit all artifacts alongside generated code for full traceability.