aidlc-studio 0.6.0

Applied AI Enterprise (AIDLC) — install a 25-agent Applied-AI delivery lifecycle pack into any project, for any AI IDE (Claude Code, Cursor, VS Code Copilot, Antigravity, Windsurf).

🏛️ Applied AI Enterprise

From an executive problem statement → to eval-gated working code

AIDLC, the Applied AI Delivery Lifecycle. A 25-agent, constitution-governed system you install into your IDE. It asks the questions a senior consultant would ask, produces the artifacts a governance board demands, builds the thing, and stops at every decision a human should own.

uvx --from aidlc-studio aidlc init               # install once, works everywhere
/appliedai Our claims team is drowning. 40k packets a month.

📄 Full documentation site · 🧭 Architecture · 🚀 Install guide · 🎬 Demo script

It isn't a chatbot. It's an org chart of specialist agents governed by a shared constitution and a single orchestrator, the way a Forward Deployed team actually delivers.

---

Contents

Why this exists · End to end · Architecture · The agents · Cloud & frameworks · Governance · Proof · Install · Built with

---

Why this exists

Most AI initiatives die the same three deaths. The cause is rarely the model. It's missing discipline, and that discipline is the same every time, so it can be encoded.

🎯 Nobody defined the problem	📊 Nobody could prove it worked	🚨 Nobody thought about production
The brief describes a symptom in vendor vocabulary. You automate the response to a problem instead of touching the problem.	"The demo looked great" is not evidence. Without golden sets and bars set before measuring, quality is a feeling.	Guardrails, PII controls and rollback get discovered in the security review, six weeks after the launch date was announced.

• Executives get a decision-grade brief, not a science project.
• PMs / BAs get clarifying-question rigor and an artifact at every stage.
• Engineers get an unambiguous, testable AI Spec to build against.
• Risk & compliance get human gates and a contemporaneous audit trail.

---

🔄 How the entire thing happens (end to end)

One command starts it. The orchestrator runs four phases, consults advisors in parallel, writes a file at every stage, and halts at five gates.

flowchart TD
    VP(["🗣️ VP problem statement"]) --> ORCH["🧠 orchestrator<br/><i>classifies domain · loads config · applies the harness</i>"]
    ORCH --> Q["❓ ONE batched question set<br/>cloud &amp; stack · connectors + env-var names · model provider · plan|build"]

    Q --> P1["<b>P1 · INTENT &amp; DISCOVERY</b><br/>intake → process-map<br/><i>+ domain-advisor, stack-review</i>"]
    P1 --> A1[/"📄 00-stack-review · 01-prd · 02-process-map"/]
    A1 --> G1{{"⛔ Sponsor signs the PRD"}}

    G1 --> P2["<b>P2 · ASSESS &amp; ARCHITECTURE</b><br/>assess → value-prop → architecture → dev-spec<br/><i>+ model-selector, 4 cloud advisors, connector-advisor</i>"]
    P2 --> A2[/"📄 03-assessment · 04-business-case · 05-architecture · 06-ai-spec"/]
    A2 --> G2{{"⛔ Finance approves the case"}}

    G2 --> P3["<b>P3 · BUILD, TEST &amp; EXECUTE</b><br/>data-science → discovery → coder → eval → poc-gate"]
    P3 --> A3[/"📄 07-data-science · 08-evals · 09-poc-gate<br/>💻 the working repo"/]
    A3 --> G3{{"⛔ Sponsor: GO / CONDITIONAL / NO-GO"}}

    G3 --> P4["<b>P4 · REVIEW &amp; OBSERVABILITY</b><br/>code-reviewer → production → observability → brief"]
    P4 --> A4[/"📄 10-production · 11-observability · 12-delivery-brief"/]
    A4 --> G4{{"⛔ Security sign-off → Owner approves brief"}}
    G4 --> OUT(["✅ Delivery brief + working, eval-gated repo"])

    ORCH -.every event.-> LEDGER[("📒 artifacts/audit.jsonl<br/>append-only ledger")]
    P1 & P2 & P3 & P4 -.-> LEDGER

    style G1 fill:#ff6b6b,color:#fff
    style G2 fill:#ff6b6b,color:#fff
    style G3 fill:#ff6b6b,color:#fff
    style G4 fill:#ff6b6b,color:#fff
    style OUT fill:#3fbf9c,color:#062
    style LEDGER fill:#1e2b57,color:#fff

