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

> Discover the AIOX Spec Pipeline, an autonomous workflow transforming requirements into version-controlled executable specs. Learn how AIOX automates complexity for better software development.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: deep-dive
- Published: 2026-03-15

---

**The AIOX Spec Pipeline is an autonomous, complexity-aware workflow that converts informal requirements into version-controlled, executable specifications stored as [`spec.md`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

```bash
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:

```bash

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

```bash

# 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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/workflows/spec-pipeline.yaml). This directory contains [`requirements.json`](https://github.com/SynkraAI/aiox-core/blob/main/requirements.json), [`complexity.json`](https://github.com/SynkraAI/aiox-core/blob/main/complexity.json), [`research.json`](https://github.com/SynkraAI/aiox-core/blob/main/research.json), [`spec.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec.md), and [`critique.json`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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.