# How to Implement QA Evolution with 10-Phase Structured Reviews in aios-core

> Learn to implement QA Evolution with 10-phase structured reviews in aios-core using the @qa agent and *review-build command. Enhance your quality checks now.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The QA Evolution system in aios-core replaces ad-hoc quality checks with a deterministic 10-phase IO-structured review orchestrated by the `@qa` agent through the `*review-build` command.**

The SynkraAI/aios-core repository introduces **QA Evolution** in Epic 6 to transform quality assurance from a single manual checkpoint into a repeatable, automated pipeline. This guide explains how to implement the **10-phase structured review** system that uses input-output (IO) phase mechanics to validate stories from specification through deployment.

## Understanding the QA Evolution Architecture

The QA Evolution architecture centers on the `@qa` agent and its declarative task definitions. Unlike traditional QA processes that rely on manual checklists, this system encodes quality gates as code within the repository.

### The @qa Agent and Command Interface

The `@qa` agent is defined in [`.aios-core/development/agents/qa.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/agents/qa.md). It exposes the `*review-build` command, which serves as the primary entry point for the 10-phase review. When you invoke `@qa *review-build {story-id}`, the agent binds to the [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md) task and executes the structured workflow.

Key implementation details from the source:
- Command pattern: `@qa *review-build STORY-ID`
- Agent configuration: [`.aios-core/development/agents/qa.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/agents/qa.md)
- Task binding: The command maps directly to [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md)

### The qa-review-build.md Task Definition

The core logic resides in [`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md). This file contains a declarative YAML specification that defines the 10 phases, their inputs, actions, and outputs. The task implements the **IO-phase pattern**: each phase consumes specific input artefacts, performs deterministic actions, and produces output artefacts that subsequent phases consume.

The task specification includes:
- Phase definitions (0 through 9)
- Input/output mappings for each phase
- Verification gates (`type: gate`, `blocking: true`)
- Action bindings (e.g., `read_file`, `run_tests`, `external_tool`)

## The 10-Phase IO-Structured Review Workflow

The QA Evolution process breaks quality assurance into ten discrete phases, each with explicit inputs and outputs. This structure creates a deterministic pipeline where quality data flows sequentially from context loading through final signal emission.

### Phase Breakdown and IO Mechanics

| Phase | Input (IO) | Core Action | Output (IO) |
|-------|------------|-------------|-------------|
| **0 Load Context** | [`spec.md`](https://github.com/SynkraAI/aios-core/blob/main/spec.md), [`implementation.yaml`](https://github.com/SynkraAI/aios-core/blob/main/implementation.yaml), story MD, previous [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) | `read_file` actions | JSON `context` object for downstream phases |
| **1 Verify Subtasks** | Parsed [`implementation.yaml`](https://github.com/SynkraAI/aios-core/blob/main/implementation.yaml) checklist | `extract_checklist`, `git_log` verification | `subtasks` status report |
| **2 Evidence Requirements** | Story metadata, PR type detection | `detect_pr_type`, `evaluate_evidence_checklist` | `evidenceCheck` (score, missing items) |
| **3 Automated Tests** | Test suites defined in `scripts/` | `run_tests` (unit, integration, e2e) | `testResults` (pass/fail, coverage) |
| **4 Browser/DB Verification** | Deployed build URL, DB connection info | `browser_check`, `db_check` | `verificationReport` |
| **5 Code Review** | Source files, previous diffs | `static_analysis`, `security_scan` | `codeReviewReport` |
| **6 Regression Detection** | Historic [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) | `diff_report` | `regressionReport` |
| **7 Performance Benchmarks** | Load-test scripts | `run_perf` | `performanceMetrics` |
| **8 Report Generation** | All previous outputs | Assemble markdown [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) | [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) (final artefact) |
| **9 Signal Emission** | [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) verdict | Write [`status.json`](https://github.com/SynkraAI/aios-core/blob/main/status.json) with `signal: APPROVE\|REJECT` | Status used by CI/CD gates |

Each phase is **blocking** by default, meaning the pipeline halts if a phase fails. Certain phases, such as Phase 2 (Evidence Requirements), can be configured as non-blocking or advisory depending on the task configuration in [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md).

## CI/CD Integration and Quality Gates

The QA Evolution system integrates with continuous integration pipelines through deterministic exit signals. The final phase emits a binary `APPROVE` or `REJECT` signal that CI systems can consume as a quality gate.

### GitHub Actions Integration Example

The verification gate defined in [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md) uses `type: gate` with `blocking: true` to ensure the pipeline halts if the `signal` is not `APPROVE`. Below is a practical GitHub Actions workflow that invokes the review and enforces the quality gate:

```yaml
name: QA Evolution Gate

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  qa-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run QA Review
        run: aios qa *review-build ${{ env.STORY_ID }}
        
      - name: Enforce QA Signal
        if: failure()
        run: echo "QA failed – PR cannot be merged"

```

The `aios` CLI resolves the `@qa` agent and executes all 10 phases. If any blocking phase fails or the final signal is `REJECT`, the command exits with a non-zero status, causing the CI job to fail and blocking the merge.

## Practical Implementation Guide

Implementing the 10-phase structured review requires configuring the agent, invoking the command, and optionally customizing phases to match your technology stack.

### Running the Review Command

To execute the full QA Evolution workflow, use the `@qa` agent's `*review-build` command followed by the story identifier:

```bash

# From the repository root

@qa *review-build 6.1            # Full 10-phase review

@qa *review-build 6.1 --quick   # Skip non-critical phases (browser/db)

```

The command resolves `@qa` → `review-build` → [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md). All artefacts are written under `docs/stories/{storyId}/qa/` (e.g., [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md)).

### Customizing Individual Phases

You can extend the 10-phase workflow by editing [`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md). For example, to add SonarQube analysis to Phase 5 (Code Review):

