SOPs-as-Code: The AI Execution Playbook

From Wiki Pages to Manifests

Most design teams already have SOPs. They just do not call them that. They live in onboarding docs, copied prompts, old Miro boards, and the phrases senior people repeat in review: “show me the quote,” “split current from future state,” “do not merge the journey and the blueprint,” “who owns this change.” That is useful craft, but it is a terrible runtime. A new designer cannot inspect it cleanly. A machine cannot execute it safely. CI cannot fail it before a weak artifact reaches a client. The result is uneven quality disguised as creative freedom.

ASD treats the method itself as a design object. The machine source of truth lives in manifest files under the knowledge package. The readable projection lands in the portable SKILL.md surface. The runtime then enforces the boring parts humans routinely forget under deadline pressure: evidence minimums, non-empty fields, forbidden placeholders, review gates, typed handoffs, and a deterministic fact-check before any human phase advance. That is the important shift. The library is not a folder of admired templates. It is an executable operating discipline.

Once I encode a method this way, three things change immediately. First, the method becomes inspectable. A junior designer can see the real contract instead of reverse-engineering it from examples. Second, the method becomes testable. I can run fixtures, compare runs, and tighten failure classes. Third, the method becomes governable. When something drifts, I can point to the manifest, the review rows, the factcheck output, and the commit that changed the rule. The practice stops relying on memory and starts relying on versioned judgment.

That distinction is why article 29 mattered so much in the series. It showed the framework article itself becoming the client: one lead designer, one part-time design-ops owner, three reviewers, and a growing library of methods that had to survive live runs across sectors. The lesson was blunt. Prose-only methods create prose-only quality. Once the method has a machine tail, the practice can improve without depending on who happened to brief the agent that day.

Anatomy of a Method Manifest

The shipped runtime source of truth today is JSON. I use YAML here because it is the clearest teaching format for the anatomy. The engine reads machine manifests, not nicely formatted examples. The key idea is simple: every field exists because something downstream needs it. Inputs tell the runtime what must already be in the project. Steps preserve sequence and role ownership. The output schema constrains shape. Acceptance criteria turn quality into checks. The review gate makes approval explicit instead of cultural. If a field cannot change runtime behavior, it probably does not belong in the contract.

id: service-blueprinting
phase: synthesis
owner: mapper
inputs:
  - kind: evidence-set
    min: 4
    note: frontline observations and process documentation
steps:
  - role: mapper
    instruction: Map customer actions in order and cite evidence for each node.
  - role: mapper
    instruction: Add physical evidence, frontstage, backstage, and support-process lanes.
  - role: critic
    gate: true
    instruction: Reject placeholder lanes or uncited nodes.
output_schema:
  kind: service-blueprint
  required_fields:
    - lane
    - label
    - evidence_refs
acceptance_criteria:
  - type: min-nodes
    value: 4
  - type: min-evidence-per-node
    value: 1
  - type: field-non-empty
    field: lane
  - type: forbid-field-values
    field: lane
    values:
      - unknown
      - tbd
      - n/a
review_gate: critic

That example is deliberately small, but it already captures the difference between a method description and an executable contract. “Blueprint well” is vague. “Reject placeholder lanes or uncited nodes” is enforceable. The service-blueprinting flagship skill adds depth about lane craft, current-versus-future separation, and failure points. The manifest keeps the machine truths: minimum evidence, required fields, and the fact that a Critic veto keeps the artifact in draft. Both layers matter. The human-readable flagship adds judgment. The manifest defines what the runtime can actually police.

The deeper point is that manifests do not eliminate judgment. They relocate it. The designer still decides where the human gate sits, which fields are non-negotiable, what counts as evidence, and which failures must fail closed. That is exactly the right layer for human craft. I do not want humans wasting judgment on whether a lane is blank. I want them spending judgment on whether the line of visibility is drawn honestly, whether the evidence is structurally representative, and whether the service change should exist at all.

The 80-Skill Library by Phase

