How AI-first teams build software.

Why Cloverleaf

AI inverts the cost structure of software. Implementation becomes near-free; specification, review, coordination, and failure-handling become the new bottlenecks. Methodologies built on the assumption that humans are the slow part — Scrum sprints, Shape Up cycles, traditional code review — under-allocate effort to the parts that actually gate throughput in an AI-first team.

Cloverleaf re-balances effort around the new bottlenecks. Specifically:

• The human attention moves upstream to strategic decisions where it has the most leverage.
• Risk classification is deterministic and conservative so AI volume can scale without compromising on what matters.
• Specs are treated as binding contracts so agents can execute without ambiguity.
• Code review is structurally fresh-eyes, not aspirational.
• Failure handling is typed so mechanical issues never burn human attention.

Principles

These principles bind throughout the methodology. They are not aspirational — they are the contract.

1. Humans gate, AI executes. Humans never implement on the critical path. They define, approve, and reject.
2. Specs are contracts, not suggestions. Every artifact has a mandatory schema. Agents can rely on the contract.
3. Fresh eyes, always. Code review happens in a separate AI context. The agent that wrote the code never reviews it.
4. Risk is deterministic, not judged. AI never decides “is this risky?” — risk is rules-based, conservative, and only ever escalates.
5. Strategic decisions are batched upstream; tactical decisions stay with the agent. Humans approve at the RFC/batch level, not per-Task by default.
6. Failure type determines handling. Mechanical → auto-retry; quality → bounce once; strategic → escalate immediately.
7. Phases are contracts, agents are recommendations. The methodology binds at phase input/output. Agent split is a recommended default.
8. Roles are agnostic; gates carry responsibilities. The methodology defines what each gate decides; how teams staff it is an org choice.
9. Docs are for AI; Work Items are for humans. Documenter Agent output serves AI; humans communicate intent through RFCs, Spikes, Plans, and Tasks.

Two tracks

Discovery feeds Delivery via approved Tasks.
Delivery feeds Discovery via emergent questions, mid-implementation discoveries, or Final-Gate rejections that require revisiting the RFC.

The stages

Discovery

The Discovery Track converts an idea into a ratified plan with well-formed Tasks.

Stages

1. RFC — A proposal authored by the Researcher Agent. Origination is org-decided.
2. Spike(s) — Zero or more research/de-risk tasks. Each Spike has a single specific question, a method (research/prototype/benchmark), evidence-backed findings, and a recommended path.
3. RFC + Strategy Gate (Human) — Approves the RFC + Spike findings as a strategic decision. Rejection sends the RFC back for revision.
4. Plan & Task Breakdown — Executed by the Plan Agent. Emits the Plan artifact: finalized RFC, Task DAG, Tasks (each conforming to the mandatory Task schema), and path → reviewer mappings.
5. Task Batch Gate (Human) — Verifies the Task breakdown is well-decomposed, achievable, and faithfully implements the RFC intent.

Approved Tasks land in the Delivery backlog.

Failure handling on Discovery

• A failed Spike does not invalidate the RFC; it informs the next Spike or the RFC revision.
• A failed Strategy Gate sends the RFC back for re-drafting; if multiple iterations fail, the RFC is closed.
• A failed Task Batch Gate bounces back to Plan for re-decomposition (cheaper than re-spiking).

RFC-direct tasks

Sometimes the work doesn’t fit a Plan. Two cases recur:

• Hotfix after a Plan has delivered. The Plan’s tasks are merged, the RFC is approved, but a small bug or polish item surfaces afterward. Forming a new Plan with one task in it is pure ceremony.
• Incremental RFC progress without batch decomposition. The operator hasn’t decided how to chunk the next slice of work, but one concrete task is clear right now. Create that task; defer Plan formation until a batch shape emerges (or skip Plans entirely if the work keeps arriving one task at a time).

In both cases the operator can emit a task directly against the approved RFC, no Plan, no task_batch_gate. The task gets context.rfc set; its parent field stays absent. The walker still drives it through Delivery normally via /cloverleaf-run.

