# ACDL — Agentic Cloud Delivery Platform

Consumers declare intent; the platform delivers safe production deployment
through an agentic stack — automatically, safely, and with a complete audit
trail. A merged change progresses through lower environments end-to-end
without a platform engineer joining a thread; a non-technical consumer ships
a production deployment by declaring intent, without authoring a workflow,
a configuration file, or an infrastructure module.

## Two repositories

There are two kinds of repository in the ACDL model:

- **Platform repo (this one).** The source code of the platform. It owns
  `modules/`, `adapters/`, `core/`, `schemas/`, `pipelines/`, `scripts/`,
  and the reusable workflow files. Platform engineers work here. A consumer
  never clones it.
- **Consumer repo (yours).** A consumer repo contains only its application
  code, one or more contracts (`.acdl/contract.yml`), and one or more CI
  definitions (a thin `.github/workflows/deploy.yml` that `uses:` the central
  reusable workflow, pointing at the appropriate environment + contract).
  The consumer does not write infrastructure modules, workflow YAML, or
  adapter code.

## Documentation

| Section | Audience | What it covers |
|---------|----------|----------------|
| [Consumer Guide](consumer-guide) | Consumers | Step-by-step: create a repo, write a contract, reference the central pipeline, ship a deployment. |
| [Modules](modules/) | Consumers + platform engineers | The module catalog — primitives and modules, their inputs/outputs, and usage. |
| [Contracts](contracts/) | Consumers | The contract schema, fields, and a worked sample. |
| [Pipeline](pipeline/) | Consumers + platform engineers | The central CI + deployment pipeline and its stages. |
| [Versioning](pipeline/versioning) | Consumers + platform engineers | Module versioning + deploy-pipeline versioning (the `uses:` tag). |
| [Environments](environments/) | Consumers | Platform-managed environments and the first-run onboarding flow. |
| [Architecture](architecture) | Platform engineers | The current architecture — layers, cross-cutting concerns, the engine abstraction. |
| [Vision](vision) | All | The why — the friction the platform absorbs and the north star. |

## Features

- **Contract-driven deploys** — a consumer writes a YAML contract; the
  platform resolves it to a stack, compiles it, and deploys it.
- **Reusable versioned deploy workflow** — consumer repos `uses:` a
  versioned central workflow; no platform code is cloned by the consumer.
- **Module catalog** — primitives (single resources) and modules (patterns
  of primitives) with self-documented inputs/outputs.
- **Zero-trust credentials** — OIDC federation + attribute-based
  authorization (ABAC) by default; no long-lived keys in consumer repos.
- **Security + policy checks** — a security-check stage and a policy-check
  stage run before any infrastructure is created.
- **Confidence signal** — a computed, explainable score gates promotion.
- **Evidence outbox** — every deployment writes a hash-chained evidence
  event to an audit outbox.
- **Shell reproducibility** — `scripts/run_ci.sh` mirrors the CI pipeline
  locally; `scripts/run_platform.sh --check-only` runs offline.
- **Platform-managed environments** — consumers provide no AWS account,
  VPC, subnet, or state bucket; the platform manages environments.

## Roadmap

Planned future features (no dates; tracked in the internal roadmap):

- **Dynamic module creation from a contract** — an agentic flow where a
  consumer creates a module directly from the contract file (the "composition"
  mechanism, redesigned).
- **Compliance milestone** — per-module compliance extension points (GDPR,
  SOX, SOC2, DORA) wired into the pipeline.
- **Additional engine adapters** — beyond the Terraform adapter.
- **Environment self-service** — a consumer-facing flow to request and
  provision a new platform-managed environment.
- **HITL gates for qa / prod / dr** — human attestation + higher confidence
  thresholds for higher environments.
- **OIDC for all platform runners** — zero-trust credentials everywhere.

## Quick links

- [Consumer Guide](consumer-guide) — start here if you are a consumer.
- [Architecture](architecture) — start here if you are a platform engineer.
- The [README](https://github.com/acdl/acdl) describes the platform repo.