A Durable Control Plane for Long-Running Agentic Coding

#1 Gap What Breaks

The problem

Chat is a poor control plane for long-running work

Once work spans sessions, review rounds, and resumable state, ordinary chat stops being enough. The gap is not mainly model capability; it is the absence of a durable control surface.

Human practice

Chat-native failure mode

Written plan with verifiable milestones

Scope drifts; done is asserted without evidence.

One change set per logical unit

Multiple concerns land in a single undifferentiated edit burst.

Code review before merge

The same agent that wrote the code judges its own correctness.

CI / test gates

Verification is optional, summarized, or hallucinated.

Resuming after interruption

Context compaction loses mission alignment.

Knowing who may edit what

Planner, implementer, and reviewer collapse into one session.

The design question: What is the minimum control-plane structure that lets a local coding agent stay resumable, reviewable, and governable—without a cloud orchestrator, without forbidding direct edits in ordinary chat, and without treating free-form prose as the source of truth?

#2 Rules Design Principles

Design invariants

What this control plane must preserve

These are the invariants the workflow has to keep intact if long-running agent work is going to stay resumable, reviewable, and bounded across interruptions.

01

Durable out-of-band canonical state

Workflow state must live outside the conversation buffer, in repo-adjacent machine-readable files that override stale chat summaries.

02

Slice-based execution

Work should decompose into bounded slices with acceptance criteria, declared surfaces, verification commands, and one-commit discipline.

03

Role separation enforced in code

Role boundaries must be enforced in code. The implementer edits product code; reviewers and auditors remain read-only.

04

Structured emit contracts

Roles should terminate through versioned schemas, not authority-bearing freeform markdown. Prose may explain; it does not authorize transitions.

05

Fail-closed verification

Vague startup intent, malformed reports, and missing evidence should block progress. The system should block rather than degrade silently.

06

Explicit opt-in

Workflow mode should stay optional. Ordinary chat remains valid for quick edits, Q&A, and work that does not need canonical state.

#3 Topology Architecture

Flat, primary-driven topology

One driver, one role at a time

A main agent session acts as the workflow root and dispatches at most one specialized role at a time. Roles cannot dispatch nested roles. There is no application server or cloud dependency: everything is local and repo-scoped.

Bootstrapper Setup

Scaffold or repair control-plane state

First-time `.agent/` scaffolding and recovery when canonical files are missing or broken.

Regrounder Reconcile

Canonical reconciliation and slice selection

Re-grounds plan and active slice against repo truth; handles dirty worktrees, roadmap drift, and stop-wave reconciliation.

Implementer Execute

Product edits and slice commit

The only role that may edit product code and create the slice commit. Runs verification before landing changes.

Reviewer Evaluate

Per-slice rubric review

Read-only structured review across contract coverage, correctness risk, verification evidence, and docs/state parity.

Auditor Evaluate

Project-level audit

Read-only evaluation of whether the slice fits the broader mission and backlog integrity.

Stop-judge Close

Final stop / no-stop judgment

Independent read-only judgments on whether work may stop. Default policy may require multiple unanimous judges on current HEAD.

Role dispatch routing

flowchart TB Driver["Workflow driver\n(main session + MCP claim/submit)"] subgraph setup ["Setup and reconciliation"] Bootstrapper["Bootstrapper\nscaffolding / repair"] Regrounder["Regrounder\nplan, slice selection, reconciliation"] end subgraph execute ["Implementation"] Implementer["Implementer\nproduct edits + slice commit"] end subgraph evaluate ["Read-only evaluation"] Reviewer["Reviewer\nper-slice rubric review"] Auditor["Auditor\nproject-level audit"] StopJudge["Stop-judge\nfinal stop / no-stop"] end subgraph close ["Closure gates"] StopVerifier["Stop verifier\n.agent/verify_completion_stop.sh"] end Driver -->|"missing scaffolding"| Bootstrapper Driver -->|"stale state / no slice / post-review reconciliation"| Regrounder Bootstrapper --> Regrounder Regrounder -->|"slice selected, no commit"| Implementer Implementer -->|"slice committed"| Reviewer Reviewer --> Auditor Auditor --> Regrounder Regrounder -->|"all slices done"| StopJudge StopJudge -->|"more judges required"| StopJudge StopJudge -->|"stop wave complete"| StopVerifier StopVerifier --> Regrounder Regrounder --> Driver

Dispatch

Mandatory dispatch order

Missing scaffolding → bootstrapper
Stale or ambiguous state → regrounder
No slice selected → regrounder
Slice selected, no commit → implementer
Committed slice, no review → reviewer
No audit → auditor
Post-review reconciliation → regrounder
All slices done → stop-judge (×N)
After stop judgments → stop verifier + final regrounder reconciliation

#4 Layer Canonical State

Repo-local filesystem control plane

Durable state adjacent to the git worktree

For local-first, inspectable agent workflows, a gitignored `.agent/` directory with JSON and JSONL files is the pragmatic instantiation of durable out-of-band state.

