Documentation

Plans that get
argued, not generated.

Everything you need to understand SwarmStack: how a Session runs, the concepts underneath, the Products on the platform, and how to drive it from the web, the CLI, or MCP.

01
One brief in

You bring a problem. Intake interviews it into a frozen Brief.

02
Your team + AI argue it, live

Coworkers join from one link and contend with a swarm of AI specialists, round by round — in real time, on one shared Session.

03
A versioned plan out

A SwarmPlan with a Glossary, Decision Records, and the contention shown.

Platform 3 Products Session lifecycle Concepts CLI + MCP Architecture
01 · The platform

What SwarmStack is

SwarmStack is where a whole team plans with AI in real time. Several people — your coworkers by a free join code, and vetted experts you hire — work one shared, server-hosted Session at once, alongside a swarm of AI specialist personas, and argue one deliverable into shape by contention. Not one AI answering alone, and not one person driving a tool.

SwarmStack is the platform; Products are the desks on it. Each Product runs a Session where the room contends, then synthesizes a versioned deliverable. Crucially, the Session surfaces the contention — the points the participants disagreed on and where they landed — so you read a decision and the dissent that shaped it, the way you would after a good design review. The result was argued, not just generated.

Everything is versioned, tenant-isolated, and durable. The platform is one glossary and one architecture; the Products differ only in what they produce and how they read.

The core bet

One model answers in one voice and never flags what it left out. That missing dissent, not hallucination, is the quiet failure that breaks plans. SwarmStack's answer is to put more than one perspective in the room and make them disagree before anything gets synthesized. See One confident model is the failure mode.

02 · The Products

Three Products, one engagement shape

A Product either shares SwarmPlan's engagement shape (a Session with a different deliverable) or brings a genuinely different one. All three live today, and all three plug into the same tenancy, marketplace, and design system.

SwarmPlan turns a brief into a versioned software plan. SwarmRFP builds a buyer-side RFP with a weighted scoring rubric. SwarmSurvey runs a conversational survey — one link, an adaptive conversation per respondent, synthesized into a Readout — and is the first Product with a shape of its own.

03 · The lifecycle

Anatomy of a Session

A Session moves through the same arc whichever Product it belongs to: Intake establishes the Brief and the room, Rounds of contention iterate the deliverable, Synthesis merges each Round, and the Approval Gate signs it off. Then you turn the plan into work.

Intake

The brief gets interviewed into shape

The Orchestrator interviews the Creator (and any known collaborators invited up front) to establish the Brief, then proposes the room — the Personas and who should hold each seat. The Creator disposes. The Brief freezes when Intake ends.

Round 0…n

Specialists get tasked and contend

Each Round assigns a Task to every Participant. AI Personas run one-shot; human-held Personas and hired SMEs answer through a Task Interview. Where they disagree, Synthesis re-tasks them with conflict Tasks and re-opens the Round.

Synthesis

The argument is merged, not averaged

The Orchestrator merges the Round's contributions into the next SwarmPlan version, sharpens the Glossary, records Decision Records, and surfaces the contention — the points participants disagreed on and where they landed.

Approval

Every seat signs off

When Synthesis converges, the Approval Gate opens. Every Participant seat approves the SwarmPlan before the Session completes; a changes request opens a Revision Round.

Ship

Turn the plan into work

A converged Session becomes a PRD, sliced into a Work Breakdown of Epic → Story → Work Item, and published to GitHub or Jira as native issues — idempotently, so re-publishing re-syncs instead of duplicating.

The Orchestrator is not a participant in the chat — it is the server's state machine, invoking the model as a set of one-shot gates (Intake, the Persona Task, the Task Interview turn, Synthesis, Review). Each gate runs as a durable Scheduled Action, so a Session survives a restart mid-Round. Watch a real one end-to-end in the self-guided demo.

04 · Vocabulary

Core concepts

SwarmStack uses precise words for precise things. These are the ones you meet first; the full vocabulary — every term, with what to avoid calling it — lives on the Glossary.

TermWhat it means
SessionThe planning engagement a Creator starts around one problem. The top-level unit everything else belongs to.
BriefThe problem statement a Session is built around. Drafted in Intake, frozen for the rest of the Session's life.
PersonaA named planning role (SWE, QA, Security, …) assigned Tasks each Round. Usually an AI Participant; a human can take the seat instead.
OrchestratorThe server-side state machine that drives a Session and runs Synthesis — implemented as one-shot LLM gates, not a chatbot.
RoundOne Orchestrator iteration: Participants do Tasks, then the Orchestrator synthesizes.
TaskA unit of work assigned to exactly one Participant within a Round.
SynthesisThe gate that merges a Round's contributions into the next deliverable version, detects conflicts, and routes open questions.
ContentionThe record of what the Participants argued about and where they landed — surfaced, not smoothed over. The whole idea.
Decision RecordA first-class Session artifact capturing one architectural decision the gates surfaced; many per Session.
GlossaryA versioned Session artifact: the sharpened domain dictionary for the project being planned, built up by the gates.
SwarmPlanThe synthesized, versioned deliverable a SwarmPlan Session produces — one current version, updated under optimistic concurrency.
05 · Participants

Who is in the room

A Persona is a seat; a Participant is who holds it. Seats can be filled by a model or by a human, and both work the deliverable in the same Session. When AI hits its limit, you hire a real expert into the exact same room from the Marketplace.

