Discussions

A Discussion brings several Assistants (internally “agents”) together around a single topic. A dedicated Facilitator (the moderator Assistant) opens the conversation, picks who speaks next, evaluates progress after each turn, and finally writes a synthesis that wraps everything up.

Unlike a Workflow — a fixed graph of steps — a Discussion is steered live by the Facilitator. It decides how the conversation unfolds and when it is done.

Each turn is a fresh, headless Claude Code process. There are no long-lived sessions: the running transcript is fed back in as context on every turn, and state is checkpointed to the database each round so a discussion can survive a server restart.

When to use a Discussion

• Brainstorm several angles on an open-ended problem before committing.
• Review a plan, design, or piece of writing from multiple perspectives.
• Deliberate toward a well-reasoned position when there are trade-offs.

If you instead need a deterministic, repeatable pipeline, reach for a Workflow or Orchestration.

Formats

You choose a format when you create a Discussion. The format is woven into every prompt the Facilitator and participants receive, shaping tone and goal.

Roles

Every participant Assistant is assigned a role that tells it how to engage. Roles also color the turn cards in the live timeline.

Facilitator presets

A Facilitator is just an Assistant flagged isFacilitator = true whose persona (Personality) is injected verbatim as the moderator’s system prompt. That persona is what shapes how turns get chosen and how the final synthesis reads, so picking the right one matters more than it looks.

RondoFlow seeds eight built-in Facilitator presets as global Assistants, available to every workspace out of the box. Each one is a distinct moderation philosophy, tuned for particular formats, with a recommended model tier. They show up flagged “Built-in” and cannot be deleted.

You are not limited to the presets. You can create your own Facilitator (see Creating a Facilitator), optionally starting from one of the eight preset styles as a one-click template.

How a Discussion runs

The Facilitator-driven engine is a state machine. Each box below is a state; the Facilitator’s decision after every turn determines whether the loop continues or moves to synthesis.

setup
  → facilitator opening        (pick first speaker + opening question)
  → participant turn           (the chosen Assistant responds)
  → facilitator evaluation     (continue, or synthesize?)
       ├─ continue  → participant turn   (next speaker + new question)
       └─ synthesize / max rounds reached → synthesis
  → synthesis                  (Facilitator writes the conclusion)
  → concluded

How the Facilitator’s decision is parsed

The Facilitator is prompted to answer each opening and evaluation turn with a small JSON object (decision, nextParticipantId, question, optional synthesis, reasoning). That parsing is best-effort, not schema-enforced: the turn runs as an ordinary text completion (the CLI is not asked to validate against a JSON schema), and the engine extracts the decision heuristically — it strips any Markdown code fences, takes the text from the first { to the last }, and JSON.parses that slice.

If parsing fails or the object is missing required fields, the engine degrades gracefully rather than erroring:

• A failed opening falls back to the first active participant and a generic opening question.
• A failed evaluation continues round-robin while rounds remain, and synthesizes once they don’t.

Max rounds and turn limits

• Max rounds is configurable per Discussion (default 5, minimum 1). It is a hard ceiling: once the round count reaches it, the engine synthesizes regardless of what the Facilitator wants.
• Each participant turn has a timeout of about 2 minutes; each Facilitator turn (opening, evaluation, synthesis) about 90 seconds.
• If a participant times out or errors, the engine records a “timed out — no response” turn and keeps going rather than failing the whole Discussion.

Pause, resume, and crash recovery

• Pause takes effect cleanly between turns. The engine stores the upcoming participant and question, so Resume continues from exactly that next turn rather than restarting from the opening.
• State is checkpointed to the database after every round. If the server restarts mid-discussion, the recorded progress (round count and accumulated transcript) is not lost. The checkpoint is written into the discussion’s conclusion column as a [checkpoint:round=N/max] marker; the UI recognizes that marker and never displays it — only the real synthesis, written at the end, surfaces as the conclusion.
• Conclude can be forced at any time: the Facilitator synthesizes from whatever transcript has accumulated so far.

Creating a Discussion in the UI

Open Discussions from the top bar, then create one with the three-step wizard.

You can swap the Facilitator while the Discussion is still a draft (via the PATCH /api/discussions/:id/moderator route below).

Creating a Facilitator

A Facilitator is created as an Assistant with isFacilitator = true (POST /api/agents). There are two ways to make one:

• Inline in the wizard — the “New” button next to the Facilitator dropdown creates one from a name and description, with a generic facilitation persona.
• From the Facilitators panel — open it to manage all Facilitators. Its create form lets you start from any of the eight presets as a one-click style (which fills in the name, description, model, and full persona), or write your own persona from scratch. Built-in presets are badged and cannot be deleted; your own custom Facilitators can be removed there.

Watching it live

The Discussion panel streams the conversation as it happens:

• A round indicator (“Round 2 of 5”) and a status badge (Draft / Active / Concluded).
• Participant cards with the Assistant’s name and a colored role badge; long responses collapse with a “Show more” toggle.
• Facilitator cards (gavel icon) showing each decision and its reasoning.
• A highlighted Conclusion card once the Discussion concludes.

Controls along the top let you Start, Pause, Resume, Stop, and Export (download the conclusion as Markdown). The live updates arrive over Socket.IO via discussion:turn, discussion:moderator, and discussion:concluded events.

The conclusion

The synthesis is stored on the Discussion as its conclusion and rendered in the Conclusion card. From there you can Copy it to the clipboard or Download / Export it as a Markdown file. The full turn-by-turn transcript is also persisted as messages on the Conversation and is available through the API.

Discussions API

These routes provide an HTTP control surface over the same engine instances the live UI drives. All responses use the standard { success, data?, error?, meta? } envelope.

{
  "name": "Caching strategy review",
  "topic": "Should we add a Redis cache in front of Postgres?",
  "format": "deliberation",
  "moderatorId": "agent_facilitator_id",
  "maxRounds": 5,
  "participants": [
    { "agentId": "agent_a", "role": "participant" },
    { "agentId": "agent_b", "role": "devil_advocate" }
  ]
}

{ "agentId": "agent_c", "role": "observer" }

See the full API reference for the shared response envelope and error codes.

Related