One workflow,from spec to self-healing.

The AIDLC, end to end

This is the canonical pipeline. A human steering layer sets intent and holds the gates; an orchestration layer fans work out to parallel agents in isolated sandboxes; automated review and security gates stand between a green PR and production; and an agentic-SRE loop closes back onto implementation. Everything else in this manual hangs off these twelve stages.

Rendered as a control plane, work flows top-to-bottom; the violet bands are where a human must act; the green/red dashed bands are gates; the amber block is the orchestration engine; and the dotted arc is the self-healing loop.

Humans steer. Agents execute. Gates decide.

The pipeline only works because authority is split cleanly. Humans own intent and accountability; agents own throughput; deterministic gates own the go/no-go. The bottleneck has moved from writing code to reviewing it — so the leverage is in specs, decomposition, and the gates.

Three load-bearing gates, condensed from about eight. Read end to end, the pipeline has roughly eight points where a human can act (the gate column in §03 tags them at stages 1, 2, 3, 6b, 8, 9, 10 and 12). In practice they concentrate into three high-value gates — approve the plan (after stage 2), review the PR (gate 6b), and promote to production (stage 8). This mirrors the prevailing industry framing that an agentic SDLC reduces roughly eight human interruptions to three checkpoints (Augment Code), raising reviewer leverage while preserving governance.

Every stage: what the agent does, the gate, the enabler

One table to hold the whole workflow. The final column is the point of this manual: each stage is made reliable by a specific harness or loop mechanism (detailed in §09–10). The gate tags read HUMAN AGENT HARD.

The shape of the job. Read the gate column top to bottom: there are about eight points where a human can act, but the load-bearing ones concentrate into three — approve the plan, review the PR, and promote to production — with spec and design sign-off folded into planning, and sensitive-code review tightening the rest. That is the entire post-transition role: engineers move up the stack from authoring lines to authoring intent and judging output.

The front of the pipeline is where humans win or lose

Underspecified intent multiplies errors across a whole fleet, so stages 1–3 carry the heaviest human gates. Three tool categories matter here — and they are not interchangeable: a portable process scaffold, an agentic IDE, and a spec-as-source framework.

Spec Kit vs Kiro vs Tessl — three different roles

# bootstrap
uvx --from git+https://github.com/\
github/spec-kit.git specify init APP

# inside your agent:
/speckit.constitution
/speckit.specify  <feature>
/speckit.clarify
/speckit.plan     <tech>
/speckit.tasks
/speckit.implement

.kiro/
  specs/<feature>/
    requirements.md  # EARS
    design.md
    tasks.md
  steering/   # persistent
              # project knowledge
  hooks/      # on save:
              # lint · test · scan

