# How the ADE (Autonomous Development Engine) Works: A Deep Dive into the 7 Epics in AIOX-Core

> Explore the ADE Autonomous Development Engine and its 7 Epics powering AIOX-Core's software development lifecycle. Understand how JavaScript modules manage Git worktrees to memory capture.

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

---

**The ADE (Autonomous Development Engine) is the core self-directed runtime that powers AIOX-Core's end-to-end software development lifecycle, splitting the process into seven progressive Epics—from isolated Git worktrees to cross-session memory capture—each implemented by specific JavaScript modules in the `.aiox-core/infrastructure/scripts/` directory.**

The **Autonomous Development Engine (ADE)** orchestrates autonomous software delivery within the SynkraAI/aiox-core repository. It transforms vague requirements into production code through a structured pipeline of seven progressive capabilities, each building upon the previous to enable true agent-driven development.

## Epic 1: Worktree Manager (Story Isolation)

**Epic 1** establishes isolated development environments using Git worktrees to prevent agent actions from affecting the `main` branch.

The **`WorktreeManager`** class in [`.aiox-core/infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/worktree-manager.js) creates a dedicated branch `auto-claude/<storyId>` and a corresponding worktree under `.aiox/worktrees/<storyId>`. It enforces configurable concurrency limits and automatically tracks stale worktrees older than 30 days.

```javascript
// demo-create-worktree.js
const WorktreeManager = require('.aiox-core/infrastructure/scripts/worktree-manager');

(async () => {
  const manager = new WorktreeManager();            // uses cwd as repo root
  const story = 'STORY-42';
  try {
    const info = await manager.create(story);
    console.log('Worktree created:', info);
  } catch (err) {
    console.error('❌', err.message);
  }
})();

```

Run the script with `node demo-create-worktree.js` inside the repository root to create an isolated workspace for any story ID.

## Epic 2: Project-Status System (YAML-Backed State)

**Epic 2** persists the overall project state in a human-readable YAML format that downstream pipelines consult for context.

The **[`project-status-loader.js`](https://github.com/SynkraAI/aiox-core/blob/main/project-status-loader.js)** module reads and writes [`.aiox/project-status.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/project-status.yaml), maintaining the current story, story-level statuses, and QA gates. The schema is validated internally, and the status file serves as the single source of truth for the **Spec Pipeline** and **Self-Healing** systems.

```javascript
const loader = require('.aiox-core/infrastructure/scripts/project-status-loader');

(async () => {
  const status = await loader.load();
  console.log('Current story:', status.project.currentStory);
  console.log('Story details:', status.stories[status.project.currentStory]);
})();

```

## Epic 3: Spec Pipeline (Requirement to Specification)

**Epic 3** converts vague user requests into complete, version-controlled specifications through a series of LLM-driven tasks.

