Two approaches to writing code with AI

Two suites, two assumptions #

• delivery-team — AI acceleration of a traditional human sprint. A linear, gated pipeline that mirrors a traditional Notion-based sprint process. Each stage maps to a process stage; each agent maps to a job title. AI makes every seat faster, but the shape is the sprint.
• flow — an AI-first approach to building. The spec is the source of truth and code is regenerated output. An orchestrator dispatches one wide probe generation of parallel generators, a multi-objective evaluator scores them on a Pareto front, and the winner ships through an evidence gate rather than on a calendar date. Further generations happen only when evidence demands them.

The contrast in one line #

delivery-team — AI-accelerated human sprint #

A sequential, gated pipeline. One path forward, fixed agent roles, single-threshold gates, and a human go/no-go at every transition.

flowchart TD
    subgraph DT["delivery-team — AI acceleration of a human sprint"]
        direction TB
        S1["Stage 1
Problem Brief
(user-researcher)"]
        S2["Stage 2
Design Intent
(product-designer)"]
        S3["Stage 3
Technical Spec
stories + EARS ACs
(architect → scrum-master)"]
        S4["Stage 4
Build — story by story
(frontend / backend / middleware devs)"]
        S45["Stage 4.5
Release Planning
(release-scorer)"]
        S5["Stage 5
Cross-Functional Readiness
(gtm / marketing / cx)"]
        S6["Stage 6
Release — ring 0→3
(release-communicator)"]
        S7["Stage 7
T+2 Fast-Follow
retro + close"]

        S1 -->|"Gate 1→2"| S2
        S2 -->|"Gate 2→3"| S3
        S3 -->|"Gate 3→4"| S4
        S4 -->|"Gate 4→4.5"| S45
        S45 -->|"Gate 4.5→5"| S5
        S5 -->|"Gate 5→6"| S6
        S6 -->|"Gate 6→7"| S7
    end

    H["Human HITL
go / no-go at every gate"]
    H -.approves.-> S1
    H -.approves.-> S3
    H -.approves.-> S5
    H -.approves.-> S6

    QA["QA gate per story
single threshold:
zero blocking failures"]
    S4 --- QA

    classDef stage fill:#e8f0fe,stroke:#4285f4,color:#1a1a1a;
    classDef human fill:#fff4e5,stroke:#f59e0b,color:#1a1a1a;
    class S1,S2,S3,S4,S45,S5,S6,S7 stage;
    class H,QA human;

One path forward, gated stage-by-stage, with a human approving each transition.

Characteristics: one path forward · fixed agent roles (= human job titles) · time-boxed sprint · single-threshold gates · code is the artifact · stories in prose · humans gate each transition.

flow — AI-first probe-and-ship #

No sprint. The spec (GWT scenarios → derived EARS, executable, versioned) is the source of truth; code is regenerated output. A cheap interpretation panel probes the spec for ambiguity before any implementation token is spent. The orchestrator then dispatches one wide probe generation of N parallel generators, where N comes from the effort's weight-class envelope (light 3 / standard 3 / heavy 5–7, ceiling 10) — not from fixed roles. Each writes only to its own variant directory (P1: intelligence parallel, writes serial). A multi-objective evaluator scores variants on a Pareto front with a noise floor; the cull close is the checkpoint — adversarial review and the ship decision follow immediately. The winner ships through flow-ship's gate on named qualitative grounds; post-ship, narrow redispatch (N=1–2, grafting from the shipped variant) happens only on named evidence — a fired watch, a fork the evals can't settle, a spec change.

flowchart TD
    SPEC["spec.md + constitution.md
GWT scenarios (SCN) → derived EARS (SR)
executable, versioned
source of truth — code is regenerated"]
    EVAL["evals/ — multi-objective suite
correctness · perf · maintainability
a11y · security · cost
(versioned, with adversarial holdouts)"]

    SPEC --> PANEL

    PANEL["flow-panel
3–5 cheap parallel readers
divergent readings → spec amendments
gen-1 requires a panel record"]
    PANEL --> ORCH

    ORCH["flow-orchestrator
dynamic dispatch
N = f(weight class, delta), not fixed roles
(P1: writes serialize here)"]

    subgraph GEN["One wide probe generation — intelligence parallel, writes serial"]
        direction LR
        V1["generator
bias: maintainability"]
        V2["generator
bias: simplicity"]
        V3["generator
bias: convention"]
    end

    ORCH ==>|"spawn parallel variants
each writes ONLY its own dir"| GEN

    CULL["flow-cull
score vs evals, noise floor
Pareto front survives
cull close = the checkpoint"]
    EVAL -.feeds.-> CULL
    GEN --> CULL

    CHAV["flow-chavruta
stability vs velocity reviewers
exit at documented dissent,
not consensus → dissents-active.yaml"]
    CULL --> CHAV

    GATE{"flow-ship gate
named qualitative grounds
deep eval pass · ledger audit
FIRED revert probe · watches"}
    CHAV --> GATE

    GATE -->|"ship — clean, or gated behind flags"| SHIP["flow-ship
progressive rollout via flags
changelog + ship record from spec delta
pre-registered post-ship watches"]

    MON["flow-dissent-monitor
watches commits for
reactivation triggers"]
    SHIP -.monitored.-> MON
    MON -.reactivated dissent.-> ORCH
    SHIP -.->|"fired watch / eval-blind fork / spec delta
narrow redispatch, N=1–2 + graft"| ORCH

    classDef truth fill:#e6f4ea,stroke:#34a853,color:#1a1a1a;
    classDef agent fill:#f3e8fd,stroke:#a142f4,color:#1a1a1a;
    classDef gen fill:#fce8e6,stroke:#ea4335,color:#1a1a1a;
    classDef decision fill:#fff4e5,stroke:#f59e0b,color:#1a1a1a;
    class SPEC,EVAL truth;
    class ORCH,PANEL,CULL,CHAV,SHIP,MON agent;
    class V1,V2,V3 gen;
    class GATE decision;

A spec-driven probe → generate → cull → ship pipeline; no calendar, no fixed roles.

Characteristics: spec → regenerated code · dynamic agent count (function-shaped, not role-shaped) · parallel reads/generation, serialized writes · multi-objective Pareto evaluation (no single gate) · one wide probe, then evidence-gated narrow redispatch (no time box) · an evidence-gated ship, never a scalar · preserved dissent with reactivation, not forced consensus.

GWT → EARS layered spec #

Status: implemented & merged. flow's entry unit of work is a Given/When/Then behavioral scenario (SCN-{NNN}) that derives the EARS requirements (SR-{NNN}) — so the spec is user/product-focused first rather than engineering-spec-first. See flow/context/flow-spec-protocol.md and flow/context/flow-philosophy.md (P3).

Previously flow-spec-writer converted natural language straight to EARS (The {system} shall…), a system-centric grammar. Leading with GWT keeps observable user behavior primary and defers system decomposition. It also pays off twice: a GWT scenario is already a graded example, so the scenarios double as flow's eval datasets (P4).

The layered spec — scenarios first, requirements derived

1. Behavioral layer (primary): GWT scenarios. Given <context>, When <event>, Then <observable outcome>. Authored from the actor's perspective. This is what the human reviews and what flow-narrator derives comms from.
2. Normative layer (derived): EARS requirements. Each scenario expands into the SR-{NNN} requirements that must hold for it to pass. EARS stays load-bearing and parseable — it just sits downstream of behavior.
3. Conformance layer: graders + datasets. GWT scenarios seed evals/datasets/ directly; EARS requirements still map to graders via evals/harness.yaml.

Why keep EARS, not go pure GWT. The very dimensions on flow's Pareto front — security, perf, cost — are often not user-observable events, so they don't fit Given/When/Then cleanly. EARS's ubiquitous/state-driven forms cover the ambient requirements GWT can't. Use quality-attribute scenarios for the few non-functional cases that do warrant a scenario, and let EARS carry the rest.

Traceability: SCN-{NNN} (scenario) → SR-{NNN} (requirement) → grader + dataset. This preserves the existing conformance-mapping discipline while adding a product-first front door.

Implemented across 12 files: the spec protocol and P3 philosophy (behavioral layer + SCN/SR model), flow-spec-writer and the /flow-spec command (scenario-first authoring, --requirement fast-path for non-functional SRs), the eval protocol and /flow-eval (scenarios seed correctness datasets), flow-generator / /flow-generate (variants implement SCN + SR), flow-orchestrator, flow-narrator (comms led by SCN), /flow-init (scenario-first initial spec), and the README + USAGE docs.