GREENLOOP v2.4.0 / verification layer / MIT

GREENLOOP

Spec tools plan. Greenloop proves done.

A state-machine execution workflow for AI coding agents. It makes the agent persist state, converge before it edits, test its assumptions, and refuse completion until a verification harness exits cleanly.

$ curl -fsSL https://greenloop.violhex.workers.dev/install.sh | sh

Repo only: ... | sh -s -- --repo / both: --all / remove: --uninstall

The doctrine

Three laws against fog.

AI makes expansion effortless. Greenloop keeps the useful exploration, then forces it back into state, evidence, and one finite observable done.

IThe record

"If it exists only in context, it does not exist."

State, plan, memory, and worklog survive outside the chat window.

IIConsequence

"The model is free at thought. The system is strict at consequence."

The agent can reason broadly, but edits and completion pass through gates.

IIITermination

"One finite, observable done when."

Every loop must reduce into an artifact, decision, deletion, or verified state.

Reduction

The work is not anti-exploration. It is anti-dissolution.

Greenloop exists because AI sessions can generate more structure than they can actually verify. The process begins in the wide field, but it cannot end there.

The useful move is reduction: preserve the original intent, remove defensive complexity, and return to contact with the real target.

FieldExplore the request, context, constraints, and possible shape.
ShapeName the system, the risks, and the evidence that matters.
ReductionChoose the smallest real move that can be verified.
ArtifactCommit the work to files, state, tests, or a written decision.
Next fieldOnly expand again after the prior loop made contact.

The proof surface

Not a prompt. A verification layer.

Greenloop already has a public installer, agent bindings, state artifacts, enforcement hooks, an MCP server, and early comparative research. The next proof target is one real case study.

What exists today

The current product surface is enough to test the wedge honestly against real AI-assisted work.

Public static site and POSIX installer with checksum verification.

Native bindings for Claude Code, Cursor, Windsurf, Aider, Codex CLI, OpenCode, local models, and more.

Pre-edit gates, stop-time verification, state, plan, memory, and worklog artifacts.

Research battery covering drift, proxy verification, misleading evidence, and combined stress.

The method

Five stations, one record.

This is the Thyrsus grammar applied to agent work: discover, architect, instrument, evaluate, archive.

Discover

Frame the request, constraints, and what counts as evidence.

Architect

Design the workflow, agents, gates, and boundaries.

Instrument

Wire in capture, state, logs, and verification from the first move.

Evaluate

Run the loop, test the assumptions, and keep what fails.

Three steps to green.

Install the workflow, bind it to the agents already in your repo, then make completion observable.

Install

Run the curl command. It fetches the workflow files, verifies checksums, and installs a greenloop command.

Bind your agents

Run greenloop inside a repo. It detects your agent stack and writes native bindings without clobbering owned files.

Give the agent a task

Phase 1 initializes .greenloop/. The loop runs until the harness exits 0 and the worklog explains why.

repo/
|-- GREENLOOP.md                  contract, S/C/R, phases 0-10
|-- GREENLOOP-APPENDICES.md       orchestration and role library
|-- greenloop.state.schema.json   state template
|-- GREENLOOP-PROFILE-DESIGN.md   design domain profile
|-- AGENTS.md                     universal binding
`-- .greenloop/                   state / plan / memory / worklog

Inventory

Works with what you already run.

Each target gets its native instruction channel. Anything not listed still reads the universal AGENTS.md binding.

Claude CodeCLAUDE.md + hooks

Cursor.cursor/rules

Windsurf.windsurf/rules

Aider.aider.conf.yml read-list

Cline.clinerules

Roo Code.roo/rules

Continue.continue/rules

GitHub Copilotcopilot-instructions.md

OpenAI Codex CLIAGENTS.md

Gemini CLIGEMINI.md

OpenCodeAGENTS.md

Zed.rules

JetBrains Junie.junie/guidelines.md

OpenHands.openhands/microagents

Local LLMssystem-prompt rendition

Everything elseAGENTS.md convention

Enforcement

Instructions persuade. Hooks enforce.

On Claude Code, Greenloop can install gates that do not depend on model obedience.

What the gates hold

The hooks read the same state the workflow writes, and they fail closed.

PreToolUse gate: file edits are blocked until .greenloop/state.json exists.

Stop gate: the session cannot end while scripts/verify.sh exits non-zero.

GREEN: every done item satisfied, every harness check passed, no known unresolved error in scope.

Example run

[00:00] PHASE 0 CONTRACT read; State Law in effect

[00:03] PHASE 2 SPEC user_request stored; done-when falsifiable

[00:10] PHASE 5 PLAN each step has a verification hook

[00:14] PHASE 7 HARNESS scripts/verify.sh wired

[00:41] PHASE 9 VERIFY full harness clean

[00:43] STATUS: GREEN / exit 0

Field test

It works pasted into a chat box.

Greenloop is instructions first. Its minimum viable deployment is paste, and the workflow can still govern the session.

User / chatgpt.com

"Here is GREENLOOP.md. I want a site with the delivery and feel of a high-end Framer site, and it should take style changes that equally match."

Agent / Phase 2 to 4 before code

Refused to copy pixels. Reconstructed the upper layers first, the constraints that caused the reference to emerge, and returned the chain as the deliverable:

artifact -> structure -> rules -> constraints -> intent
|-- tokens.json scales inferred, not pixels copied
|-- motion-spec.md reveal timing, stagger, reduced-motion fallback
|-- component-spec.md shared rules as evidence of a system
`-- brand-spec.md the feeling and what was deliberately not done

Agent / Vision Lock

"No component may be implemented until the visual, motion, interaction, and emotional systems it expresses are explicitly described."

Get the files

Plain files. No lock-in.

Everything is markdown, JSON, shell, and TypeScript. Read it before you run it. That is the point.

docs/CASE-STUDY-001.mdA real task run through GREENLOOP end to end, with its state artifacts. docs/GREENLOOP-PROOF.mdVerification wedge, evidence summary, and next proof artifact. docs/REDUCTION-DOCTRINE.mdThe reduction thesis behind the workflow. workflow/GREENLOOP.mdThe core workflow, contract, S/C/R, and phases 0-10. workflow/GREENLOOP-APPENDICES.mdOrchestration, no-tools mode, and role library. workflow/GREENLOOP-PROFILE-DESIGN.mdDesign profile: extraction, constitution, and design GREEN. workflow/greenloop.state.schema.jsonCopy-to-initialize state template. cli/greenloop-inject.tsThe CLI: detection, bindings, TUI, and gates. install.shThe installer. Read it first.

Is this a lot of process?

Only when the task earns it. Greenloop compresses for small changes and expands for destructive, complex, or ambiguous work.

Is it safe to run in an existing repo?

Shared files get marker-delimited blocks. Unknown files are backed up before replacement. Re-running upgrades in place.

What does the CLI need?

Bun for the full TUI, or npx as fallback. The repo-only mode needs only sh and curl.

Can I change the workflow?

Yes. GREENLOOP.md is the source of truth. Edit it, version it, and your agents pick it up.