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

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

// 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 module reads and writes .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.

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 → spec-assess-complexity.md → spec-research-dependencies.md → spec-write-spec.md → spec-critique.md—are orchestrated by the spec-pipeline.yaml workflow. Each task runs under a dedicated agent role (@pm, @architect, @analyst, @qa) to ensure comprehensive requirements gathering.

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 module creates a JSON plan mapping stories to subtasks and persists progress under .aiox/. The subtask-verifier.js validates each sub-task completion against its expected output and records self-critique results, ensuring accountability in the implementation phase.

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 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 records the attempt and invokes rollback-manager.js or approach-manager.js to auto-cure the pipeline without human intervention.

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 runs the multi-stage QA workflow defined in qa-loop.yaml. The qa-report-generator.js emits results, and failed gates automatically spawn a qa-fix-issues.md task assigned to the responsible agent, creating a closed-loop quality system.

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 builds a JSON map of the repository structure. The pattern-extractor.js pulls reusable snippets into .aiox/patterns/code-patterns.json, while gotchas-documenter.js writes known pitfalls to .aiox/patterns/gotchas.json. The Workflow-Intelligence System (WIS) consumes these stores to provide context-aware assistance in future sessions.

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) 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 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 to prevent branch pollution
• Epic 2 maintains project state in .aiox/project-status.yaml through 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 and subtask-verifier.js
• Epic 5 enables auto-recovery through stuck-detector.js and rollback-manager.js
• Epic 6 runs iterative QA loops via qa-loop-orchestrator.js until quality gates pass
• Epic 7 builds cross-session memory using codebase-mapper.js and 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 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 and automatically invokes rollback-manager.js to revert problematic changes or 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 and documented pitfalls in .aiox/patterns/gotchas.json. The 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 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.

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