Coding Pipeline

This repo vendors a playbook/ directory: a de-branded copy of a reusable, test-first coding pipeline process framework, plus Drupal-specific guidance. It is kept as in-repo reference material for contributors and their AI coding agents working on this module.

This page is the developer reference — what the playbook is, that it is dev-only, where it lives, a readable overview of the process, and the per-variant flow diagrams for the review-rigor dial. For the conceptual “when to reach for each rung,” see the AI Pipeline page.

The pipeline at a glance

The pipeline is test-first and phased — O → D → A → T → F → T → A → U → S → O. The Tester authors the suite and confirms it fails (RED) before the Feature implementor writes code, then re-runs for GREEN. Design (D) and the UI Walkthrough (U) run only when the change touches a UI surface. The review-rigor dial (base / second-opinion / panel) is applied at the two human gates (brief and diff). The base rung has accepted synonyms — base, standard, no variant, and none all name the same rung (base is the primary label; none remains accepted).

flowchart TD
    O0([O · survey + write brief])
    G1{{human gate — brief<br/>review-rigor dial}}
    Dq{UI surface?}
    D[D · wireframe<br/>→ human sign-off]
    A1[A · architecture review<br/>brief + wireframe, up front]
    T1[T · author suite<br/>confirm RED]
    F[F · implement to GREEN]
    T2[T · re-run<br/>confirm GREEN]
    A2[A · anti-duplication<br/>review the diff]
    G2{{human gate — diff<br/>review-rigor dial}}
    Uq{UI surface?}
    U[U · live-browser walkthrough]
    S[S · spec + WCAG audit]
    O1([O · open MR → human merges])

    O0 --> G1 --> Dq
    Dq -- yes --> D --> A1
    Dq -- no --> A1
    A1 --> T1 --> F --> T2 --> A2 --> G2 --> Uq
    Uq -- yes --> U --> S
    Uq -- no --> S
    S --> O1

    classDef gate fill:#fff3cd,stroke:#e0a800,color:#5c4400;
    classDef test fill:#e7f5ff,stroke:#1c7ed6,color:#0b4a86;
    classDef cond fill:#f3f0ff,stroke:#7048e8,color:#3b2a86;
    class G1,G2 gate;
    class T1,T2 test;
    class Dq,Uq cond;

Roles: O Orchestrator · D Designer · A Architecture reviewer · T Tester · F Feature implementor · U UI Walkthrough · S Spec Auditor. Full detail lives in playbook/workflow/workflow-coding-pipeline.md.

Dev-only — it does not ship

playbook/ is development-only. It is export-ignored, so it is present in the repo and in clones but is stripped from the packaged module release. Nothing in it is loaded or executed at runtime — it is documentation, not module code.

Where it lives

Everything is under playbook/ at the repo root:

playbook/README.md — the bot/agent-facing index that maps the whole directory. An agent starting work reads this first.
playbook/workflow/ — the coding pipeline, its shared conventions, one doc per pipeline role, and two support docs.
playbook/frameworks/drupal/ — Drupal best practices, the AI-module stack, and DDEV/Drush guardrails for agents.

The pipeline in brief

The pipeline is test-first and phased. Each build item runs through eleven numbered phases, shorthanded O → D → A → T → F → T → A → U → S. An Orchestrator (O) drives the whole cycle and spawns the specialist role agents; a human approves at the gates (a wireframe sign-off, and brief/diff review points).

The test-first idea is the core of it: the Tester authors the test suite from the approved brief and confirms it fails for the right reason (RED) before the Feature implementor writes any production code, then re-runs to confirm GREEN. Architecture review happens up front, on the plan, before code exists. Design (a wireframe) and the UI Walkthrough (driving the live UI in a real browser) run only when the change has a UI surface.

The roles, each with its own doc in playbook/workflow/:

O — Orchestrator: drives the pipeline, owns the issue/PR and the decision journal.
D — Designer: produces or ingests a wireframe for human sign-off (UI surfaces only).
A — Architecture Reviewer: up-front plan review, plus an anti-duplication gate on the diff.
T — Tester: authors the RED suite before implementation, verifies GREEN afterward.
F — Feature Implementor: writes the code against the brief and failing tests.
U — UI Walkthrough: drives every control in a real browser (UI surfaces only).
S — Spec Auditor: the Tier-3 visual / accessibility / spec audit authority.

The review-rigor dial

How much outside review a story gets is a per-story dial: base (in-session review only), second-opinion — also called dual review — (adds the Critic at the brief and diff gates), or panel (adds a two-model pair on an identical prompt, with a reconciliation step). The base rung has accepted synonyms — base, standard, no variant, and none all name the same rung. base is the primary label; none remains accepted because it is pervasive in existing briefs and templates.

The two models are named variables each dev binds to whatever they have access to: Author (Model 1) — your own coding model — and Critic (Model 2) — an independent outside reviewer, ideally a different provider. The AI Pipeline page explains when to reach for each rung; the diagrams below show what each changes in the flow.

Review-rigor variants

