# The 7 ADE Epics in AIOS-Core: Architecture, Relationships, and Implementation

> Discover the 7 ADE Epics in SynkraAI aios-core: Worktree Manager, Migration V2→V3, Spec Pipeline, Execution Engine, Recovery System, QA Evolution, and Memory Layer. Understand their architecture and relationships in this autono...

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: architecture
- Published: 2026-02-19

---

**The AIOS-Core framework implements seven ADE Epics—Worktree Manager, Migration V2→V3, Spec Pipeline, Execution Engine, Recovery System, QA Evolution, and Memory Layer—coordinated by a Master Orchestrator to form a tightly-coupled autonomous development pipeline.**

The **SynkraAI/aios-core** repository powers the **AIOS Autonomous Development Engine (ADE)**, a modular system designed to automate end-to-end software development workflows. Understanding the seven ADE Epics is essential for developers extending the framework or debugging pipeline failures, as each epic represents a distinct functional layer with specific entry points and responsibilities.

## Overview of the 7 ADE Epics and the Master Orchestrator

While the ADE architecture comprises eight numbered epics (0-7), **Epic 0 (Master Orchestrator)** serves as the global controller that sequences the other components. The **7 ADE Epics** proper—numbered 1 through 7—implement the actual autonomous development pipeline capabilities, from workspace isolation to memory persistence.