The walker’s RFC auto-advance treats these RFC-direct tasks as first-class. After every Plan completes, the walker asks cloverleaf-cli rfc-tasks <repo_root> <RFC-ID> whether the RFC can advance — and that check considers both sibling Plans and standalone tasks of the same RFC. An in-flight standalone task blocks the advance; a merged one counts toward “at least one delivered.”

The tradeoff is real: skipping the Plan means skipping task_batch_gate. That’s the right call for hotfixes and one-task-at-a-time work, where there’s no decomposition to review. It’s the wrong call for a large multi-task scope, where the human’s review of the decomposition is the load-bearing checkpoint. Plans are a checkpoint, not ceremony — use them when the checkpoint earns its keep.

Delivery

The Delivery Track executes every Task along one path. Deterministic risk classification decides not where a Task goes but who reviews it — which council profile convenes after implementation.

Stages

1. Pickup — The Implementer Agent picks up an approved Task with its Definition of Done, Acceptance Criteria, and risk markers.
2. Risk Classifier — Rules-based, deterministic. Examines the Task’s touched paths against project-defined rules (e.g., changes under auth/ always select the full profile). Conservative by design: only escalates, never downgrades.
3. Documentation — Every Task passes through a documenting step. For risk_class: high the Documenter Agent adds documentation commits; for low the orchestrator advances the step directly.
4. Delivery Council — risk_class selects the profile. The fast delivery profile (delivery-fast) seats the Reviewer, adding the Security Reviewer when security_class is high. The full delivery profile (delivery-full) additionally seats the UI Reviewer when the diff touches UI, and QA. Aggregation is any-veto: one bounce returns the Task to the Implementer.
   • Security Review — Seated on the council when a task’s security_class is high: a deterministic secret scan followed by an LLM vulnerability judgment. Blocker findings route to escalation; clean passes let the council conclude.
5. Final Approval Gate (Human) — The single human gate in Delivery. Approves merge.
6. Merge & Deploy — The Implementer (or a deploy agent) merges and ships.

Security review in the council

A Task whose security_class is high seats the Security Reviewer as a blocking council member, under either profile. The council aggregates by any-veto, so a Security Reviewer bounce returns the Task to the Implementer — there is no ordering an orchestrator can get wrong, because the council does not report a pass until every seated member does.

The guarantee is recorded rather than inferred: the council → final-gate transition carries a security_review_verdict, so the audit trail shows which review produced the pass, and a re-run after a bounce records a fresh one.

Releases before Standard 0.8.0 encoded this as edge annotations on a hub state. That topology is retired: the hub and its guarded edges collapsed into the council. security_gate survives as an optional annotation a consumer state machine may set on its own transitions, and the reset annotation is gone. See Chapter 11 (Glossary) for the mapping.

See also: Chapter 7 (Agents) · Chapter 8 (Gates)

Failure handling on Delivery

• Mechanical (build break, test flakiness, lint) — auto-retry with the same agent.
• Quality (Reviewer rejection) — bounce once back to Implementer; if rejected again, escalate.
• Strategic (mid-implementation discovery that the Task is wrong) — escalate immediately to Discovery; the Task does not block the rest of the batch.

Work items

Cloverleaf has four Work Item types. Each maps to one leaf of the cloverleaf interchange and has a mandatory schema.

RFC

A proposal. Captures problem, context, recommended approach, alternatives, and acceptance criteria. Authored by the Researcher Agent.

Spike

A bounded research task with a single specific question, a method (research/prototype/benchmark), evidence-backed findings, and a recommended path.

Plan

The output of Plan & Breakdown. Contains: finalized RFC, Task DAG, Tasks (each schema-valid), and path → reviewer mappings.

Task

A unit of implementation work. Has DoD, AC, risk markers, dependency edges, and assigned reviewers.

A Task’s parent references a Plan when materialised by /cloverleaf-discover. When the operator creates a Task directly against an RFC (via /cloverleaf-new-task --rfc=<RFC-ID>), parent is absent and context.rfc is set — the canonical shape for an RFC-direct task (see chapter 4 § “RFC-direct tasks”).

