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

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
Epic 2	Migration V2→V3	Converts agents and tasks to the auto-Claude V3 schema	infrastructure/scripts/migrate-agent.js
Epic 3	Spec Pipeline	Transforms user requests into executable specs through five phases	development/tasks/spec-pipeline.yaml
Epic 4	Execution Engine	Executes specs, tracks sub-tasks, and verifies completion	infrastructure/scripts/plan-tracker.js
Epic 5	Recovery System	Detects failures, rolls back work, and manages retries	core/orchestration/recovery-handler.js
Epic 6	QA Evolution	Enforces quality gates via self-critique checklists	core/qa/self-critique-checklist.md
Epic 7	Memory Layer	Persists learned insights and patterns across runs	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:

// 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 and infrastructure/schemas/task-v3-schema.json.

Run migrations via infrastructure/scripts/migrate-agent.js:

# 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 that drives downstream execution.

Trigger the pipeline via development/tasks/spec-pipeline.yaml:

// 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 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 and verifies completion through infrastructure/scripts/subtask-verifier.js.

// 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.

// 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.

# 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, this epic enables continuous improvement, allowing future runs to reuse validated solutions.

// 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.
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, 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, 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 for Epic 1 or 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) 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 and 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.

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