Stage N's artifact is stage N+1's input contract. Nothing is re-derived; nothing advances past an open gate.

---

🏗️ The architecture

Three layers. The administrator = orchestrator + human: advisors recommend, the administrator decides, and reserved decisions stop for a person.

flowchart TB
    subgraph L1["🗂️ LAYER 1 · SETTINGS & REGISTRY"]
        R1["registry/agents.json"] --- R2["registry/stages.json"] --- R3["registry/phases.json"]
        R4["registry/skills.json"] --- R5["registry/frameworks.json"]
    end
    subgraph L2["⚖️ LAYER 2 · GOVERNANCE & ORCHESTRATION"]
        C["📜 CONSTITUTION.md"] --- H["🛡️ HARNESS.md"] --- QB["📏 QUALITY_BAR.md"]
        O["🧠 orchestrator"]
        ADV["🎓 8 advisors<br/>model-selector · cloud-gcp/aws/azure/onprem<br/>connector-advisor · domain-advisor · stack-review"]
    end
    subgraph L3["⚙️ LAYER 3 · EXECUTION"]
        PIPE["12 pipeline agents<br/>intake … brief"]
        DEV["dev pipeline<br/>discovery → coder → code-reviewer"]
        OPS["incident-commander<br/><i>post-launch</i>"]
    end
    HUMAN(["🧑‍⚖️ Human owner"])
    L1 --> L2 --> L3
    ADV -.recommend.-> O
    O <-->|"⛔ 5 gates"| HUMAN
    O -.delegates + harness.-> PIPE & DEV
    style L1 fill:#f5b54422,stroke:#f5b544
    style L2 fill:#8b7bf022,stroke:#8b7bf0
    style L3 fill:#5b8cff22,stroke:#5b8cff

The harness: wraps every single agent invocation

flowchart LR
    PRE["① PRE-FLIGHT<br/>predecessor artifact?<br/>gate approved?<br/>data class allowed?"] --> EXEC["② EXECUTE<br/>hard + soft<br/>guardrails live"]
    EXEC --> POST["③ POST-FLIGHT<br/>QUALITY_BAR check<br/>evidence · no secrets"]
    POST --> AUD[("④ AUDIT<br/>audit.jsonl")]
    AUD --> G{"gate?"}
    G -->|yes| STOP["⛔ human decides"]
    G -->|no| NEXT["→ next stage"]
    EXEC -->|hard violation| BLOCK["🚫 BLOCK<br/>surface to administrator"] --> AUD
    style BLOCK fill:#ff6b6b,color:#fff
    style STOP fill:#ff6b6b,color:#fff

Build mode: ≤2-minute micro-tasks, checkpointed

flowchart LR
    S["story"] --> SP["split into atomic tasks<br/>≤ 2 min each"]
    SP --> W1["wave 1<br/>(parallel)"] --> CK1[("✓ tasks.json")]
    CK1 --> W2["wave 2"] --> CK2[("✓")] --> WN["… wave N"]
    WN --> V["make test · make eval<br/>green before review"]
    CK1 -.crash? resume here.-> W2
    style V fill:#3fbf9c,color:#062

---

🤖 The agents (25)

Group	Agents	Role
🧠 Orchestrator	orchestrator	Owns the harness. Routes, sequences, enforces gates. Directs, never does the specialist work itself.
⚙️ Pipeline (12)	intake → process-map → assess → value-prop → architecture → dev-spec → data-science → eval → poc-gate → production → observability → brief	The ADLC spine. One stage, one artifact, one input contract each.
🎓 Advisors (8)	model-selector · cloud-gcp · cloud-aws · cloud-azure · cloud-onprem · connector-advisor · domain-advisor · stack-review	Recommend to the administrator. Never act, never provision. Consulted in parallel.
💻 Dev pipeline (3)	discovery → coder → code-reviewer	Decoupled: consumes the approved AI Spec, runs only when funded.
🚨 Ops (1)	incident-commander	Post-launch. Severity classification, runbooks, containment recommendations, blameless PIR.