All four types share a common envelope (project, id, status, relationships, extensions). The full schemas live in the Cloverleaf Interoperability Standard at standard/.

Agents

Cloverleaf defines 9 default agent roles. They are recommended, not mandated — phases bind, agents are flexible.

The Security Reviewer is a hybrid two-pass agent: deterministic secret scan (cloud keys, tokens, PEM headers) followed by LLM judgment (injection, authz, deserialization, SSRF, input validation, weak crypto). It routes by severity — blocker findings escalate, error/warning findings bounce back to the Implementer, clean diffs pass. It is seated as a blocking council member when a task’s security_class is high.

The Chair is a deliberative judge. It is convened only when a blocking member of a council that aggregates by chair bounces — if every blocking member passes, or if any member escalates, the verdict resolves without it. When it is convened it reads every seated member’s verdict and feedback, renders the council verdict, and curates which feedback reaches the Implementer. The Chair judges the members’ verdicts rather than the code, and it may raise a bounce to an escalation but never lower one.

Mechanical enforcement

The security-review requirement is enforced by the council’s aggregation rule, not by orchestrator prose.

How it works. When security_class is high, the Security Reviewer is seated as a blocking member of the delivery council. Aggregation is any-veto: a bounce from any seated member returns the Task to the Implementer, and the Task cannot reach final-gate until every seated member passes. The outcome is written as security_review_verdict on the council → final-gate transition, so the pass is auditable rather than assumed.

Motivation. During the v0.8.0 claw-crypto dogfood (2026-05-25), the LLM orchestrator driving /cloverleaf-run skipped the security-review bookkeeping — the diff triggered the security path but the state machine advance was not gated. Seating the reviewer inside the council closes that gap structurally: the ordering the orchestrator used to get wrong no longer exists.

See also: Chapter 5 (Delivery) · Chapter 8 (Gates)

A solo developer can run all 9 by switching personas in a single session. A 50-person team can map them to specialized teams. The methodology only requires that the function of each role is filled at the right phase.

Gates

Cloverleaf has three human gates. Each decides one thing.

Strategy Gate (Discovery)

Decides: “Is this strategy sound?” Considers RFC + Spike findings. Outputs: approve, reject (with reason), or send back for revision.

Task Batch Gate (Discovery)

Decides: “Does this breakdown faithfully implement the strategy?” Considers the Plan artifact. Outputs: approve, reject (re-decompose), or escalate (re-RFC).

Final Approval Gate (Delivery)

Decides: “Is this Task ready to merge?” Considers the implementation, review reports, and any QA artifacts. Outputs: approve (merge) or reject (back to Implementer).

Path → reviewer mappings

Project-configurable rules suggest reviewers based on which code paths a Task touches:

• Changes under auth/ request a Security Reviewer
• Schema changes request a Database Reviewer
• Frontend changes request a Frontend Reviewer

The framework provides the mechanism (path → role rules); teams define the mappings per project.

Risk classification

Risk classification is deterministic and conservative. AI never decides “is this risky?” — risk is rules-based, only ever escalates.

Inputs

• Touched code paths (from the Task DAG)
• Touched data schemas
• Author identity (the Implementer Agent does not influence its own risk score)
• Project-specific rule configuration

Outputs

A single risk_class of low or high, which selects the delivery council’s profile — the fast delivery profile (delivery-fast) or the full one (delivery-full).

Conservative principle

If any rule matches high, the Task is high. Rules can only escalate; nothing in the Task or its execution can downgrade the classification afterwards.

Example rules

• Any change under auth/ → high
• Any schema migration → high
• Any change touching > 200 LOC → high
• Frontend-only change in a single component → low
• Documentation-only change → low (the fast profile seats no QA member)

Teams configure their own rules at project setup. The framework provides the matcher; the rules are project property.

security_class