.agent/
  current/
    state.json                  # Workflow controller
    startup-brief.json          # Confirmed intake (not the plan)
    plan.json                   # Slice backlog + acceptance criteria
    active-slice.json           # Current implementation contract
    slice-history.jsonl         # Append-only role transcripts
    stop-check-history.jsonl    # Stop-judge judgments
    verification-evidence.json  # Command results + coverage
    tmp/                        # Repo-local scratch
  verify_completion_stop.sh
  verify_completion_control_plane.sh

01

Workflow controller

`state.json` drives automation: current phase, continuation policy, next mandatory role, reground flags, and stop-wave epochs.

02

Startup brief ≠ plan

Startup brief captures confirmed intake. The regrounder authors the slice plan from repo truth after confirmation—prose missions do not silently become execution contracts.

03

Active-slice contract

Goal, acceptance criteria, implementation surfaces, verification commands, basis commit, and scope locks. Verifiers fail closed when plan and active slice drift.

#5 Unit Slice Lifecycle

Central unit of work

One slice at a time, one commit per slice

Each plan entry needs non-empty, verifiable acceptance criteria. A slice is not complete until it lands as a new commit, reviewer and auditor history is recorded while active-slice status stays `committed`, and the regrounder accepts it as `done`.

Slice lifecycle phases

stateDiagram-v2 [*] --> selected: regrounder selects slice selected --> in_progress: implementer begins in_progress --> committed: commit + implemented record committed --> done: regrounder accepts committed --> selected: regrounder reopens done --> [*] in_progress --> reground: roadmap drift discovered committed --> reground: dirty worktree / reconciliation reground --> selected: regrounder reconciles

01

Select

Regrounder selects a slice, locks acceptance criteria and basis commit, and writes the active-slice contract.

02

Implement

Implementer works against the contract, runs verification commands, and creates exactly one slice commit.

03

Evaluate

While active-slice status stays `committed`, reviewer and auditor append `reviewed` and `audited` records to slice-history. Failures reopen scope via regrounder reconciliation.

04

Reconcile

Regrounder updates backlog state, handles dirty worktrees, and selects the next slice—or advances to stop evaluation.

05

Close

When all slices are done, stop-judges and verifiers must pass before continuation policy may become done.

While continuation policy is continue, the driver auto-dispatches mandatory roles instead of asking ‘shall I continue?’ between slices.
Before the next slice, the tracked worktree must be clean. Unrelated changes may be auto-preserved via reversible stash when safe.
For eligible regression slices, verification reruns at the locked basis commit in a disposable worktree—workflow-layer proof the bug existed on the basis.

#6 Proof Verification

Evidence, not prose

Evaluation, verification, and governed closure

Verification evidence is a durable, structured artifact, not a chat summary. Read-only evaluators share a four-dimensional rubric, and each dimension receives pass, concern, or fail.

01

Contract coverage

Does the implementation satisfy the locked acceptance criteria and declared surfaces?

02

Correctness risk

What could break, regress, or behave unexpectedly given current evidence?

03

Verification evidence

Were deterministic checks run, recorded, and fresh enough to support the verdict?

04

Docs / state parity

Do documentation, canonical state, and repo truth still align?

Stop waves: Multiple independent stop-judge subprocesses may need to agree that work may stop on the current HEAD. Stop-wave epochs allow re-evaluation when reconciliation changes canonical truth without creating a synthetic commit. On closure, removing `.agent/` is expected, not anomalous.

#7 Choice Two Modes

Workflow mode vs ordinary chat

Explicit opt-in preserves direct assistance

The design deliberately preserves two modes. Workflow mode adds overhead only when resumability, review trails, and governed closure are worth the cost.

Mode

Behavior

Ordinary chat

Quick edits, Q&A, brainstorming, multi-file work without workflow overhead.

Direct repo edits allowed. No role dispatch. No workflow protocol loaded.

Workflow mode

Resumable missions, review/audit rounds, canonical state, confirm-first boundaries.

Explicit entry. Fail-closed startup synthesis. Role dispatch. Sticky continuation until a stopping posture.

Controls

Start / resume — enter or continue from saved state
Park — pause for ordinary direct edits; forces reground on resume
Cancel — close a stopped or parked workflow

#8 Build Implementation

From specification to implementation

How this design is implemented in Cursor

This page describes the architecture in abstract form. The letscook Cursor plugin turns that architecture into a working workflow mode for long-running coding tasks.

Design vs. implementation: the control plane is the model; letscook is one concrete realization of it. The invariant ideas stay the same, while command names, file layout, and host integration details remain implementation choices.

Quickstart

Customize → import letscook plugin
Reload Cursor → enable plugin + MCP
/cook add login redirect handling and the missing redirect tests

Design surface

letscook implementation

Explicit workflow entry

A governed long-running mode should be opt-in and confirm-first.