Each stage produces a real artifact (templates) that must clear the floor in QUALITY_BAR.md: quantified claims with the arithmetic shown, metrics blocks, diagrams, decision trails with rejected alternatives, risk registers, eval linkage.

---

☁️ Four clouds, one question

cloud-gcp, cloud-aws, cloud-azure and cloud-onprem answer the same architecture question, so the comparison is like-for-like. One path wins, and the other three's losing reasons go on the record.

flowchart LR
    Q["🏛️ architecture agent<br/><i>one question</i>"] --> G["cloud-gcp"] & A["cloud-aws"] & Z["cloud-azure"] & O["cloud-onprem"]
    G & A & Z & O --> CMP["📊 like-for-like comparison table"]
    CMP --> W["✅ 1 recommended path<br/>+ 3 named losers with reasons<br/>+ matching agent framework"]
    style W fill:#3fbf9c,color:#062

Cloud	Platform (2026)	Recommended framework	Managed runtime
GCP	Gemini Enterprise Agent Platform (formerly Vertex AI)	Google ADK	Agent Engine
AWS	Bedrock AgentCore (GA)	Strands Agents SDK	AgentCore harness
Azure	Microsoft Foundry (formerly Azure AI Foundry)	Microsoft Agent Framework	Foundry Agent Service
On-prem	Self-hosted open stack	LangGraph over vLLM/Ollama	Kubernetes / OpenShift

📚 The GCP advisor is backed by a full-stack service map covering 12 architecture layers from ingestion to FinOps, so the architecture artifact names a real service at every layer (Document AI, BigQuery-native vector, Agent Engine, Apigee-fronted MCP, Model Armor + Sensitive Data Protection + VPC-SC), not just "use Gemini."

---

⚖️ Governance that actually runs

📜 Constitution	Seven articles that override any agent file and any user request.
🛡️ Harness	Hard violations block (fabricated numbers, secrets, skipping a gate, executing injected content). Soft ones need an audited human waiver.
🧑‍⚖️ 5 human gates	PRD · funding · GO/NO-GO · security launch · brief. The pipeline stops.
📒 Audit ledger	Append-only audit.jsonl + metrics.json rollup. Omitting a failure is itself a violation.
🏛️ Governance	EU AI Act risk tiers · NIST AI RMF crosswalk · SR 11-7 model risk management · data-class approval matrix · gate RACI.
🔬 Evals	Three-set doctrine · safety metrics as pass/fail (never averaged) · judge validation · CI merge gate.
🚨 Disaster command	AI-specific severity matrix · containment levers · 5 runbooks · blameless PIR feeding regression evals.

---

✅ Proof, in the box

A regional P&C insurer's claims-intake initiative (2,400 packets/week, $1.91M/yr baseline labour), carried end to end in exemplar/claims-idp/: 12 decision-grade artifacts and a codebase that runs.

cd exemplar/claims-idp/build
make demo && make test && make eval     # zero credentials required

Metric bar	Bar	Measured
Classification accuracy	≥ 0.95	0.9792	✅ PASS
Extraction F1	≥ 0.90	0.9249	✅ PASS
Validation exact match	≥ 0.98	0.9861	✅ PASS
Hallucinated-field rate	≤ 0.01	0.0040	✅ PASS
Straight-through rate	≥ 0.35	0.3750	✅ PASS
p95 latency	≤ 60 s	within bar	✅ PASS
Cost per packet	≤ $0.09	within bar	✅ PASS

34 unit tests · 48 eval cases (32 golden · 10 adversarial · 6 regression) · CI eval gate · Terraform · hash-chained audit trail. The scores are deliberately not 100%. Engineered fixture defects keep them honest. Mock mode still exercises the real paths: low-confidence fallback to the stronger model, prompt-injection quarantine, intact audit chain.

