What Is the AIOX Spec Pipeline? How It Transforms Requirements into Executable Specs

The AIOX Spec Pipeline is an autonomous, complexity-aware workflow that converts informal requirements into version-controlled, executable specifications stored as spec.md.

The Spec Pipeline is a core component of the Auto-Claude ADE (Autonomous Development Engine) in the SynkraAI/aiox-core repository. It orchestrates specialized AI agents to analyze, research, and document requirements without human intervention, producing a specification file that downstream code generators and deployment bots can execute directly.

The Five-Phase Pipeline Architecture

The pipeline is defined in .aiox-core/development/workflows/spec-pipeline.yaml and executes five logical phases in sequence. Each phase is handled by a dedicated agent with a specific responsibility and output artifact.

Gather Phase (PM Agent)

The Gather phase normalizes raw input—user stories, PRDs, or ad-hoc notes—into structured data. The pm agent collects all functional and non-functional requirements and writes them to requirements.json according to the sequence defined at lines 70-78 of the workflow YAML.

Assess Phase (Architect Agent)

The Assess phase evaluates technical feasibility. The architect agent scores the requirement across five dimensions: scope, integration, infrastructure, knowledge, and risk. It outputs complexity.json (lines 100-108), which determines which execution path the pipeline follows.

Research Phase (Analyst Agent)

The Research phase validates external dependencies. The analyst agent queries Context7 and EXA to verify library compatibility, API contracts, and system constraints. It produces research.json containing verified claims and open questions (lines 134-144).

Write Phase (PM Agent)

The Write phase synthesizes all preceding artifacts into the final deliverable. The pm agent generates spec.md under docs/stories/{storyId}/spec/ (lines 172-184), strictly using derived content without invention. This file serves as the executable specification for downstream agents.

Critique Phase (QA Agent)

The Critique phase acts as a quality gate. The qa agent validates the spec against the original requirements, complexity analysis, and research data. It outputs critique.json with one of three statuses: APPROVED, NEEDS_REVISION, or BLOCKED (lines 202-214).

Complexity-Aware Execution Paths

The pipeline adapts its execution based on the complexity score from the Assess phase. This prevents over-processing simple tasks while ensuring rigorous validation for complex ones.

• SIMPLE Path: Runs only Gather → Write → Critique for straightforward requirements.
• STANDARD Path: Executes all five phases sequentially for medium-complexity stories.
• Complex Path: For high-complexity stories, the pipeline injects a Revise step (phase 5b) and a second critique pass (phase 5c) if the first critique returns NEEDS_REVISION (lines 236-260).

Pipeline Configuration and Triggers

The orchestration logic resides in .aiox-core/development/workflows/spec-pipeline.yaml. The workflow header declares the pipeline purpose and version at lines 1-8.

The pipeline supports two primary invocation methods:

• Primary trigger: The *create-spec CLI command (lines 24-27)
• Secondary trigger: Automatic execution via the story_created hook (lines 28-30)

The outputDir configuration at lines 80-82 ensures all artifacts are written to docs/stories/{storyId}/spec/, maintaining version control and traceability.

Running the Spec Pipeline (CLI Commands)

Developers interact with the pipeline through the AIOX CLI. Below are the primary commands for executing and debugging the workflow.

Execute the Full Pipeline

Start the complete spec generation process for a specific story:

aiox *create-spec checkout-flow

This command maps to the primary trigger defined at lines 24-27 of the workflow definition.

Run Individual Phases

For debugging or incremental development, execute specific phases independently:

# Gather requirements only

aiox *gather-requirements checkout-flow

# Assess complexity after gathering

aiox *assess-complexity checkout-flow

These correspond to phase-specific triggers at lines 33-37 (gather) and 40-42 (assess) in the YAML configuration.

Inspect Generated Artifacts

View the pipeline outputs to verify progress or debug issues:

# View structured requirements

cat docs/stories/checkout-flow/spec/requirements.json

# View the final executable specification

cat docs/stories/checkout-flow/spec/spec.md

Summary

• The AIOX Spec Pipeline is an autonomous workflow within the Auto-Claude ADE that converts informal requirements into executable spec.md files.
• It orchestrates five specialized agents (PM, Architect, Analyst, QA) across phases: Gather, Assess, Research, Write, and Critique.
• Execution is complexity-aware: simple stories skip research, while complex stories trigger automatic revision loops.
• The pipeline is configured in .aiox-core/development/workflows/spec-pipeline.yaml and invoked via the *create-spec CLI command.
• All artifacts are stored under docs/stories/{storyId}/spec/, ensuring version control and direct consumption by downstream code generation agents.

Frequently Asked Questions

How do I start the Spec Pipeline for a new user story?

Invoke the *create-spec command followed by your story identifier. For example: aiox *create-spec checkout-flow. The pipeline automatically triggers when you create a story if you have the story_created hook enabled in your workflow configuration.

What determines whether the pipeline runs the simple or standard path?

The Assess phase generates a complexity.json file that scores the requirement across scope, integration, infrastructure, knowledge, and risk dimensions. Simple stories bypass the Research phase entirely, while standard and complex paths require full five-phase execution with potential revision loops.

Where are the generated specification files stored?

All artifacts are written to docs/stories/{storyId}/spec/ as defined by the outputDir parameter in .aiox-core/development/workflows/spec-pipeline.yaml. This directory contains requirements.json, complexity.json, research.json, spec.md, and critique.json for complete traceability.

What happens if the QA critique finds issues with the spec?

If the qa agent returns NEEDS_REVISION in critique.json, the pipeline automatically invokes a Revise step and conducts a second critique pass for complex stories. This loop continues until the spec converges to APPROVED status or is marked BLOCKED requiring human intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}