And more than one human can be in a Session at once, in real time. Because a Session lives on the server rather than on any one person's machine, several people plan the same thing together: the Creator, collaborators invited by a free join code, and hired experts. During Intake, a brief-sync step mirrors the brief questions to every collaborator, waits for their answers, synthesizes one Brief, and raises any conflict to the Creator before it locks. There is one shared plan under optimistic concurrency, so the room never forks into copies that later have to be merged — the Team tier exists for exactly this: the whole room in one Session.

WhoRole
CreatorThe paying planner who starts the Session, drives Intake, runs the Rounds, and decides who holds each seat.
AI PersonaA specialist role filled by a model with a real stake — the security voice pushes on audit trails, the infra voice on what locks the database.
SMEA verified human expert (a Remote Human Planner) hired from the Marketplace for a flat per-session rate when a decision genuinely needs a human.
CollaboratorA peer the Creator already knows, invited by a free join code to hold a Persona and take part in the collaborative brief. Not paid, not verified.
What an SME can and cannot see

A hired expert sees only the Brief, their own assigned Task, and the synthesized deliverable — never other Participants' raw contributions, and never your raw source. Grounding an external expert's Task in a connected repo requires you to opt that connection in, and even then they receive AI-mediated answers about the source, never the source itself.

06 · Inputs

Bring your own context

A Session does not have to start from a blank Brief. You can seed it with material you already have, and you can let the swarm read a real codebase.

  • Baseline.One uploaded document becomes the SwarmPlan's first version, so the swarm iterates your existing draft instead of planning from scratch.
  • References. Read-only material the gates consult but never rewrite — as many as you need.
  • Source Lookup. An AI gate reaches into a connected repo, Confluence space, or Jira project during its run to pull context on demand. Nothing pulled is persisted, and raw source is never rendered to any human.
  • Clone Targets. The specific repositories (each at an optional ref) a Session reads from a connected GitHub App install, read with short-lived, read-only, repo-scoped tokens minted on demand.
  • BYOK.Route a Session through your own Anthropic key and it is off SwarmStack's bill — required whenever you attach a GitHub source.

The design is deliberate: SwarmStack never becomes a mirror of, or a leak path for, your source. Read the full posture on Trust and Security.

07 · Deliverables

Outputs & integrations

A Session produces three versioned artifacts — the SwarmPlan, the Glossary, and a set of Decision Records — and everything downstream derives from them.

From plan to shippable work

A converged SwarmPlan can be transformed into a PRD, which is sliced into a Work Breakdown: Epic → Story → Work Item. A Work Item is a tracer-bullet slice with acceptance criteria and blocked-by edges — the unit that maps to a GitHub Issue or a Jira sub-task.

Publishing

A Publication pushes the artifacts and/or the Work Breakdown to one connected destination through a Connector. Every pushed node is recorded as an External Object with a content fingerprint, so re-publishing is idempotent — it re-syncs the same issues instead of duplicating them. Pushes run only inside durable Scheduled Actions, never inline.

08 · Interfaces

CLI & MCP

SwarmStack is a web app and an MCP surface. From Claude Code you can create a Session, hold a Persona Task, invite a collaborator, and drive the engagement without leaving your terminal — the same server, the same Session, the same durable state.

# start a Session from a one-line brief
/swarmstack-create Plan a zero-downtime migration off our single Postgres box

# join an existing Session as a Remote Human Planner
/swarmplan-join<invite-or-join-code>

# work the Persona Task assigned to your seat
/swarmplan-task

The MCP tools cover the same verbs a marketplace expert or a creator needs — create, invite, join, poll, view, discuss, answer, complete — so a Task Interview persisted turn by turn on the server reads the same whether it was driven from the web or the CLI.

09 · Under the hood

How it is built

The reliability model is the load-bearing part of the product. Four disciplines carry it:

  • Tenant isolation by default. Every domain row carries a tenant id, and Postgres row-level security is forced on every domain table. The application role cannot bypass it; CI fails the build if any table is missing the policy.
  • The atomicity contract. Every state mutation runs in one Postgres transaction — lock, validate, update, audit, enqueue — and never calls an external API inline.
  • Durable side effects. Async work (an email, a payment, a payout, a timeout, an LLM gate) becomes a Scheduled Action row claimed by the Scheduler with atomic compare-and-set. Nothing important lives in a setTimeout, so nothing is lost on restart.
  • Prompt-injection defense. All Participant-authored text is wrapped in an untrusted-content envelope before any model sees it, and an append-only audit log records every state mutation for at least a year.

The full threat model, control catalog, and incident SLAs are on the Security page.

10 · Access

Plans & limits

A Creator's Plan Tier — free, pro, or team — bounds the shape of their Sessions, not a token allowance. SwarmStack bounds the cost of a Session by bounding its Session Envelope: its depth, model class, seat count, and number of Rounds.

  • Free is near-solo and capped at three lifetime SwarmPlans (the first on the managed key, then bring-your-own-key), sized so you still complete one full plan and see the contention.
  • Pro unlocks unlimited SwarmPlans, GitHub and Jira integrations, the Marketplace, and wider depth, models, seats, and Rounds.
  • Team is where the many-humans case lives — shared seats for the whole room in one Session.

See the full breakdown on Pricing.

11 · Next

Where to go next

Start with one problem you would not ship on one opinion.

Bring a brief. Watch a room of specialists argue it into shape, pull in a real expert when it matters, and leave with a plan you watched get argued.