How It Works

ado-aw takes a markdown agent file and turns it into an Azure DevOps pipeline built around three core security stages — with optional flanking jobs that the compiler adds automatically depending on your configuration.

The three-stage pipeline model

1. Agent — The first stage runs the AI agent inside a network-isolated sandbox with a read-only Azure DevOps token. The agent can inspect code, use its approved tools, and propose actions through safe outputs.

   Importantly, the agent does not perform write actions directly.

2. Detection — The second stage reviews the agent’s proposed outputs. Its job is to detect problems such as:

   • prompt injection attempts
   • secret leakage
   • malformed or suspicious outputs
   • policy violations

   Only approved proposals continue to the next stage.

3. SafeOutputs — The third stage applies approved actions with a separate write-capable token. This stage can create or update Azure DevOps resources such as pull requests, comments, work items, and related artifacts.

   Because the write credential is isolated from the agent, the system keeps a strong boundary between reasoning and mutation.

The full pipeline shape

The three core stages are the minimum. The compiler adds optional surrounding jobs based on your configuration. The complete canonical sequence is:

Setup           (optional — setup: steps or PR-filter gate steps)
  ↓
Agent               Stage 1: run inside the network-isolated AWF sandbox
  ↓
Detection           Stage 2: threat analysis of proposed outputs
  ↓
ManualReview    (optional — when require-approval is set on a safe output)
  ↓
SafeOutputs         Stage 3: apply approved proposals with the write token
  ↓
Teardown        (optional — teardown: steps)
  ↓
Conclusion      (optional — post-run reporting; skipped on explicit cancellation)

Job	When it appears
Setup	When setup: steps are configured, or when PR-filter gate steps are generated by the compiler
ManualReview	When any safe-output tool has require-approval: true
Teardown	When teardown: steps are configured
Conclusion	When any safe-outputs: are declared — files work items for noop, missing-data, missing-tool, and pipeline failures; skipped on explicit cancellation

See the Safe Outputs reference for a full description of what the Conclusion job does and how to configure it.

Compile time vs. runtime

At compile time

When you run ado-aw compile, the compiler:

• parses the markdown body and YAML front matter
• validates the configuration
• selects the target pipeline template
• injects runtime configuration for tools, runtimes, and safe outputs
• emits Azure DevOps YAML and supporting agent assets

At runtime

When Azure DevOps executes the compiled pipeline, it:

• runs the agent with the configured tool set and permissions
• records proposed safe outputs
• analyzes those outputs for threats
• executes approved outputs with the final executor stage

Flow diagram

flowchart TD
    A["agent.md source"] --> B["ado-aw compile"]
    B --> C["Azure DevOps pipeline YAML"]
    C --> D["Stage 1: Agent"]
    D -->|"safe-output proposals"| E["Stage 2: Detection"]
    E -->|"approved proposals"| F["Stage 3: SafeOutputs"]

    style A fill:#7c3aed,color:#fff,stroke:#5b21b6
    style B fill:#6d28d9,color:#fff,stroke:#4c1d95
    style C fill:#4338ca,color:#fff,stroke:#3730a3
    style D fill:#2563eb,color:#fff,stroke:#1d4ed8
    style E fill:#d97706,color:#fff,stroke:#b45309
    style F fill:#059669,color:#fff,stroke:#047857

The key idea is that authoring happens once in markdown, compilation produces the pipeline definition, and runtime execution enforces the safety boundaries.