1. Edit [`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md) and locate Phase 5.
2. Add a new action entry:

```yaml
- id: run-sonarqube
  action: external_tool
  cmd: sonar-scanner -Dsonar.projectKey=myproj -Dsonar.sources=src

```

3. Update the output section to include [`codeReviewReport.sonar.json`](https://github.com/SynkraAI/aios-core/blob/main/codeReviewReport.sonar.json) as an additional artefact.

### Automating the Story Development Cycle

The QA Evolution system fits into a complete story lifecycle managed by aios-core agents. A typical automated workflow follows this sequence:

```bash

# 1. Create story

@po *create-story STORY-42

# 2. Develop

@dev *implement STORY-42

# 3. QA (structured)

@qa *review-build STORY-42

# 4. If APPROVE, continue to DevOps

@devops *deploy STORY-42

```

Each step respects the **IO-phase** contract: inputs are read from the previous stage's outputs, and new artefacts are generated for downstream consumption. This creates a deterministic pipeline where quality data flows sequentially from specification to deployment.

## Key Source Files and References

The following files define the QA Evolution implementation in SynkraAI/aios-core:

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`.aios-core/development/agents/qa.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/agents/qa.md) | Defines the `@qa` agent, its commands (`review-build`, `critique-spec`, etc.) | [qa.md](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/agents/qa.md) |
| [`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md) | Full 10-phase IO-structured review specification | [qa-review-build.md](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md) |
| [`docs/en/aios-workflows/qa-loop-workflow.md`](https://github.com/SynkraAI/aios-core/blob/main/docs/en/aios-workflows/qa-loop-workflow.md) | High-level workflow diagram & when to run the review | [qa-loop-workflow.md](https://github.com/SynkraAI/aios-core/blob/main/docs/en/aios-workflows/qa-loop-workflow.md) |
| [`CHANGELOG.md`](https://github.com/SynkraAI/aios-core/blob/main/CHANGELOG.md) (Epic 6 entry) | Historical note of the QA Evolution introduction | [CHANGELOG – Epic 6](https://github.com/SynkraAI/aios-core/blob/main/CHANGELOG.md#epic-6---qa-evolution) |
| [`docs/guides/api-reference.md`](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/api-reference.md) (review-build command) | CLI reference for `*review-build` syntax and flags | [API reference – review-build](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/api-reference.md#review-build) |

## Summary

Implementing **QA Evolution with 10-phase structured reviews** in aios-core requires activating the `@qa` agent's `*review-build` command, which runs the declarative [`qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/qa-review-build.md) task. Key takeaways include:

- The **10-phase IO pattern** creates a deterministic pipeline where each quality check consumes specific inputs and produces structured outputs for downstream phases.
- **Blocking phases** enforce quality gates, while the final **Signal Emission** phase (Phase 9) produces binary `APPROVE` or `REJECT` verdicts for CI/CD integration.
- Configuration resides in **declarative markdown files** ([`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md)), making the workflow version-controllable and extensible without core code changes.
- The system integrates with **GitHub Actions** and other CI platforms through the `aios` CLI, enabling automated quality gates that prevent merges on rejection.

## Frequently Asked Questions

### What is QA Evolution in aios-core?

**QA Evolution** is a quality assurance framework introduced in Epic 6 of the SynkraAI/aios-core repository. It replaces traditional ad-hoc QA checks with a structured, automated 10-phase review process orchestrated by the `@qa` agent. The system uses input-output (IO) phase mechanics to ensure each quality validation step consumes specific artefacts and produces deterministic outputs that feed into subsequent phases or CI/CD gates.

### How does the 10-phase review differ from traditional QA approaches?

Traditional QA typically relies on manual code reviews and end-of-cycle testing without structured feedback loops. The **10-phase structured review** in aios-core breaks quality assurance into discrete, automated steps including context loading, subtask verification, evidence checking, automated testing, browser/database verification, static analysis, regression detection, and performance benchmarking. Each phase is **blocking** by default, meaning the pipeline halts immediately on failure, and all outputs are written to structured files like [`qa_report.md`](https://github.com/SynkraAI/aios-core/blob/main/qa_report.md) and [`status.json`](https://github.com/SynkraAI/aios-core/blob/main/status.json) for auditability.

### Can I customize individual phases in the QA review?

Yes, you can customize any of the 10 phases by editing [`.aios-core/development/tasks/qa-review-build.md`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/qa-review-build.md). For example, to add a new static analysis tool like SonarQube to Phase 5 (Code Review), you would add a new action entry with `action: external_tool` and specify the command. You can also modify output mappings to include additional artefacts, or change whether a phase is blocking or advisory by adjusting the gate configuration in the YAML specification.

### How do I integrate QA Evolution with my CI/CD pipeline?

The QA Evolution system integrates through the `*review-build` command's exit status and the [`status.json`](https://github.com/SynkraAI/aios-core/blob/main/status.json) signal file. When run in a CI environment like GitHub Actions, the command executes all 10 phases and writes a final `APPROVE` or `REJECT` signal to [`status.json`](https://github.com/SynkraAI/aios-core/blob/main/status.json). If the signal is `REJECT` or any blocking phase fails, the command exits with a non-zero status, causing the CI job to fail. You can enforce this by running `aios qa *review-build ${{ env.STORY_ID }}` in your workflow and using the `failure()` condition to block merges on QA rejection.