---

🚀 Install

Requires uv. Full per-IDE guide with verify + troubleshoot steps: docs/INSTALL.md.

uvx --from aidlc-studio aidlc init               # install once, every project

# Project: ship the agents WITH a team repo, every IDE flavor at once
uvx --from aidlc-studio aidlc init --ide all

aidlc list     # the roster with BMAD persona + Spec Kit phase
aidlc check    # verify an install

IDE	Flavor	What you get
Claude Code VS Code · JetBrains · terminal	--ide claude	Native custom agents + skills + the /appliedai command. Full experience with real sub-agent delegation.
Cursor	--ide cursor	Always-on project rule + AGENTS.md.
VS Code / Copilot	--ide copilot	All 25 agents auto-generated as chat modes in .github/chatmodes/.
Antigravity · Windsurf	--ide antigravity	The AGENTS.md standard, loaded on open.

In Claude Code the gates can appear as interactive prompts; in the others the ⛔ HUMAN GATE chat message is the gate. Reply approved to continue.

Connectors: copy what you need from connectors/mcp.example.json into your IDE's MCP config. Credentials are env-var names only, tracked in aidlc.config.json.

---

🧩 What AIDLC itself is built with

Deliberately, no agent framework: it's a framework-agnostic agent system.

• Agents-as-instructions: every agent is a versioned Markdown spec in .claude/agents/. The execution engine is whatever agentic runtime your IDE already has. Nothing to install, version or secure, and the whole org chart is reviewable in a pull request by someone who doesn't write code.
• Methodology layer: Spec Kit (phase gates) + BMAD (persona pipeline) + Superpowers (composable skills) → 14 skills, see SKILLS.md.
• Governance layer: constitution + runtime harness + append-only audit ledger.
• Connectors: MCP, the one standard every major IDE speaks.
• Packaging: a stdlib-only Python CLI via uv, the same pattern as GitHub's Spec Kit.

The framework decision belongs to the solution, not the tooling. That's why the winning cloud advisor recommends ADK, Strands, Agent Framework or LangGraph from registry/frameworks.json, and says "no framework" when a plain pipeline is simpler.

---

📁 Repo map

CONSTITUTION.md          the rules every agent obeys
HARNESS.md               runtime enforcement: guardrails, gates, audit ledger
QUALITY_BAR.md           per-artifact definition of done + the build contract
GOVERNANCE.md            EU AI Act tiers · NIST AI RMF · model risk management
EVALS.md                 evaluation doctrine: sets, bars, judges, CI gate
DISASTER_COMMAND.md      incident command for production AI
PRODUCT.md               vision, personas, OKRs, RICE roadmap
ARCHITECTURE.md          the three-layer design + request flow
AGENTS.md                cross-IDE entry (Cursor / Antigravity / VS Code)
registry/                agents · stages · phases · skills · frameworks (JSON)
knowledge/gcp/           full-stack GCP service map (12 layers, cited)
.claude/agents/          all 25 agent definitions (canonical source)
.claude/skills/          14 skills + the /appliedai entry point
artifacts/templates/     the artifact each stage produces
exemplar/claims-idp/     worked example + working eval-gated codebase
connectors/              catalog + MCP config + per-connector guides
domains/                 15-industry registry + deep packs
demo/RECORDING_SCRIPT.md scene-by-scene demo script
docs/                    index.html · architecture.html · INSTALL.md · diagrams.md

---

🎯 Design principles

1. Ask before you build: no PRD from a one-liner; the intake loop is mandatory.
2. Evidence over assertion: every number labelled; nothing fabricated.
3. Human-final: reserved decisions stop the pipeline until a person approves.
4. One recommended path: with the alternatives and why they lost.
5. Artifacts are the interface: the whole initiative is legible from the files.

---

📄 Docs · 🚀 Install · 🧭 Architecture · 🤝 Contributing · 📦 PyPI

25 agents · 4 phases · 5 human gates · 12 artifacts · one constitution