The library currently ships 80 skills from 81 sources. That distinction matters. There are 80 generated projections plus one authored flagship source, but only 80 shipped skills because service-blueprinting is present twice in source form and only once in the emitted pack. The compiler applies a flagship-wins rule: it walks the authored flagship tree before the generated tree and takes first-write-wins for the same skill id. That is how the platform keeps one executable contract while still allowing depth where a method genuinely needs more human judgment. The library also grew with the Studio v2 artifact kinds, jobs-to-be-done among them, so the phase counts below reflect the current shipped set rather than the original release.

The phase distribution is not cosmetic inventory. It tells you how the practice is weighted. Research and synthesis remain the thickest layers because evidence quality still determines almost everything downstream. Delivery and measurement are narrower in count, but they are where governance gets real: standards, rollout plans, audits, service recovery, KPI trees, and the gates that keep a change honest after the prototype applause dies down.

The twelve-skill canon the series leans on makes the architecture even clearer. Three research methods, six synthesis methods, one ideation method, one delivery method, one measurement method. The canon is smaller than the whole library. It is the recurring spine pulled by sd_method_run across articles and cases. In other words: the 80-skill count proves breadth; the canon proves continuity.

{
  "skillSources": 81,
  "skillsShipped": 80,
  "phaseCounts": {
    "research": 19,
    "synthesis": 15,
    "ideation": 13,
    "prototyping": 12,
    "delivery": 10,
    "measurement": 11
  },
  "flagshipReplacement": {
    "id": "service-blueprinting",
    "rule": "flagship-wins",
    "generatedTwinShipped": false
  }
}

This is also where the flagship authored skill earns its keep. The generated twin for service-blueprinting is perfectly serviceable as a machine projection. The authored flagship adds what the manifest cannot carry elegantly: why the line of visibility is a design decision, why current and future state must be separate artifacts, why backstage cannot be a dumping ground, and why recovery rows matter. ASD keeps both source forms in agreement, then ships the deeper one. I like that pattern because it respects both sides of the practice: determinism where machines need determinism, prose depth where humans need craft.

Evolving SOPs Through Review

The wrong mental model is “we wrote the SOP, so the problem is solved.” No. An SOP library is a live service. It takes change requests, accumulates defects, gets challenged by new domains, and eventually retires bad assumptions. Article 29 made this explicit with five gates: source stability, executable shape, fixture survival, publish readiness, and operating review. That is the right governance pattern because method quality does not fail in one place. It fails at the source, the schema, the live run, the release ritual, and the telemetry trend.

When I change a method, I am changing institutional behavior. So the review has to be more serious than “this wording feels clearer.” The creator authors the change. The reviewer tests method integrity. The approver owns production risk. If the run depends on live consent, political trade-off, clinical or legal judgment, or other irreducibly human accountability, the manifest says so. The method can still exist, but as a human-run checkpoint rather than an autonomous agent routine. That boundary is not a limitation. It is design maturity.

change:
  skill_id: service-blueprinting
  version: 1.3.0
  creator: service_design_practice
  reviewer: critic
  approver: journey_owner
  required_checks:
    - generated-skill-sync
    - fixture-regression
    - provenance-review
    - factcheck-green
  release_rule: reject-if-any-required-check-fails

The authored-versus-generated split sharpens this review discipline. A generated skill changes when its manifest changes or the generator changes. A flagship skill can also change because the prose guidance got better, even while the machine acceptance stays the same. That means the team has to review two failure classes separately: runtime contract drift and judgment guidance drift. Good teams name that difference. Weak teams muddle it, then wonder why the artifact still passes the machine while the practitioner experience gets worse.

There is another advantage to this explicit review loop: institutional memory stops decaying into anecdote. Article 29 mined 31 draft SOPs from the corpus and accepted 26 into reusable form. That acceptance number matters because it proves selectivity. Five of those drafts stayed local because they were too context-bound. I would rather keep a method local than pretend it is generic when it is really a disguised memory of one project. Reusability is earned, not declared.

