APEX

Agentic Platform Engineering eXperience for Azure.

This repository is the source project for a multi-agent workflow that turns Azure platform engineering requirements into deployable Bicep or Terraform with human approval gates across the lifecycle.

The full documentation for this repository lives here:

• APEX documentation
• Documentation source and publishing

APEX contains product tooling and runtime guidance. Documentation assets and publishing are maintained in apex-docs; the accelerator distributes consumer workflow templates.

This README is the general documentation entrypoint. AGENTS.md, VERSION.md, runtime references, templates and technical CLI contracts remain here because agents and validation depend on them.

Key entry points:

• Accelerator template
• MicroHack
• Contributing guide

Workflow

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
  autonumber
  participant U as User
  participant C as Orchestrator
  participant R as Requirements
  participant X as Challenger
  participant A as Architect
  participant G as Governance
  participant IaC as IaC Plan
  participant Gen as IaC Code
  participant D as Deploy
  participant W as As-Built

  Note over C: ORCHESTRATION LAYER<br/>AI prepares. Humans decide.

  U->>C: Describe infrastructure intent
  C->>R: Translate intent into structured requirements
  R-->>C: 01-requirements.md (includes iac_tool selection)
  C->>X: Challenge requirements
  X-->>C: challenge-findings-requirements.json
  C->>U: Present requirements + challenge findings

  rect rgba(255, 200, 0, 0.15)
  Note over U,C: HUMAN APPROVAL GATE
  U-->>C: Approve requirements
  end

  C->>A: Assess architecture (WAF + Cost)
  Note right of A: cost-estimate-subagent<br/>handles pricing queries
  A-->>C: 02-architecture-assessment.md + 03-des-cost-estimate.md
  C->>X: Challenge architecture
  X-->>C: challenge-findings-architecture.json
  C->>X: Independently review cost feasibility
  X-->>C: challenge-findings-cost-estimate.json
  C->>U: Present architecture + challenge findings

  rect rgba(255, 200, 0, 0.15)
  Note over U,C: HUMAN APPROVAL GATE
  U-->>C: Approve architecture
  end

  C->>G: Discover policy constraints
  G-->>C: 04-governance-constraints.json and Markdown
  C->>X: Reconcile constraints with approved architecture
  X-->>C: challenge-findings-governance-constraints-pass1.json
  C->>U: Review governance constraints and confirmations
  U-->>C: Approve governance
  C->>IaC: Create implementation plan using approved inputs
  Note right of IaC: Unified IaC Planner (05)<br/>routes based on decisions.iac_tool
  IaC-->>C: 04-implementation-plan.md
  C->>X: Challenge implementation plan
  X-->>C: challenge-findings-plan.json
  C->>U: Present plan + challenge findings

  rect rgba(255, 200, 0, 0.15)
  Note over U,C: HUMAN APPROVAL GATE
  U-->>C: Approve plan
  end

  C->>Gen: Generate IaC templates (AVM-first)
  Note right of Gen: Bicep codegen or Terraform codegen
  Gen-->>C: infra/bicep/{project} or infra/terraform/{project}

  rect rgba(0, 150, 255, 0.08)
  Note over C,Gen: Validation loop
  alt Validation passes
    C->>U: Present templates for deployment
    rect rgba(255, 200, 0, 0.15)
    Note over U,C: HUMAN APPROVAL GATE
    U-->>C: Approve for deployment
    end
  else Validation fails
    C->>Gen: Revise with feedback
  end
  end

  C->>D: Execute deployment
  Note right of D: what-if or terraform plan preview first
  D-->>C: 06-deployment-summary.md
  C->>U: Present deployment summary

  rect rgba(255, 200, 0, 0.15)
  Note over U,D: HUMAN VERIFICATION
  U-->>C: Verify deployment
  end

  C->>W: Generate workload documentation
  Note right of W: Reads prior artifacts and deployed resource state
  W-->>C: 07-*.md documentation suite
  C->>U: Present as-built docs

  Note over U,W: AI orchestrated. Human governed. Azure ready.

Loading

Start Here

For new projects, use the Accelerator template rather than cloning this repository directly.

1. Create a repository from the Accelerator template.
2. Open that repository in VS Code and reopen it in the dev container.
3. Start with the published docs: https://apexops.pro/

What This Repository Contains

• Agent definitions, skills, and instruction files for the workflow engine
• Reference implementations for Bicep and Terraform tracks
• Validation scripts, MCP configuration, and sample agent outputs
• apex-recall CLI for progressive session recall across agent-output projects
• Source content for the published documentation site

The skill catalog describes procedure ownership and invocation flags. For explicit prose cleanup, use /apex-unslop; it is manual-only, preserves technical content, and is not part of the automatic workflow. Local prompt files are adapters. On Agent Host, select the owning agent and use the shared manual entry skill; apex-host-workflow-start supports an explicit resume operation. Skills inherit the caller's model/tools and do not bypass human approval gates.

Explicit risk acceptance is supported only for authorized non-production labs, with externally verified authority, individual finding selection and separate human gate approval. Kit authoring permission never grants deployment permission; original review verdicts and unresolved findings remain intact. Maintainer and CLI contract: risk-authorizations.md.

License

MIT. See LICENSE.