The three rigor rungs are the same test-first backbone with progressively more outside review bolted on at the two human gates (after the brief, and after the diff goes GREEN). The dial is declared per story in the brief.

`base` — in-session review only

(Accepted synonyms: standard, no variant, none — the same rung.) Thin or mechanical changes. The pipeline’s own A / T / U / S agents are the only reviewers; no outside model is called.

flowchart TD
    O1["O — survey & brief"]:::role
    D["D — wireframe · human sign-off<br/>(UI changes only)"]:::role
    A1["A — architecture review"]:::role
    Tr["T — author tests (RED)"]:::test
    F["F — implement"]:::role
    Tg["T — verify (GREEN)"]:::test
    Ad["A — anti-duplication check"]:::role
    U["U — UI walkthrough<br/>(UI changes only)"]:::role
    S["S — spec audit"]:::role
    O2["O — PR & merge"]:::role
    O1 --> D --> A1 --> Tr --> F --> Tg --> Ad --> U --> S --> O2
    classDef role fill:#e7f5ff,stroke:#1c7ed6,color:#0b4a86;
    classDef test fill:#d3f9d8,stroke:#2f9e44,color:#14532d;

`second-opinion` — the Critic at each gate

Also called dual review. The default minimum for non-trivial work. The Critic (Model 2, one independent outside model, via dual-review.sh) reviews the brief and, later, the diff. The pipeline’s own A / T / S remain the in-session review; the Critic is the second opinion. Hard findings block.

flowchart TD
    O1["O — survey & brief"]:::role
    D["D — wireframe · human sign-off<br/>(UI changes only)"]:::role
    BG["brief gate — Critic<br/>(outside second opinion)"]:::gate
    A1["A — architecture review<br/>(in-session review)"]:::role
    Tr["T — author tests (RED)"]:::test
    F["F — implement"]:::role
    Tg["T — verify (GREEN)"]:::test
    DG["diff gate — Critic<br/>(outside second opinion)"]:::gate
    Ad["A — anti-duplication check<br/>(in-session review)"]:::role
    U["U — UI walkthrough<br/>(UI changes only)"]:::role
    S["S — spec audit<br/>(in-session review)"]:::role
    O2["O — PR & merge"]:::role
    O1 --> D --> BG --> A1 --> Tr --> F --> Tg --> DG --> Ad --> U --> S --> O2
    classDef role fill:#e7f5ff,stroke:#1c7ed6,color:#0b4a86;
    classDef test fill:#d3f9d8,stroke:#2f9e44,color:#14532d;
    classDef gate fill:#fff3cd,stroke:#e0a800,color:#5c4400;

`panel` — two-model pair, reconciled

High-stakes changes. At each gate the same prompt bytes go to two independent reviewers — the Critic and a fresh-context Author — running in parallel; their findings are then reconciled. Feeding both arms a byte-identical prompt is what makes the comparison fair; the parallel arms are what let the panel both clear a false positive and catch what one arm alone misses.

flowchart TD
    O1["O — survey & brief"]:::role
    D["D — wireframe · human sign-off<br/>(UI changes only)"]:::role

    BP["brief gate — one prompt,<br/>byte-identical to both"]:::art
    BO["Critic<br/>independent review"]:::outside
    BA["fresh-context Author<br/>independent review"]:::outside
    BR["reconcile findings"]:::recon

    A1["A — architecture review"]:::role
    Tr["T — author tests (RED)"]:::test
    F["F — implement"]:::role
    Tg["T — verify (GREEN)"]:::test

    DP["diff gate — one prompt,<br/>byte-identical to both"]:::art
    DO["Critic<br/>independent review"]:::outside
    DA["fresh-context Author<br/>independent review"]:::outside
    DR["reconcile findings"]:::recon

    Ad["A — anti-duplication check"]:::role
    U["U — UI walkthrough<br/>(UI changes only)"]:::role
    S["S — spec audit"]:::role
    O2["O — PR & merge"]:::role

    O1 --> D --> BP
    BP --> BO --> BR
    BP --> BA --> BR
    BR --> A1 --> Tr --> F --> Tg --> DP
    DP --> DO --> DR
    DP --> DA --> DR
    DR --> Ad --> U --> S --> O2

    classDef role fill:#e7f5ff,stroke:#1c7ed6,color:#0b4a86;
    classDef test fill:#d3f9d8,stroke:#2f9e44,color:#14532d;
    classDef art fill:#f8f9fa,stroke:#868e96,color:#212529;
    classDef outside fill:#e5dbff,stroke:#7048e8,color:#3b2a86;
    classDef recon fill:#ffe8cc,stroke:#e8590c,color:#7a3608;

The dial fires at the two human gates. How to run each rung in this repo — the installed .claude/agents/ roles, the dual-review.sh Critic engine (any model, via LiteLLM), and the .env setup — plus a worked proof that the gates catch real defects, live on the Running the Pipeline and Pipeline Verification pages (Develop group).

AI Pipeline — the conceptual pipeline and the three rigor variations.
AI Agent Skills — reusable skills this module ships for AI coding agents.
Developer Setup — clone, install the toolchain, and start contributing.