# How the ADE Execution Pipeline Works in aios-core: Inside the Autonomous Development Engine

> Explore the ADE execution pipeline in aios-core. Learn how it orchestrates agent activation through a tiered loading system, builds enriched context across phases, and generates context-aware greetings.

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

---

**The ADE execution pipeline orchestrates agent activation through a tiered, timeout-guarded loading system that assembles enriched context across Critical, High, and Best-effort phases before generating context-aware greetings via the `GreetingBuilder`.**

The **Autonomous Development Engine (ADE)** serves as the central orchestration "brain" of AIOS, managing how agents initialize and present themselves to users. When you activate an agent through `UnifiedActivationPipeline.activate()`, the system executes a sophisticated **ADE execution pipeline** that balances speed against data richness through strict per-tier budgets and graceful degradation strategies.

## ADE Execution Pipeline Architecture

The pipeline follows a deterministic sequence defined in `UnifiedActivationPipeline` ([`.aios-core/development/scripts/unified-activation-pipeline.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/scripts/unified-activation-pipeline.js)). The process begins by loading core configuration from [`.aios-core/core-config.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core-config.yaml), then proceeds through three distinct loader tiers, each with dedicated timeout budgets.

The central entry point is the static `activate()` method, which accepts an agent identifier and optional conversation history:

```javascript
const { UnifiedActivationPipeline } = require(
  './.aios-core/development/scripts/unified-activation-pipeline'
);

UnifiedActivationPipeline.activate('dev', {
  conversationHistory: [{ role: 'user', content: 'Add a CI pipeline' }],
});

```

## The Three-Tier Loader System

The **ADE execution pipeline** implements a tiered loading strategy where each tier has specific responsibilities and timeout constraints defined in the `LOADER_TIERS` configuration.

### Tier 1: Critical Loaders (80ms budget)

Critical loaders must succeed for meaningful agent activation. This tier loads the **AgentConfig** via `AgentConfigLoader.loadComplete()`, which defines the agent's persona, available commands, and capabilities. If this tier fails, the pipeline immediately triggers a fallback greeting.

### Tier 2: High Priority Loaders (120ms budget)

This tier executes `PermissionMode` and `GitConfigDetector` in parallel. It determines the permission badge (ask/read/write) and captures the current git branch and repository state. These loaders share the remaining budget after Tier 1 completes.

### Tier 3: Best-Effort Loaders (180ms budget)

The final tier loads `SessionContext` and `ProjectStatus` in parallel, retrieving SYNAPSE session data and parsing [`.aios/project-status.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios/project-status.yaml). This phase enriches the context with workflow history and modified files, but timeouts here only reduce greeting quality rather than blocking activation.

## Context Enrichment and Greeting Generation

After the tiered loaders complete, the pipeline assembles an **enriched context** object containing:

- Agent definition and persona
- Git status and repository state
- Project status and modified files
- Session info and conversation history
- Permission badges
- Agent memories (if the PRO module is enabled via the *memory.extended* feature gate)

This context feeds into `GreetingBuilder.buildGreeting()`, which constructs the final greeting through internal sections each guarded by 150ms timeouts.

## Timeout Management and Graceful Degradation

The **ADE execution pipeline** implements multiple timeout layers to ensure deterministic performance:

- **Global pipeline timeout**: 500ms (configurable via `AIOS_PIPELINE_TIMEOUT` environment variable or `pipeline.timeout_ms` in config)
- **Per-tier budgets**: 80ms (Critical), 120ms (High), 180ms (Best-effort)
- **Memory loader**: 500ms independent budget (if PRO module is active)

Graceful degradation follows strict rules:

- **Tier 1 failure** → immediate fallback greeting via `_generateFallbackGreeting()`
- **Lower tier timeouts** → partial quality greeting with available data
- **Global timeout** → fallback greeting after the configured limit

All errors are logged with a `[UnifiedActivationPipeline]` prefix and never thrown to the caller, guaranteeing a deterministic user experience.

## Programmatic Invocation

Developers can trigger the **ADE execution pipeline** programmatically using the static `activate` method:

```javascript
const { UnifiedActivationPipeline } = require(
  './.aios-core/development/scripts/unified-activation-pipeline'
);

// Activate the "dev" agent with optional conversation history
UnifiedActivationPipeline.activate('dev', {
  conversationHistory: [{ role: 'user', content: 'Add a CI pipeline' }],
})
  .then(({ greeting, context, duration, quality }) => {
    console.log(greeting);               // Rendered greeting
    console.log('Quality:', quality);    // full | partial | fallback
    console.log('Took ms:', duration);
  })
  .catch(console.error);

```

The CLI command `aios dev` uses [`generate-greeting.js`](https://github.com/SynkraAI/aios-core/blob/main/generate-greeting.js) as a thin wrapper around this pipeline, making the **ADE execution pipeline** accessible from both code and command line interfaces.

## Metrics Collection and Diagnostics

Every loader within the **ADE execution pipeline** records detailed metrics for observability:

```javascript
metrics.loaders[name] = {
  duration: <ms>,
  status: 'ok' | 'timeout' | 'error',
  start: <timestamp>,
  end: <timestamp>,
  error?: <msg>
};

```

The pipeline persists this data to [`/.synapse/metrics/uap-metrics.json`](https://github.com/SynkraAI/aios-core/blob/main//.synapse/metrics/uap-metrics.json) using fire-and-forget logic via `_persistUapMetrics()` (lines 334-363 of the pipeline file). Performance targets include p50 < 150ms, p95 < 250ms, and fallback rate < 5%, allowing teams to monitor **ADE execution pipeline** health in production environments.

## Summary

- The **ADE execution pipeline** centers on `UnifiedActivationPipeline` in [`.aios-core/development/scripts/unified-activation-pipeline.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/scripts/unified-activation-pipeline.js), providing a single entry point for all 12 agents.
- It implements a **three-tier loading strategy** (Critical: 80ms, High: 120ms, Best-effort: 180ms) with strict per-tier budgets and global 500ms timeout guards.
- **Graceful degradation** ensures users always receive a greeting: Tier 1 failures trigger immediate fallbacks, while lower-tier timeouts produce partial quality results.
- The pipeline generates **enriched context** combining agent definitions, git state, project status, and session data before passing it to `GreetingBuilder.buildGreeting()`.
- **Fire-and-forget side effects** write SYNAPSE session bridges (`_writeSynapseSession()`) and persist metrics (`_persistUapMetrics()`) without blocking the user experience.

## Frequently Asked Questions

### What happens if the Critical tier fails during ADE execution?

If the Critical tier (Tier 1) fails or exceeds its 80ms budget, the **ADE execution pipeline** immediately triggers `_generateFallbackGreeting()` to return a basic greeting without attempting subsequent tiers. This ensures the user receives a response even when essential configuration is unavailable, though the quality flag will be set to `'fallback'`.

### How does the ADE execution pipeline handle timeouts in lower tiers?

When High (Tier 2) or Best-effort (Tier 3) loaders timeout, the pipeline continues execution using whatever data succeeded in previous tiers. The `_determineQuality()` method inspects loader metrics to assign a `'partial'` quality rating, allowing `GreetingBuilder` to construct a degraded but functional greeting rather than failing entirely.

### Where does the ADE execution pipeline store performance metrics?

The pipeline writes detailed loader metrics to [`/.synapse/metrics/uap-metrics.json`](https://github.com/SynkraAI/aios-core/blob/main//.synapse/metrics/uap-metrics.json) via the `_persistUapMetrics()` method (lines 334-363 of [`unified-activation-pipeline.js`](https://github.com/SynkraAI/aios-core/blob/main/unified-activation-pipeline.js)). This fire-and-forget operation captures duration, status (`ok`, `timeout`, or `error`), and timestamps for each loader without blocking the greeting delivery.

### Can I customize the timeout budgets in the ADE execution pipeline?

Yes, the global pipeline timeout defaults to 500ms but can be overridden via the `AIOS_PIPELINE_TIMEOUT` environment variable or the `pipeline.timeout_ms` setting in [`.aios-core/core-config.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core-config.yaml). However, individual tier budgets (80ms/120ms/180ms) are currently hardcoded in the `LOADER_TIERS` configuration within the pipeline source.