`/cook` resolves workspace context, synthesizes a startup handoff, and waits for `confirm_cook_handoff` (Start/Cancel; on main checkout, an isolation gate) before the six-role MCP loop begins.

Resume, pause, and close

Lifecycle control should stay explicit instead of being hidden in chat momentum.

`/cook resume`, `/cook park`, and `/cook cancel` make continuation, pause, and closeout explicit.

Durable canonical state

Workflow state must survive compaction and session restarts outside conversation memory.

Repo-local `.agent/` files store the startup brief, plan, active slice, evidence, and stop state beside the worktree.

Role-separated execution

Implementation, evaluation, and closure should not collapse into one authority surface.

bootstrapper, regrounder, implementer, reviewer, auditor, and stop-judge run as distinct completion roles with bounded authority.

Governed verification and closure

Completion should depend on structured evidence and explicit stop criteria, not conversational confidence.

Built-in control-plane and stop verifiers, structured evidence, and fail-closed review/audit/stop rounds gate completion.

Role prompt implementation

Where the six role agents are actually constrained

The architecture diagram shows the division of labor. The concrete edit rights, forbidden actions, report formats, and handoff contracts live in the role prompts shipped by letscook. Read the full prompts if you want the source of truth; use the quick references if you want the shorter runtime brief.

Bootstrapper

Bootstraps or repairs local `.agent/**` helper files and canonical state, then hands off to the regrounder. It may not edit tracked product files or create commits.

Full prompt Quick reference

Regrounder

Reconciles plan, active slice, workflow state, and verification evidence against repo truth. It may not edit tracked product files, invoke downstream roles, or create commits.

Full prompt Quick reference

Implementer

The only role allowed to edit tracked product files, run slice verification, create the slice commit, and append the implementation record. It may not choose the next slice or silently rewrite the roadmap.

Full prompt Quick reference

Reviewer

Performs read-only structured review on one committed slice, with an explicit acceptability verdict and the smallest truthful follow-up slice when needed. It may not write canonical state or create commits.

Full prompt Quick reference

Auditor

Performs read-only project-level audit on remaining work, worktree cleanliness, backlog truthfulness, and canonical state freshness. It may not write canonical state or create commits.

Full prompt Quick reference

Stop-judge

Makes an independent read-only stop / no-stop judgment on current HEAD during the final stop wave. It may not write canonical state or create commits.

Full prompt Quick reference

What stays invariant

Durable out-of-band state, slice-based execution, explicit workflow entry, role separation, and fail-closed verification are design invariants. They are the architectural core, not just implementation quirks.

What is implementation-specific

The `/cook` command, the current `.agent/` file layout, Cursor plugin packaging, and MCP orchestration details belong to the current letscook implementation rather than the abstract design itself.

Practical guide

Where to look first

Different readers need different entry points. Use the implementation surfaces below based on whether you want to use the plugin, inspect the protocol, or understand orchestration details.

If you want to use it

Start with the plugin README. It explains when to use `/cook`, how workflow mode differs from ordinary chat, and how to install the letscook Cursor plugin.

If you want the runtime contract

Read the completion-protocol skill. It documents canonical `.agent/**` state, workflow commands, generated verifier scripts, mandatory dispatch, and fail-closed continuation rules.

If you want orchestration details

Use the cursor-orchestrator and cursor-worktree-cook skills. letscook runs the full workflow natively in Cursor via MCP, bundled agents, and optional worktree isolation.

Concrete details

The implementation goes further than the diagram.

The plugin ships commands, MCP tools, repo-local `.agent/` state, generated verifier scripts, bundled role agents, and the completion-protocol skill. It runs natively in Cursor with optional worktree isolation.

View the implementation on GitHub Read the plugin README Inspect the completion protocol See Cursor orchestration docs

#9 Honesty Trade-offs

What this is and is not

Pay the overhead only when drift is costly

Workflow mode adds latency, token overhead, and cognitive load. The payoff shows up when work spans sessions, review trails matter, false completion is costly, or mission drift has already appeared in chat-only attempts.

Not a cloud orchestrator

Everything is local, repo-scoped, and plugin-owned.

Not a replacement for chat

Direct implementation remains valid when workflow overhead is unnecessary.

Not a correctness guarantee

Roles and verifiers reduce risk and drift; they do not prove formal correctness.

Not host-agnostic by default

A concrete implementation binds to a specific agent runtime, subprocess isolation, and tool ecosystem.

Single-agent keep going

Low overhead, but no resumable control plane, authority blur, and weak closure.

Human PR workflow

Strong review culture, but not agent-native—no automatic dispatch or compaction recovery.

Cloud task queues

Scalable orchestration with external dependency and less git-native adjacency.

Prompt-only multi-agent

Flexible role play, but roles collapse without tool enforcement and canonical state.

Executable specification

Protocol behavior belongs in the release gate, not as incidental CI hygiene.

Regression suites should cover schema parity, evaluator calibration, stop-wave semantics, dirty-worktree policy, worktree-root boundaries, helper authority, and public documentation parity with runtime behavior.