| Epic | Name | Core Responsibility | Main Entry Point |
|------|------|---------------------|------------------|
| **Epic 1** | **Worktree Manager** | Isolates development branches using Git worktrees for parallel story processing | [`infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/worktree-manager.js) |
| **Epic 2** | **Migration V2→V3** | Converts agents and tasks to the auto-Claude V3 schema | [`infrastructure/scripts/migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/migrate-agent.js) |
| **Epic 3** | **Spec Pipeline** | Transforms user requests into executable specs through five phases | [`development/tasks/spec-pipeline.yaml`](https://github.com/SynkraAI/aios-core/blob/main/development/tasks/spec-pipeline.yaml) |
| **Epic 4** | **Execution Engine** | Executes specs, tracks sub-tasks, and verifies completion | [`infrastructure/scripts/plan-tracker.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/plan-tracker.js) |
| **Epic 5** | **Recovery System** | Detects failures, rolls back work, and manages retries | [`core/orchestration/recovery-handler.js`](https://github.com/SynkraAI/aios-core/blob/main/core/orchestration/recovery-handler.js) |
| **Epic 6** | **QA Evolution** | Enforces quality gates via self-critique checklists | [`core/qa/self-critique-checklist.md`](https://github.com/SynkraAI/aios-core/blob/main/core/qa/self-critique-checklist.md) |
| **Epic 7** | **Memory Layer** | Persists learned insights and patterns across runs | [`synapse/memory-bridge.js`](https://github.com/SynkraAI/aios-core/blob/main/synapse/memory-bridge.js) |

## Deep Dive into the 7 Functional ADE Epics

### Epic 1: Worktree Manager

The **Worktree Manager** isolates development environments using Git worktrees, preventing branch conflicts when processing multiple stories in parallel. This epic creates isolated workspaces before any code generation begins.

The implementation resides in [`infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/worktree-manager.js):

```javascript
// src/example-worktree.js
const { WorktreeManager } = require('../infrastructure/scripts/worktree-manager');

// Create a new worktree for story "STORY-42"
(async () => {
  const manager = new WorktreeManager(process.cwd());
  await manager.create('STORY-42');
  console.log('Worktree created');   // 👉 isolates the story's code
})();

```

### Epic 2: Migration V2→V3

**Migration V2→V3** ensures backward compatibility by converting legacy V2 agents and tasks to the **auto-Claude V3 format**. This epic validates against the JSON schemas defined in [`infrastructure/schemas/agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/schemas/agent-v3-schema.json) and [`infrastructure/schemas/task-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/schemas/task-v3-schema.json).

Run migrations via [`infrastructure/scripts/migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/migrate-agent.js):

```bash

# Migrate a single agent

node .aios-core/infrastructure/scripts/migrate-agent.js \
  --agent=architect \
  --output=.aios-core/infrastructure/scripts/architect-v3.json

```

### Epic 3: Spec Pipeline

The **Spec Pipeline** transforms vague user requests into fully-specified, executable specifications through five sequential phases: gather, assess, research, write, and critique. This epic outputs a concrete [`spec-pipeline.yaml`](https://github.com/SynkraAI/aios-core/blob/main/spec-pipeline.yaml) that drives downstream execution.

Trigger the pipeline via [`development/tasks/spec-pipeline.yaml`](https://github.com/SynkraAI/aios-core/blob/main/development/tasks/spec-pipeline.yaml):

```javascript
// src/run-spec-pipeline.js
const { execSync } = require('child_process');

// The spec-pipeline.yaml orchestrates the 5 phases
execSync('node .aios-core/development/tasks/spec-pipeline.yaml', { stdio: 'inherit' });

```

Individual phase definitions reside in companion files like [`spec-gather-requirements.md`](https://github.com/SynkraAI/aios-core/blob/main/spec-gather-requirements.md) within the `development/tasks/` directory.

### Epic 4: Execution Engine

The **Execution Engine** consumes the generated spec and drives sub-task execution to completion. It tracks progress via [`infrastructure/scripts/plan-tracker.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/plan-tracker.js) and verifies completion through [`infrastructure/scripts/subtask-verifier.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/subtask-verifier.js).

```javascript
// src/execute-plan.js
const { PlanTracker } = require('../infrastructure/scripts/plan-tracker');

(async () => {
  const tracker = new PlanTracker('spec-output.yaml');
  await tracker.run();          // walks through sub-tasks, persists progress
})();

```

### Epic 5: Recovery System

When failures occur, the **Recovery System** detects the fault, rolls back partially completed work, and manages automatic retries or escalation. This epic integrates with the Master Orchestrator to resume the pipeline once issues are resolved.

```javascript
// src/recover.js
const { RecoveryHandler } = require('../core/orchestration/recovery-handler');

(async () => {
  const handler = new RecoveryHandler();
  await handler.handleEpicFailure(4, new Error('sub-task timeout'));
})();

```

### Epic 6: QA Evolution

**QA Evolution** enforces quality gates through automated self-critique checklists. After each sub-task and at spec completion, this epic validates naming conventions, required fields, and schema compliance via [`core/qa/self-critique-checklist.md`](https://github.com/SynkraAI/aios-core/blob/main/core/qa/self-critique-checklist.md).

```yaml

# development/tasks/self-critique-checklist.md

---
epic: 'Epic 6 - QA Evolution'
checks:
  - title: "Spec follows naming conventions"
    test: "grep -q '^name:' spec.yaml"
  - title: "All required fields present"
    test: "node scripts/validate-spec.js spec.yaml"
---

```

The Execution Engine automatically loads this checklist after each sub-task.

### Epic 7: Memory Layer

The **Memory Layer** persists learned insights, dependency conflicts, and successful patterns across autonomous development cycles. By recording "gotchas" in [`synapse/memory-bridge.js`](https://github.com/SynkraAI/aios-core/blob/main/synapse/memory-bridge.js), this epic enables continuous improvement, allowing future runs to reuse validated solutions.

```javascript
// src/memory-example.js
const { MemoryBridge } = require('../synapse/memory-bridge');

(async () => {
  const bridge = new MemoryBridge();
  await bridge.storeInsight('dependency-conflict', { lib: 'lodash', version: '4.17.0' });
  const hints = await bridge.getInsights('dependency-conflict');
  console.log(hints);
})();

```

## How the ADE Epics Relate to Each Other

The seven ADE Epics operate as a **state machine** orchestrated by Epic 0 (Master Orchestrator). The standard execution flow follows a sequential pipeline with cross-cutting concerns for resilience and quality:

1. **Epic 0** boots the system and loads configuration for each subsequent epic.
2. **Epic 1** creates an isolated worktree for the story being processed.
3. **Epic 2** guarantees that every agent and task conforms to the V3 schema required by later phases.
4. **Epic 3** transforms the user's high-level request into a concrete [`spec-pipeline.yaml`](https://github.com/SynkraAI/aios-core/blob/main/spec-pipeline.yaml).
5. **Epic 4** consumes that spec, creates a plan, and drives the sub-tasks.

When any step fails, **Epic 5** rolls back the state and either retries or signals the orchestrator to resume later. **Epic 6** runs a self-critique checklist after each sub-task and at spec completion to enforce quality gates. Throughout the run, **Epic 7** records insights—such as failed dependencies or successful patterns—making future runs smarter.

The orchestrator therefore behaves like this state machine:

```

Epic0 → Epic1 → Epic2 → Epic3 → Epic4
            ↘︎      ↘︎      ↘︎
            (recovery via Epic5) → (QA via Epic6) → (memory via Epic7)

```

When a gate fails, the Master Orchestrator pauses, invokes the Recovery System, and resumes automatically once the issue is resolved. The Memory Layer is consulted on every pass to suggest optimizations.

## Summary

- **Epic 1 (Worktree Manager)** isolates development environments using Git worktrees to prevent branch conflicts during parallel story processing.
- **Epic 2 (Migration V2→V3)** ensures backward compatibility by converting legacy agents and tasks to the auto-Claude V3 schema.
- **Epic 3 (Spec Pipeline)** transforms vague user requests into fully-specified, executable specifications through five sequential phases.
- **Epic 4 (Execution Engine)** consumes generated specs and drives sub-task execution to completion while tracking progress.
- **Epic 5 (Recovery System)** provides resilience by detecting failures, rolling back partial work, and managing automatic retries.
- **Epic 6 (QA Evolution)** enforces quality gates through automated self-critique checklists after each sub-task.
- **Epic 7 (Memory Layer)** persists learned insights and patterns across runs to enable continuous improvement in future cycles.

## Frequently Asked Questions

### What is the difference between Epic 0 and the other 7 ADE Epics?

**Epic 0 (Master Orchestrator)** functions as the global controller that sequences and coordinates the seven functional ADE Epics (1-7), whereas the other epics perform specific development tasks such as workspace isolation, schema migration, and execution. While Epic 0 handles bootstrapping, configuration loading, and state machine transitions in [`core/orchestration/master-orchestrator.js`](https://github.com/SynkraAI/aios-core/blob/main/core/orchestration/master-orchestrator.js), Epics 1-7 implement the actual autonomous development pipeline capabilities.

### How does the Recovery System (Epic 5) handle failures in the Execution Engine (Epic 4)?

The Recovery System monitors the Execution Engine via the `handleEpicFailure` method in [`core/orchestration/recovery-handler.js`](https://github.com/SynkraAI/aios-core/blob/main/core/orchestration/recovery-handler.js), which is invoked automatically when the Plan Tracker or Subtask Verifier detects timeouts or validation failures. Epic 5 rolls back partially completed work from Epic 4, manages retry logic or escalation, and integrates with the Master Orchestrator to resume the pipeline once the failure state is resolved.

### Can I run individual ADE Epics independently of the Master Orchestrator?

Yes, each ADE Epic exposes standalone entry points—such as [`infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/worktree-manager.js) for Epic 1 or [`infrastructure/scripts/migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/scripts/migrate-agent.js) for Epic 2—that can be invoked directly for testing or manual operations. However, in production deployments, the Master Orchestrator ([`core/orchestration/master-orchestrator.js`](https://github.com/SynkraAI/aios-core/blob/main/core/orchestration/master-orchestrator.js)) manages these interactions to ensure proper sequencing, state persistence, and recovery across the full pipeline.

### What schema version does the Migration epic (Epic 2) target?

Epic 2 targets the **auto-Claude V3 format**, converting legacy V2 agents and tasks to comply with the JSON schemas defined in [`infrastructure/schemas/agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/schemas/agent-v3-schema.json) and [`infrastructure/schemas/task-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/infrastructure/schemas/task-v3-schema.json). This migration ensures that all downstream components—particularly the Spec Pipeline (Epic 3) and Execution Engine (Epic 4)—receive standardized inputs that conform to the expected V3 structure.