AIDLC Implementation Examples

Pick the Example Closest to You

The examples build on each other. Most organizations start with the first, add the second, and only build the third when several teams need the same controls. The fourth applies whenever the product itself calls a model. The architecture behind all four is on Building AIDLC Into an AI Engine.

Example 1: A Team on a CLI Coding Agent

The lightest integration. The engine is the coding agent the team already uses, and the method lives in four files it reads or runs. Nothing new to deploy; everything is reviewed in pull requests like any other code.

# AGENTS.md - AIDLC rules for this repository

## How work arrives
- Every task comes from a ticket contract: acceptance criteria, risk tier, flag, rollback plan.
- No ticket contract, no code. Ask for one instead of guessing.

## Develop: tests first
1. Propose a plan: files, interfaces, test surface, rollback. Wait for approval.
2. Write tests from the acceptance criteria: unit for logic, integration or contract
   for every module boundary and external system the ticket names. Run them. They must fail.
3. Implement until they pass. Never edit, skip or delete an existing test to get green.
4. Run the full suite and the linter before showing the diff.

## Risk tiers
- Tier 1 (docs, copy, tests, flag-off scaffolding, safe dependency bumps): merges on green checks; a person samples merges.
- Tier 2 (ordinary feature work behind a flag): plan approval first; one human reviewer.
- Tier 3 (auth, money and eligibility logic, personal data, migrations, rule engines,
  external adapters, infrastructure): never unattended; two humans plus an architect review.

## Never
- Push to a protected branch, change CI configuration, or read secrets.
- Retry a failing check more than twice. Stop and report what you tried.

#!/usr/bin/env bash
# block-test-edits.sh - run by the agent before it edits a file.
# How the target path arrives differs by tool (an argument, an environment
# variable or JSON on stdin); adapt the next line to yours.
target="$1"