CI Enforcement and Institutional Memory

Review alone is not enough because humans get tired, optimistic, and busy. The library needs a write path that enforces what the review claims to care about. ASD does this in layers. The method run returns the steps and acceptance contract. The artifact write checks structure and acceptance. The Critic review decides pass or veto. Then sd_factcheck replays integrity, acceptance, and review before the human phase gate. If that final check fails, CI fails. Cleanly. Loudly. With exit code 1.

asd method-run --projectId framework --methodId service-blueprinting
asd artifact-write --projectId framework --kind service-blueprint --file artifacts/current-blueprint.json
asd review --projectId framework --artifactId blueprint-001 --verdict pass --rows review/pass-rows.json
sd_factcheck framework
if [ $? -ne 0 ]; then
  echo "factcheck failed"
  exit 1
fi

The important subtlety is what happens on failure. ASD does not quietly discard the bad artifact. Failed acceptance persists as draft with machine-readable failure rows. That is a much better learning surface. The team can inspect the defect, repair the exact rule that failed, and rerun without pretending the mistake never happened. It is the same philosophy I want in service design more broadly: fail closed, keep the evidence, and make remediation explicit.

name: sop-library-ci
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: node platform/compiler/generate-skills.mjs
      - run: node platform/compiler/emit-packs.mjs --output /tmp/asd-packs
      - run: sd_factcheck framework

That CI loop is not glamorous. Good. It should not be. Boring enforcement is exactly what lets designers spend energy on more interesting problems. Once the machine handles mermaid validity, field completeness, evidence minimums, registry integrity, and review-state consistency, the human reviewer can focus on the real questions: did we encode the right boundary, is the method still faithful to the books and proof cases, and does this automation leave dignity, safety, or accountability exposed?

Institutional memory then becomes cumulative instead of sentimental. Every merged method carries provenance. Every failure leaves a record. Every release has a diff. Every emitted pack can tell you what shipped. The library is still authored by people, but it no longer depends on people remembering what changed three quarters ago. That is the real dividend of SOPs-as-code. The practice starts compounding.

Case: The Framework Itself

Article 29 made the framework itself the case study, which is exactly why it works so well as the spine for this chapter. The team was small: one lead designer, one design-ops owner, three reviewers, and an AI stack used as execution surface rather than authority. The initial build took eight weeks. Then came six pilot iterations. The headline gains were not magical. They were procedural. First-pass SOP success moved from 50% in iteration 1 to 100% in iterations 5 and 6. Mean human review time fell from 44 minutes to 15. Junior-designer ramp to a safe first draft dropped from roughly four weeks to eight working days. None of that happened because the prompts got more lyrical. It happened because the method became inspectable, testable, and governable.

The blueprint worked example in article 29 is especially useful because it exposes the whole stack in miniature. Source methods and proof points were mined from the series. Mined patterns were accepted or rejected. A YAML contract was drafted. Fixture generators were built. A flagship blueprint SOP was tested against fixed cases and live runs. CI enforced validation. CODEOWNERS and approvers held releases. Telemetry then determined whether a method should be retained, revised, or retired. That is more than documentation. It is a service operating model for practice quality itself.

What I find most convincing is the humility built into the design. The article does not claim every method should be autonomous. It explicitly names the work that should stay human: interviewing, consent handling, politically sensitive reframing, final go/no-go choices, and other decisions where consequence outruns formal acceptance criteria. That honesty is one reason the framework scales. Teams trust a system more when it admits its boundaries.

SOPs-as-code builds a practice where good judgment survives handoff, where new people inherit more than vibes, where a method can improve through review, and where AI acceleration stays accountable to evidence. That is the execution playbook. And once you have it, the rest of the platform starts to make more sense: the skill library, the Critic, the factcheck gate, the human phase receipt, even the closing argument of this book. They are all answers to the same question. How do we make rigor compound? It also gives the team a durable answer when a client, reviewer, or future maintainer asks what changed, why it changed, and which rule now enforces it.