Loops

A Loop is a named, reusable definition of goal-seeking, self-correcting, bounded work that the daemon owns, runs unattended, and always ends with one named outcome. It is the runtime's answer to "run this until it is actually done, and tell me honestly how it ended."

A Loop is not a script and not a chat session. What makes it a Loop is a contract — a goal, a way to verify the goal is met, and the conditions under which it stops — carried by every Loop, even one that finishes on its first pass.

The contract: goal → verify → stop

Every Loop answers four questions, and the daemon holds it to all four:

• What is the goal? The definition-of-done.
• How do we verify it? A verification gate — a project command, an agent judging against a rubric, or a human approval. Verification is project-agnostic.
• When does it stop? Structural stop limits: an attempt cap, a no-progress window, optional budgets, and a breadth ceiling.
• How does it end? Exactly one of six named terminal outcomes.

Iteration is simply what happens when verification says "not done." A single-pass linear body is still a Loop — one that finished on its first pass — and it still gains the contract, which is the value no plain task graph delivers.

Two nouns, nothing else

The workspace surfaces exactly two things under one Loops umbrella:

• Loops — the catalog of definitions, each with declared inputs, a goal, and last-run state.
• Runs — the executions, active and past, observed on the run page.

There is no third noun. Running a Loop means supplying its declared inputs, which produces a Run. There is no separate "work to run," no standing work-list to browse, and no "ready" state to manage.

A Loop is made of three parts

1. A contract — goal, verification, stop conditions, and the fixed set of named terminal outcomes.
2. A body — a static DAG of typed nodes the daemon runs to completion. Node classes are action, control, and source. The body's shape varies per Loop; not every Loop has tasks.
3. Typed declared inputs — the parameters a caller supplies to run it (string, number, boolean, file, agent, or ref).

The full data model lives in the DSL reference.

Loop vs. capability

A Loop and a capability are different artifacts, and Loops do not replace capabilities:

• A Loop is a deterministic runtime program the daemon owns and runs. It rides CompozyOS's existing durable foundations — the work queue, sessions, automation, network, and memory — rather than adding a second execution engine.
• A capability is an interpretive network artifact — what an agent offers to peers over Compozy Network. Capabilities stay interpretive; the network protocol does not carry Loop execution.

Compozy Network remains, by design, not a workflow engine: envelopes do not carry loop execution. The Loop domain lives entirely in the runtime.

Arrive and use

The common path never touches a graph. On a fresh CompozyOS home, the bundled spec-cycle extension is installed enabled, so its three first-party Loops can run directly — supply a couple of inputs and go:

• implement-tasks — implements already-authored tasks in dependency order. Each task run performs its focused validation and tracking updates before the Loop collects the results.
• orchestrate-tasks — delegates the same authored tasks instead of fanning out over them: an orchestrator agent spawns one bounded worker session per task, waits for it, checks the task file on disk, and stops the session before moving on.
• review-and-fix — asks the configured reviewer agent to inspect a named task, records its structured findings as .compozy/tasks/<task>/reviews-NNN/issue_NNN.md files, remediates complete artifact batches, and repeats until a new review generation returns no issues.

If you disable spec-cycle, those Loops, their default agents, and their artifact tools leave the catalog together. Later daemon starts and extension updates preserve that choice; CompozyOS does not silently re-enable it. Enabling it restores the package.

Authoring, configuring, and forking are an opt-in power ceiling, never the entry toll.

Three ways to commit

In this section

Manage from any surface

Every Loop capability — author, configure, run, observe, approve, cancel, or kill — is operable by an agent through structured non-UI surfaces. The compozy loop CLI, the Loops HTTP API, and the compozy__loop_* native tools all reach the same validators and writers as the web UI. Web-UI-only control would be incomplete by definition.