# New test files are welcome. Existing ones change only with a human-approved reason.
if [[ "$target" == tests/* ]] && git ls-files --error-unmatch "$target" >/dev/null 2>&1; then
  echo "Blocked: $target is an existing test. Add a new test or ask a person." >&2
  exit 2
fi
exit 0

Example 2: An Agent in the CI Pipeline

The next step moves the controls from the developer's laptop into the pipeline, where they apply to every pull request no matter who or what wrote it. It also opens Lane B: an issue labeled agent-eligible starts an agent under its own service identity, which opens a pull request and can never merge one. See the two lanes and work classes for which tickets qualify.

The workflow below is GitHub Actions syntax; the same steps translate to any CI runner. Each scripts/aidlc/ script is small and owned by the team, so the gate logic stays readable and reviewable.

# .github/workflows/aidlc-gates.yml - illustrative
name: aidlc-gates
on: pull_request
permissions:
  contents: read
  pull-requests: read
jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Ticket contract linked and complete
        run: ./scripts/aidlc/check-ticket-contract.sh
      - name: Tests came first and existing tests are untouched
        run: ./scripts/aidlc/check-tests-first.sh "origin/$GITHUB_BASE_REF"
      - name: Test suite
        run: npm test
      - name: Mutation gate on critical modules
        run: ./scripts/aidlc/mutation-gate.sh        # runs only when critical paths changed
      - name: Reviewers required for the risk tier
        run: ./scripts/aidlc/require-reviewers.sh

#!/usr/bin/env bash
# check-tests-first.sh - fail when existing tests were modified or deleted.
set -euo pipefail
base="$1"

changed=$(git diff --name-only --diff-filter=MD "$base"...HEAD -- tests/)
if [ -n "$changed" ]; then
  echo "Existing tests were modified or deleted:"
  echo "$changed"
  echo "Add the label tests-change-approved after a person reviews the reason."
  exit 1
fi

Example 3: An In-House Orchestrator on a Model API

When several teams need the same controls, or the work spans more than code, an organization builds its own engine: a service that owns the phase state machine and the artifact store, calls a model API for each agent role, and gives agents tools through MCP servers. People approve in the tracker or in chat, and the approval event drives the next transition.

This is the full seven-layer architecture. Three pieces are worth showing concretely: the data model, the tool surface, and the routing of agents to phases.

-- Illustrative schema: every version is kept, and approvals live apart from content.
CREATE TABLE artifact (
    id           TEXT      NOT NULL,   -- e.g. BILL-412
    kind         TEXT      NOT NULL,   -- brief | spec | ticket_contract | plan | pull_request | release_plan | runbook
    version      INTEGER   NOT NULL,
    phase        TEXT      NOT NULL,   -- analyze | ideate | develop | launch | curate
    body         JSON      NOT NULL,
    authored_by  TEXT      NOT NULL,   -- a person's id or an agent identity
    created_at   TIMESTAMP NOT NULL,
    PRIMARY KEY (id, kind, version)
);

CREATE TABLE approval (
    artifact_id  TEXT      NOT NULL,
    kind         TEXT      NOT NULL,
    version      INTEGER   NOT NULL,
    role         TEXT      NOT NULL,   -- product_owner | tech_lead | reviewer | release_owner
    approved_by  TEXT      NOT NULL,   -- always a person; the engine rejects agent identities here
    approved_at  TIMESTAMP NOT NULL
);

CREATE TABLE agent_run (
    run_id       TEXT      PRIMARY KEY,
    artifact_id  TEXT      NOT NULL,
    phase        TEXT      NOT NULL,
    agent        TEXT      NOT NULL,   -- versioned agent definition
    model        TEXT      NOT NULL,   -- pinned model identifier
    input_tokens  INTEGER,
    output_tokens INTEGER,
    gate_result  TEXT,                 -- passed, or failed with reasons
    started_at   TIMESTAMP NOT NULL
);

# agents.yaml - illustrative; one versioned definition per phase role
analyze:
  agent: research-agent
  tools: [tracker.read, docs.read]
  writes: brief
ideate:
  agent: design-agent
  tools: [tracker.read, docs.read]
  writes: [design_note, adr, contract, spec]
develop:
  agent: coding-agent
  tools: [tracker.read, docs.read, repo.read, repo.open_pull_request, ci.read]
  writes: [plan, tests, pull_request]
  sandbox: worktree
launch:
  agent: release-agent
  tools: [repo.read, repo.open_pull_request, ci.read]
  writes: [assurance_report, gap_tests, release_plan]   # a failing gap test returns to develop
curate:
  agent: monitoring-agent
  tools: [telemetry.read, repo.read, ci.read]
  writes: [incident_review, rule_pull_request]

defaults:
  model: pinned            # each definition names an exact model identifier, changed only with evals
  max_repair_attempts: 2
  budget: per_run_cap

Example 4: A Team Whose Product Is the AI Engine

Here the engine is what ships: an invented support-triage assistant that reads a customer message, classifies it and drafts a reply. Coding agents may still write the application code under Examples 1 and 2. The model's own behavior is governed by evals, written before any prompt or model change, exactly as tests are written before code.

{"id": "triage-001", "input": "I was charged twice for order 5521", "expect": {"intent": "billing_refund", "must_mention": ["order 5521"], "must_not": ["promise a refund amount"]}, "blocking": true}
{"id": "triage-002", "input": "Close my account and delete my data", "expect": {"intent": "account_closure", "route_to_human": true}, "blocking": true}
{"id": "triage-003", "input": "How do I export invoices?", "expect": {"intent": "how_to", "must_cite": "help-center"}, "blocking": false}

# triage.config.yaml - illustrative
model: <exact pinned model identifier>
prompt: prompts/triage.md            # versioned in the repository
retrieval:
  index: help-center
  results: 5
eval_gate:
  suite: evals/triage.jsonl
  blocking_cases: all_must_pass
  other_cases: no_regression_vs_main
rollback: previous_config_tag

More on the seam between the two lifecycles: AIDLC vs the ML Lifecycle and evals in Engineering Practices.

Related Pages