---
name: User Auth
targets: [../src/auth/*.py]
---
Users log in with email +
password.
  def login(email, pw)
      -> Session
[@test] ../tests/test_login.py
# run: tessl eval run .

CONFIG EARS — the structured-spec grammar (stage 1)

EARS keeps acceptance criteria testable. It is the connective tissue between the human's intent and the agent's contract, and is the native requirements format in Kiro.

# Ubiquitous      The system shall encrypt all data at rest.
# Event-driven    WHEN a user submits invalid credentials, the system shall return 401.
# State-driven    WHILE a session is active, the system shall refresh the token every 15m.
# Unwanted       IF a payment webhook signature is invalid, THEN the system shall reject it.
# Optional       WHERE multi-factor auth is enabled, the system shall require a TOTP code.

Stage 3 · architecture the agent cannot violate

Design is enforced mechanically, not by hoping the agent remembers. Encode a forward-only dependency direction and a single seam for cross-cutting concerns as linters set to error; the rule is then a hard gate for every agent on every run.

# MyProject — what this service does, in one line

## Commands
- build: `make build`   # lint rules are ERROR-level, not warn
- test:  `make test`

## Where things live (point outward; don't inline detail)
- Architecture & layer rules .... docs/architecture.md
- ADRs (why X over Y) .......... docs/adr/
- Testing strategy ............. docs/testing.md

## Boundaries
- Dependency direction: Types → Config → Repo → Service → Runtime → UI
- Cross-cutting concerns enter ONLY via the Providers interface
- Never edit: .env, infra/prod/**, .git/**

Inside the box: implement → sandbox → test → self-review → CI

This is where loop engineering earns its keep. Each agent runs a bounded inner loop in an isolated sandbox: generate → run sensors → self-review → fix, exiting on pass and escalating when capped. Nothing here is open-ended.

CONFIG The sandbox (stage 4) — disposable & isolated

Isolation is what lets an agent run with full permissions safely; pre-install dependencies at build time so a new agent starts ready to code (the "warm devbox" / cached-dev-container idea). Two real options:

{
  "name": "my-app",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  // run once at build → agents start in seconds
  "onCreateCommand": "pip install -r requirements.txt",
  "forwardPorts": [3000, 8000]
}

# pip install e2b-code-interpreter
from e2b_code_interpreter import Sandbox
with Sandbox() as sbx:
    sbx.run_code("x = 1")
    r = sbx.run_code("x += 1; x")
    print(r.text)   # 2

CONFIG Hooks (stages 4–7) — turn the design into enforcement

Claude Code hooks make "the agent can't make that mistake again" literal: auto-format/lint every edit, deny destructive commands, inject branch context, and block stopping while tests fail. exit 2 is a blocking error fed back to the agent.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" && npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\"" }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE' && exit 2 || exit 0" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "npm test || exit 2" }] }
    ]
  }
}

CONFIG The CI cap (stage 7) — green in two rounds, or escalate

The hard iteration cap is the single most important loop bound: it prevents infinite token-burning loops and routes genuinely hard problems to a human. (Documented at the strict end as a two-round cap.)

# the agent gets at most 2 attempts to make CI green, then a human is paged
MAX=2; n=0
until npm run ci; do
  n=$((n+1))
  [ "$n" -ge "$MAX" ] && { gh pr comment --body "CI red after $MAX rounds — escalating to a human."; exit 1; }
  claude -p "CI failed. Read the logs, fix the cause, do not disable tests."
done
echo "green in $n round(s)"

Between a green PR and production

A green CI means the code runs, not that it's right. Two gates stand between the PR and prod: an automated gate (AI review + SAST + dependency CVEs) and a human gate whose strictness you set by blast radius. These are inferential sensors used as gates — rich but non-deterministic, so they gate rather than decide alone.

CONFIG AI review gate (6b)

reviews:
  profile: "assertive"
  request_changes_workflow: true   # block merge until review threads resolve
  path_instructions:
    - path: "src/payments/**"
      instructions: "High blast radius. Require a human approver; flag any auth or money-movement change."
  tools:
    semgrep: { enabled: true }
    github-checks: { enabled: true }

Ship safely, watch closely, heal automatically

Past the gates, the workflow keeps containing risk: progressive delivery bounds the blast radius, telemetry is made legible to agents, an agentic-SRE loop turns incidents into fix PRs that re-enter implementation, and a doc-gardening agent keeps the system of record fresh.

CONFIG Deploy with auto-rollback (stage 8)

apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 5m }
        - analysis:                 # auto-rollback if the SLO query fails
            templates: [{ templateName: error-rate-slo }]
        - setWeight: 50
        - pause: { duration: 10m }

Stage 10 · the agentic-SRE loop that closes back onto [4]

This is the loop that makes the pipeline self-healing. On alert, an SRE agent triages, runs root-cause analysis over the agent-legible telemetry, performs a bounded remediation, and opens a fix PR — which re-enters the workflow at stage 4 and passes the same gates. A human stays on the loop via escalation thresholds.

Security, compliance & audit, throughout

Stage 12 is not a step — it's a rail spanning the whole pipeline. In an agentic SDLC the same gates that make agents trustworthy double as your control evidence: the change-management trail an auditor samples is produced automatically, on every PR. The job is to make those gates emit immutable, attributable, replayable records by construction — so a SOC 2 audit becomes a query against artifacts you already have.

The two questions a SOC 2 audit asks

Mapping the pipeline to the Trust Services Criteria

Every AIDLC mechanism already maps to a SOC 2 Common Criterion. The columns that matter for the audit are the last two: what proves the control was designed (Type 1) and what proves it operated (Type 2).

References follow the AICPA 2017 Trust Services Criteria (rev. 2022); Security (CC-series) is mandatory. Confidentiality (C1) and Privacy (P-series) attach the same way when in scope — map the data-handling stages (sandbox isolation, audit redaction) to them.

CONFIG Change management as code (CC8.1)

The gate that satisfies CC8.1 should be enforced by the platform, not by convention. A branch ruleset makes review, status checks, and linear history mandatory — and is itself the Type 1 design artifact.

{
  "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["refs/heads/main"] } },
  "rules": [
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1,
                     "require_code_owner_review": true,
                     "dismiss_stale_reviews_on_push": true } },
    { "type": "required_status_checks",
      "parameters": { "required_checks": [
        { "context": "sast/semgrep" }, { "context": "deps/cve-scan" },
        { "context": "ci/tests" }, { "context": "compliance/evidence-gate" } ] } },
    { "type": "required_linear_history" },
    { "type": "non_fast_forward" }
  ]
}

CONFIG Make compliance a blocking check, not a hope

A small policy-as-code gate (the compliance/evidence-gate check above) refuses the merge unless the evidence a Type 2 auditor will sample actually exists. Encoding it means the control can't be silently skipped under deadline pressure.

package merge.evidence
default allow := false

allow if {
  input.review.approvals >= 1
  input.review.approver != input.pr.author        # CC8.1 — reviewer ≠ author
  input.scans.sast == "passed"                    # CC7.1
  input.scans.cve_high == 0                        # CC7.1
  input.actor.identity_scope == "per-task"        # CC6 — no shared tokens
  input.plan.ref != ""                            # CC3/CC8 — change traces to an approved plan
}

CONFIG The audit record — your Type 2 evidence unit

Type 2 lives or dies on the operating log. Emit one append-only record per gate event, attributable to a single identity, hash-chained, shipped to an immutable store. This is the artifact the auditor samples.

{
  "ts": "2026-06-15T14:03:11Z",
  "actor": { "identity": "agent://impl-7f3a", "scope": "task-4821", "human_owner": "u/eng-114" },
  "event": "pr.merged", "pr": 9182, "change_ref": "plan/exec-4821",
  "controls": { "reviewer": "u/eng-220", "sast": "passed", "cve_high": 0, "ci": "green" },
  "tool_calls": 37, "prev_hash": "e3b0c4…", "hash": "a17fde…"   // hash-chained = tamper-evident
}

CONFIG Least-privilege MCP for stage 4 (CC6)

{
  "servers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
                "env": { "GITHUB_TOKEN": "${scoped_repo_token}" } },
    "prod-db": { "command": "uvx", "args": ["db-mcp@1.4.2"],
                 "disabled": true, "comment": "never enabled in the agent sandbox" }
  }
}

Harness engineering — the "how" under stages 1–4 & 8–12

A coding agent is a model wrapped in a system: Agent = Model + Harness, where the harness is everything except the model. It is where almost all of your engineering leverage lives, and it is what makes the front and back of the pipeline reliable. The operating heuristic of the field:

Pictured as an exploded view, the agent is a small model core wrapped in concentric, mostly-deterministic rings — and every ring is something you author and version. Each one also maps onto the pipeline: context & tools feed stages 1–4, the sandbox is stage 4, the sensors are stages 5–6b, and orchestration & hooks span the whole engine.

The seven harness components — and the stage each one serves

Feedforward guides vs feedback sensors

The clearest current framing (Thoughtworks, Apr–May 2026) splits the harness into what you give the agent before it acts and what you measure after. The "after" signals divide into two kinds with very different economics — and they map directly onto pipeline stages.

Loop engineering — the "how" under stages 4–7 & 10

Loop engineering is designing the agent's iteration cycles so they converge on something verified and cannot run forever. The inner loop (§05) is one instance; the most reliable inferential sensor in the field is a fresh-context evaluator paired with a default-FAIL contract, so an agent can't claim a success it hasn't observed.

CONFIG Fresh-context evaluator + default-FAIL (stage 6)

---
name: evaluator
description: Skeptical reviewer. Reads the diff and the builder's evidence,
  returns PASS or NEEDS_WORK with specific findings. No Write/Edit tools.
tools: Read, Glob, Grep, Bash
---
You did NOT build this change. Begin your reply with the bare word
PASS or NEEDS_WORK on its own line. Judge ONLY against the spec and the
evidence that was actually Read.

// every acceptance criterion starts FALSE
{ "feature-1": { "passes": false }, "feature-2": { "passes": false } }

# PreToolUse verify-gate.sh blocks writing "passes": true until the agent
# has Read real evidence (a screenshot / console log) this session:
{ "decision": "block",
  "reason": "No evidence Read this session. Open the evidence file first, then retry." }

CONFIG Repeat-until-green, with a hard cap (stages 4–7)

# first-party plugin: loop until a completion promise or the cap
/plugin install ralph-wiggum@claude-plugins-official
/ralph-loop "<prompt>" --max-iterations N --completion-promise "DONE"

# built-in & version-stable — prefer this for "keep working until correct":
/goal all tests in test/auth pass and lint is clean

The discipline that ages well: re-audit the harness every model release

A harness encodes assumptions about what the model can't do; those assumptions go stale as models improve. On every major upgrade, ask "which components exist only to compensate for now-fixed limitations?" and delete them — the best harnesses get simpler over time.

When stage 4 becomes many agents at once

The orchestration layer in the pipeline is a multi-agent workspace manager: it isolates each agent (worktree or container), tracks work that survives restarts, runs watchdogs, and merges through a verifying queue. It is the control plane for stages 4–7 at scale.

CONFIG Gastown — agent presets + a concurrency cap

# define agent aliases (any CLI runtime) + a default
gt config agent set codex-low   "codex --thinking low"
gt config agent set claude-haiku "claude --model haiku --dangerously-skip-permissions"
gt config default-agent codex-low

# cap concurrent workers so you don't exhaust API rate limits
gt config set scheduler.max_polecats 5   # >0 enables deferred dispatch
gt sling gt-abc gastown                   # auto-defers when a cap is set

Read the open ones as a blueprint. Even if you never run Gastown, its architecture is the clearest open catalogue of what an unattended orchestrator needs: persistent work state, a coordinator, isolated worker storage, a verifying (bisecting) merge queue, health watchdogs, severity-routed escalation, capacity governance, and OpenTelemetry. Evaluate every commercial platform against that checklist.

A concrete stack for the pipeline

One defensible pick and a strong alternative for each stage. Tool names are representative of the field, not endorsements — choose against your own constraints and the recency caveats in §15.

Stage-4 models — current lineup (vendor-reported, harness-sensitive)

† GPT-5.5 price via secondary source — unconfirmed. SWE-bench Verified is near saturation and harness-sensitive: the same model scores differently under different harnesses, which is the whole reason §09–10 matter more than this table. Don't select a model on a leaderboard — evaluate it inside your harness on your own task set.

Instrument the workflow, not the hype

Measure the pipeline's effect on outcomes you already track, plus the agentic signals that tell you the fleet is healthy. Resist vanity counters.

Stand the workflow up in stages, with hard gates

Don't wire the whole pipeline at once. Build the harness floor before the fleet; orchestration on a weak harness amplifies dysfunction. Each step has an exit criterion mapped to the workflow.

What's in window, what's quarantined

This manual applies a hard 60-day cut (≥ 2026-04-01) for any claim, statistic, benchmark, version, or "what a company does today," and uses primary engineering sources only. Foundational harness/loop posts that predate the window are used for stable architecture, never for time-sensitive metrics.

The SOC 2 evidence runbook

A detachable one-pager that operationalizes §08. For each technical control the pipeline enforces, it names the criterion, the exact evidence artifact, where it's stored, who owns it, and how often it's collected. Type 1 wants the design artifacts (configuration); Type 2 wants the operating records across the audit window.

One sampled change, one query

The point of wiring evidence into the gates: an auditor picks any merged change from the period, and a single query reconstructs its entire control chain from the hash-chained audit record plus the artifacts it points to.

# 1) one query returns the gate record for the sampled change
$ aud get --event pr.merged --pr 9182
  actor      agent://impl-7f3a   (scope task-4821 · owner u/eng-114)
  reviewer   u/eng-220     sast passed     cve_high 0     ci green
  change_ref plan/exec-4821       hash a17fde… (chain verified)

# 2) cross-check the artifacts the record points to
GitHub PR 9182 ......... approver ≠ author ✓          (CC8.1)
CI run for the merge ... required checks present ✓    (CC7.1)
docs/exec-plans/4821 ... approved before work began ✓ (CC3)
SIEM chain 0…9182 ...... unbroken, append-only ✓      (CC4.1)

One record plus the artifacts it references closes the loop for that change. Repeat across the auditor's sample; if all five Type 2 conditions from §08 hold for every sampled change, the operating-effectiveness test passes.