A second risk axis, orthogonal to risk_class. Where risk_class is inferred from UI keywords and touched paths, security_class targets the complementary slice: backend logic, credential handling, deploy scripts, and other security-sensitive work that carries no frontend keywords. A task with security_class: high seats the Security Reviewer on the delivery council regardless of which profile risk_class selected.

The gap this fills: the most security-sensitive changes (secrets management, auth flows, infra scripts) would be classified low by a UI-keyed classifier alone, reaching merge without a vulnerability review. security_class is inferred from sensitive path prefixes and keyword markers at task creation, then re-checked against the actual diff at review time.

Failure handling

Cloverleaf classifies failure types so handling is mechanical, not improvised.

Mechanical failures

Build breaks, lint errors, test flakes, transient infra issues. Handling: auto-retry with the same agent, up to N attempts. If still failing, escalate to a human via the next available gate.

Quality failures

Reviewer rejections, QA findings, documentation gaps. Handling: bounce once back to the Implementer with the rejection rationale. If rejected again, escalate.

Strategic failures

Mid-implementation discovery that the Task is wrong, that the RFC is incomplete, or that a key assumption was false. Handling: escalate immediately to Discovery. The Task is unblocked; the rest of the batch continues. The escalation may trigger a new Spike or a revised RFC.

Glossary

Agent — A specialized AI worker with a defined role. Cloverleaf recommends 9 by default but binds at phase contracts, not at agent count.

Chair — A deliberative judge convened when a blocking member of a council that aggregates by chair bounces — a member escalation is final and bypasses it. It reads every member’s verdict, renders the council verdict, and curates the feedback forwarded to the Implementer. It may raise a bounce to an escalation, never lower one.

Cloverleaf Interoperability Standard — The machine-readable spec (JSON Schemas, OpenAPI contracts, conformance runner, reference validators) that lives in standard/.

DAG — Directed Acyclic Graph. Cloverleaf’s Task structure is a DAG: tasks have ordered dependencies but no cycles.

Delivery Track — The per-Task execution loop. Pickup → Risk Classifier → Documentation → Delivery Council → Final Approval → Merge.

Discovery Track — The strategic planning loop. RFC → Spike → Strategy Gate → Plan & Breakdown → Task Batch Gate.

Fast delivery profile (delivery-fast) — The council profile selected for risk_class: low Tasks. Seats the Reviewer, plus the Security Reviewer when security_class is high.

Full delivery profile (delivery-full) — The council profile selected for risk_class: high Tasks. Adds the UI Reviewer (when the diff touches UI) and QA to the fast profile’s seats.

Gate — A human approval point. Cloverleaf has three: Strategy Gate, Task Batch Gate, Final Approval Gate.

Plan — The output of Plan & Breakdown. Contains finalized RFC, Task DAG, schema-valid Tasks, and path → reviewer mappings.

RFC — A proposal Work Item. The starting point for any non-trivial change.

Risk Classifier — Deterministic, rules-based mechanism that sets a Task’s risk_class, which selects the delivery council’s profile.

Security Reviewer — A hybrid agent: a deterministic secret scan followed by LLM vulnerability judgment. Seated as a blocking member of the delivery council when a Task’s security_class is high.

Spike — A bounded research Task attached to an RFC. Single question, single method, evidence-backed findings.

Task — A unit of implementation work with DoD, AC, risk markers, and dependency edges.

Work Item — Any of the 4 mandatory artifact types: RFC, Spike, Plan, Task.

This glossary expands over time—terms are added as methodology teams encounter them in real practice, not speculatively.

Retired vocabulary

Terms used before Standard 0.8.0, kept so an older document or a returning reader can be mapped onto the current model.

• Fast Lane → the fast delivery profile (delivery-fast).
• Full Pipeline → the full delivery profile (delivery-full).
• automated-gates → the council phase. The hub state and the three guarded edges leaving it collapsed into a single council.
• security_gate / resets_security_verdict → a blocking security council member plus a recorded security_review_verdict on council → final-gate. security_gate survives as an optional annotation a consumer state machine may set on its own transitions; resets_security_verdict is gone.