Core concepts

Activities

Activities are workspace-scoped, reusable definitions of work. An Activity has a name, description, status, type-specific configuration, audit history, and an immutable type. Activities can be created directly or supplied inline when a Pipeline is created or updated. Pipeline-created Activities retain their Pipeline workspace as provenance for internal step resolution, while standalone Activities have no workspace association.

The API selects the configuration shape from the top-level type field. The config object does not include its own type discriminator. Activity statuses are active, disabled, and archived.

Activity Categories

Loop Activities

Loop Activities configure one or more model agents, stop conditions, and an output contract. An agent combines a Persona and one role. Personas supply instructions; model selection is resolved independently.

• generator: produces a candidate solution or proposed output;
• reviewer: evaluates a candidate and provides feedback for refinement;
• aggregator: synthesizes multiple proposals into a consolidated result.

The role cardinality is part of every loop Activity’s configuration contract.

Direct Loop

A direct_loop is an executable single-agent task. Its one generator returns a JSON operation plan that the CLI applies at its repository and Git checkpoints. It does not allow reviewer or aggregator agents.

Refinement Loop

A refinement_loop stores a multi-pass improvement definition. It requires one generator and one or more reviewers, without an aggregator. It creates a plan, collects reviewer approval after local application, and retries from a fresh repository snapshot when reviewers reject the change within max_iterations.

Roundtable Loop

A roundtable_loop is an executable multi-agent task. Each generator produces a proposal, then the aggregator synthesizes those proposals into the final JSON operation plan. Reviewers are not allowed. The CLI applies only the aggregator’s final plan, not the individual proposals.

Human Activities

Human Activities represent decisions or responses that require a person rather than model execution. They create regular persisted Activity runs with the human executor, awaiting_human_decision state, and submit_human_decision continuation action.

Approval

An approval Activity represents a human approval decision. Its configuration has no additional fields.

Quiz

A quiz Activity collects a human quiz response. Its configuration requires a quiz object that carries the quiz definition.

Activity Runs

Activities expose persisted runs. Each run identifies its owning Activity by activity_id; it does not expose a legacy loop identifier. Pipeline-run creation freezes the effective Harness for each runtime-executable Activity, preferring the Activity, Pipeline, then User scope; louie is the compatibility default. It also freezes each agent’s effective model with the same precedence. For CLI Harnesses, that model is supplied as immutable requested_model, while Personas provide instructions only. Human Activities use the built-in human execution mode and submit a terminal decision checkpoint.