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)"] 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 xN"] 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 -->|"after unanimous judgments"| 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 and its structured evidence is recorded in canonical state.

Slice state transitions

stateDiagram-v2 [*] --> selected: regrounder selects slice selected --> in_progress: implementer begins in_progress --> committed: new git commit + evidence committed --> reviewed: reviewer pass reviewed --> audited: auditor pass audited --> done: acceptance criteria satisfied 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

Reviewer and auditor produce structured rubric reports. 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 Pi

This page describes the architecture in abstract form. @linimin/pi-letscook turns that architecture into a working Pi workflow mode for long-running coding tasks.

Design vs. implementation: the control plane is the model; @linimin/pi-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

pi install npm:@linimin/pi-letscook
/reload
/cook add login redirect handling and the missing redirect tests

Design surface

pi-letscook implementation

Explicit workflow entry

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

`/cook` enters workflow mode and synthesizes a startup brief from current context before Start or Cancel.

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.

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 package quirks.

What is implementation-specific

The `/cook` command, the current `.agent/` file layout, Pi extension packaging, and Cursor integration details belong to the current pi-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 package, inspect the protocol, or understand host integration details.

If you want to use it

Start with the package README. It explains when to use `/cook`, how workflow mode differs from ordinary chat, and how to install the package into Pi.

If you want the runtime contract

Read the protocol notes. They document the canonical `.agent/**` state, workflow commands, verifier behavior, calibration gates, and release-parity expectations.

If you need Cursor integration

Use the Cursor handoff and Cursor backend docs. pi-letscook supports both Cursor → Pi workflow handoff and optional Cursor-backed role execution.

Concrete details

The implementation goes further than the diagram.

The package ships real commands, repo-local state, verifier scripts, role prompts, and maintainer protocol notes. It also supports Cursor handoff and optional Cursor-backed role execution, making the control-plane model easier to inspect in practice.

View the implementation on GitHub Read the package README Inspect the protocol notes See Cursor integration 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 package-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.