Core concepts

Ringmaster has a small vocabulary. Once these terms click, the rest of the product (and the rest of these docs) reads easily. Here they are, roughly in the order you meet them.

Workspace

A workspace is a folder on your Mac, usually a project or repository. When you point Ringmaster at a folder, it keeps everything it produces inside a .ring directory there: run history, artifacts, events, and metadata. Your work and the record of how it was made stay together, and you can have several workspaces open at once.

Project

A project is a stream of work inside a workspace. One workspace often carries several at once — a feature, a bug fix, an experiment — and a project keeps each one's runs separate and pins the short list of workflows it actually uses. Every workspace has a Default project that holds anything you haven't filed elsewhere (including runs from before you made any projects), and one project is active per window, scoping its Recent Runs, Search, and the runs you start. See Projects.

Workflow

A workflow is a repeatable process, written as a YAML file. It describes a sequence of stages that turn an idea into specs, plans, implementations, reviews, tests, whatever the process calls for. Because it's a plain file in your repo, a workflow versions alongside your code and travels with the project. Ringmaster ships thirteen built-in workflows, ordered simplest to most advanced; you can also write your own (see Authoring workflows).

Stage

A stage is the atomic unit of work: one prompt, one runtime invocation, one set of output files. Stages run in order, and a stage can consume the output of earlier stages, so a later stage sees what came before. A stage declares which runtime runs it, which model (optionally), what it consumes, what to validate, and whether it needs review.

Prompt

A prompt is the Markdown file a stage sends to its runtime, referenced by path from the workflow. A prompt named *.pml.md can carry YAML front matter declaring its inputs (with descriptions and defaults, filled into {{inputs.<name>}} placeholders) and outputs — self-documentation that the Prompt Library renders so you can browse every prompt in the workspace, see what it takes and produces, and spot broken ones before a run. See Prompt Library.

Run

A run is one execution of a workflow from start to finish. Each run gets its own directory under .ring/runs/, identified uniquely, holding every stage, attempt, and artifact it produced. Your recent runs are listed in the app so you can return to any of them.

Attempt

An attempt is one execution of a single stage within a run, numbered 001, 002, and so on. Re-running a stage never overwrites; it creates the next attempt. That's what lets you try a stage several times, compare the results, and pick the one you want without losing the others.

Execution and slot

Most of the time an attempt is one execution. But when a stage runs in a multi-agent mode, a single attempt contains several executions running side by side, one per agent. Each execution gets its own slot (a directory named like 001-claude-code, or the role name in specialist mode) so their outputs never mix. See Multi-agent execution.

Artifact

An artifact is a file a stage produces: specification.md, plan.md, output.json, anything. Each execution writes its artifacts into its own directory; nothing merges on its own. When you approve an attempt, its artifacts become canonical, the version downstream stages will consume.

Review gate and promotion

A review gate is the pause at the end of a stage where a human decides what happens next. You can approve an attempt, request a revision, or reject it. Approving an attempt promotes its artifacts to canonical. This is deliberate: Ringmaster won't carry unreviewed work downstream at the points you've marked as needing judgment. (A stage can opt out with review.required: false if you want it to auto-approve on a clean run.)

Validator

A validator is an automated check that runs against a stage's output: does the file exist, does this Markdown have the required sections, does this JSON match a schema. Each validator has a severity; a blocking failure prevents auto-approval, while lower severities just surface in the UI. Validators are how a stage refuses to pass malformed work downstream. See Validation.

Runtime

A runtime is the thing that actually runs a stage: a CLI agent (Claude Code, Codex, Copilot, Gemini, Kiro), a local model server (LM Studio, Ollama, vLLM, llama.cpp), or a hosted API (Gemini API, OpenRouter, or a custom OpenAI-/Anthropic-compatible endpoint). Workflows name runtimes by a short ID like claude-code or ollama. Because runtimes are interchangeable, you can swap one for another without touching the rest of the workflow. See Providers & runtimes.

Comparison and consensus

When several executions run in one attempt, Ringmaster builds a comparison, a side-by-side table of their status, validation results, timing, and token use. In consensus mode it adds a structural analysis on top: which sections every candidate agreed on, where they diverged, and how similar they are. The comparison is evidence for your review; Ringmaster never picks a winner for you. See Multi-agent execution.

Replay

Replay re-runs a recorded attempt, optionally against a different runtime or model, feeding it the exact original prompt and inputs. It's how you ask "what would a different model have done with the same task?" without rebuilding anything. See Replay.

Provenance

Provenance is the complete record behind an artifact: the workflow version, run, stage, and slot that produced it; the runtime and model; the prompt file; the inputs it consumed; the validation outcome; your review decision; and timestamps. Every artifact has it, and you can view or export it at any time. See Provenance, reports & metrics.