Five sequential markdown tasks—[`spec-gather-requirements.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec-gather-requirements.md) → [`spec-assess-complexity.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec-assess-complexity.md) → [`spec-research-dependencies.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec-research-dependencies.md) → [`spec-write-spec.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec-write-spec.md) → [`spec-critique.md`](https://github.com/SynkraAI/aiox-core/blob/main/spec-critique.md)—are orchestrated by the [`spec-pipeline.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/spec-pipeline.yaml) workflow. Each task runs under a dedicated agent role (`@pm`, `@architect`, `@analyst`, `@qa`) to ensure comprehensive requirements gathering.

```javascript
const { execSync } = require('child_process');

function runSpecPipeline(storyId) {
  // The CLI command that triggers the pipeline (wrapper provided by AIOX)
  execSync(`npx aiox run spec-pipeline ${storyId}`, { stdio: 'inherit' });
}

runSpecPipeline('STORY-42');

```

## Epic 4: Execution Engine (Implementation Planning)

**Epic 4** generates actionable implementation plans, tracks sub-tasks, and verifies each step against expected outputs.

The **[`plan-tracker.js`](https://github.com/SynkraAI/aiox-core/blob/main/plan-tracker.js)** module creates a JSON plan mapping stories to subtasks and persists progress under `.aiox/`. The **[`subtask-verifier.js`](https://github.com/SynkraAI/aiox-core/blob/main/subtask-verifier.js)** validates each sub-task completion against its expected output and records self-critique results, ensuring accountability in the implementation phase.

```javascript
const PlanTracker = require('.aiox-core/infrastructure/scripts/plan-tracker');

(async () => {
  const tracker = new PlanTracker();
  const story = 'STORY-42';
  const plan = await tracker.createPlan(story, {
    description: 'Add login feature',
    subtasks: [
      { title: 'Design UI', owner: '@pm' },
      { title: 'Implement backend', owner: '@dev' },
      { title: 'Write tests', owner: '@qa' },
    ],
  });
  console.log('Plan created:', plan);
})();

```

## Epic 5: Self-Healing (Auto-Cure Loop)

**Epic 5** detects stuck or failing pipelines and automatically attempts recovery through alternative approaches, rollbacks, or escalation.

The **[`stuck-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/stuck-detector.js)** monitors execution logs and error patterns, triggering when thresholds like three identical errors within a 10-minute window are hit. Upon detection, **[`recovery-tracker.js`](https://github.com/SynkraAI/aiox-core/blob/main/recovery-tracker.js)** records the attempt and invokes **[`rollback-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/rollback-manager.js)** or **[`approach-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/approach-manager.js)** to auto-cure the pipeline without human intervention.

```javascript
const StuckDetector = require('.aiox-core/infrastructure/scripts/stuck-detector');

(async () => {
  const detector = new StuckDetector({ threshold: 3, windowMs: 10 * 60 * 1000 });
  const isStuck = await detector.check('STORY-42', 'plan-create-implementation');
  if (isStuck) console.log('⚠️ Task is stuck – triggering recovery');
})();

```

## Epic 6: QA Evolution (Continuous Quality Loop)

**Epic 6** transforms quality assurance into an iterative, self-improving loop that auto-generates reports, creates fix-requests, and reruns tests until gates pass.

The **[`qa-loop-orchestrator.js`](https://github.com/SynkraAI/aiox-core/blob/main/qa-loop-orchestrator.js)** runs the multi-stage QA workflow defined in [`qa-loop.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/qa-loop.yaml). The **[`qa-report-generator.js`](https://github.com/SynkraAI/aiox-core/blob/main/qa-report-generator.js)** emits results, and failed gates automatically spawn a [`qa-fix-issues.md`](https://github.com/SynkraAI/aiox-core/blob/main/qa-fix-issues.md) task assigned to the responsible agent, creating a closed-loop quality system.

```javascript
const { execSync } = require('child_process');

function runQaGate(storyId) {
  execSync(`npx aiox run qa-loop ${storyId}`, { stdio: 'inherit' });
}

runQaGate('STORY-42');

```

## Epic 7: Memory Layer (Cross-Session Knowledge)

**Epic 7** captures reusable code patterns, known pitfalls, and session insights across multiple runs to feed context back to LLMs for smarter suggestions.

The **[`codebase-mapper.js`](https://github.com/SynkraAI/aiox-core/blob/main/codebase-mapper.js)** builds a JSON map of the repository structure. The **[`pattern-extractor.js`](https://github.com/SynkraAI/aiox-core/blob/main/pattern-extractor.js)** pulls reusable snippets into [`.aiox/patterns/code-patterns.json`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/patterns/code-patterns.json), while **[`gotchas-documenter.js`](https://github.com/SynkraAI/aiox-core/blob/main/gotchas-documenter.js)** writes known pitfalls to [`.aiox/patterns/gotchas.json`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/patterns/gotchas.json). The **Workflow-Intelligence System (WIS)** consumes these stores to provide context-aware assistance in future sessions.

```javascript
const PatternExtractor = require('.aiox-core/infrastructure/scripts/pattern-extractor');

(async () => {
  const extractor = new PatternExtractor();
  const patterns = await extractor.extract(); // returns array of reusable code snippets
  console.log('Extracted patterns:', patterns.length);
})();

```

## How the 7 Epics Work Together

The ADE operates as a linear progression where each Epic feeds the next, creating a complete autonomous development lifecycle:

1. **Epic 1** (`WorktreeManager.create`) establishes an isolated Git worktree for the story
2. **Epic 2** (`project-status-loader`) initializes the YAML status entry for tracking
3. **Epic 3** ([`spec-pipeline.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/spec-pipeline.yaml)) runs the five spec tasks to define requirements
4. **Epic 4** (`plan-tracker` and `subtask-verifier`) generates and validates the implementation plan
5. **Epic 5** (`stuck-detector` and `rollback-manager`) monitors execution and auto-recovers from failures
6. **Epic 6** (`qa-loop-orchestrator`) enforces quality gates and iterates fixes until passing
7. **Epic 7** (`codebase-mapper` and `pattern-extractor`) captures knowledge to inform future worktrees and specs

As visualized in the architecture diagram (lines 41-69 of [`ade-architecture.md`](https://github.com/SynkraAI/aiox-core/blob/main/ade-architecture.md) in the SynkraAI/aiox-core repository), the Memory Layer closes the loop by enriching the Knowledge Base for subsequent stories, enabling continuous improvement across sessions.

## Summary

- **Epic 1** provides **Git worktree isolation** via [`worktree-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/worktree-manager.js) to prevent branch pollution
- **Epic 2** maintains **project state** in [`.aiox/project-status.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/project-status.yaml) through [`project-status-loader.js`](https://github.com/SynkraAI/aiox-core/blob/main/project-status-loader.js)
- **Epic 3** transforms requirements into specifications using the **spec-pipeline.yaml** workflow
- **Epic 4** handles **implementation planning** with [`plan-tracker.js`](https://github.com/SynkraAI/aiox-core/blob/main/plan-tracker.js) and [`subtask-verifier.js`](https://github.com/SynkraAI/aiox-core/blob/main/subtask-verifier.js)
- **Epic 5** enables **auto-recovery** through [`stuck-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/stuck-detector.js) and [`rollback-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/rollback-manager.js)
- **Epic 6** runs **iterative QA loops** via [`qa-loop-orchestrator.js`](https://github.com/SynkraAI/aiox-core/blob/main/qa-loop-orchestrator.js) until quality gates pass
- **Epic 7** builds **cross-session memory** using [`codebase-mapper.js`](https://github.com/SynkraAI/aiox-core/blob/main/codebase-mapper.js) and [`pattern-extractor.js`](https://github.com/SynkraAI/aiox-core/blob/main/pattern-extractor.js) for the Workflow-Intelligence System

## Frequently Asked Questions

### How does the ADE handle concurrent story development?

The ADE handles concurrent development through **Epic 1's Worktree Manager**, which enforces a configurable maximum number of concurrent Git worktrees. Each story receives an isolated branch (`auto-claude/<storyId>`) and worktree directory (`.aiox/worktrees/<storyId>`), allowing multiple agents to work simultaneously without merge conflicts on `main`. Stale worktrees older than 30 days are automatically tracked for cleanup.

### What triggers the Self-Healing mechanism in Epic 5?

The **Self-Healing** mechanism triggers when the [`stuck-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/stuck-detector.js) module detects repetitive error patterns—specifically when three identical errors occur within a 10-minute window. Upon detection, the system records the attempt in [`recovery-tracker.js`](https://github.com/SynkraAI/aiox-core/blob/main/recovery-tracker.js) and automatically invokes [`rollback-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/rollback-manager.js) to revert problematic changes or [`approach-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/approach-manager.js) to try alternative implementation strategies.

### How does the Memory Layer improve future development cycles?

**Epic 7's Memory Layer** improves future cycles by persistently storing reusable code patterns in [`.aiox/patterns/code-patterns.json`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/patterns/code-patterns.json) and documented pitfalls in [`.aiox/patterns/gotchas.json`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox/patterns/gotchas.json). The [`codebase-mapper.js`](https://github.com/SynkraAI/aiox-core/blob/main/codebase-mapper.js) maintains a current structural map of the repository, while the Workflow-Intelligence System (WIS) retrieves this historical context to provide LLMs with relevant examples and warnings during spec generation and implementation planning.

### Can the Spec Pipeline be customized for different agent roles?

Yes, the **Spec Pipeline** in Epic 3 is designed for role-specific customization. The [`spec-pipeline.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/spec-pipeline.yaml) workflow assigns distinct markdown tasks to dedicated agents: `@pm` handles requirements gathering, `@architect` assesses complexity, `@analyst` researches dependencies, and `@qa` critiques the final specification. Each task runs as a separate LLM invocation with role-specific prompts defined in the corresponding `.md` task files.