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

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. 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 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
• Task binding: The command maps directly to qa-review-build.md

The qa-review-build.md Task Definition

The core logic resides in .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, implementation.yaml, story MD, previous qa_report.md	read_file actions	JSON context object for downstream phases
1 Verify Subtasks	Parsed 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	diff_report	regressionReport
7 Performance Benchmarks	Load-test scripts	run_perf	performanceMetrics
8 Report Generation	All previous outputs	Assemble markdown qa_report.md	qa_report.md (final artefact)
9 Signal Emission	qa_report.md verdict	Write 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.

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

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:

# 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. All artefacts are written under docs/stories/{storyId}/qa/ (e.g., qa_report.md).

Customizing Individual Phases

You can extend the 10-phase workflow by editing .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 and locate Phase 5.
2. Add a new action entry:

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

# 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	Defines the @qa agent, its commands (review-build, critique-spec, etc.)	qa.md
.aios-core/development/tasks/qa-review-build.md	Full 10-phase IO-structured review specification	qa-review-build.md
docs/en/aios-workflows/qa-loop-workflow.md	High-level workflow diagram & when to run the review	qa-loop-workflow.md
CHANGELOG.md (Epic 6 entry)	Historical note of the QA Evolution introduction	CHANGELOG – Epic 6
docs/guides/api-reference.md (review-build command)	CLI reference for *review-build syntax and flags	API reference – 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 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), 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 and 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. 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 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. 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.

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