Concepts

The core shapes: the four topologies, how the pieces relate, and how a template becomes a project.

The four topologies

The Engine wires a team one of four ways. Each is shown as an agent graph below. → §04 — Core Concepts

Hierarchical — a supervisor plans and delegates each step; workers report back. (fullstack-web)

flowchart TB
    HS[Supervisor]:::sup
    HW1[Worker 1]:::wrk
    HW2[Worker 2]:::wrk
    HW3[Worker 3]:::wrk
    HS -->|delegate| HW1
    HS -->|delegate| HW2
    HS -->|delegate| HW3
    HW1 -.->|reply| HS
    HW2 -.->|reply| HS
    HW3 -.->|reply| HS
    classDef sup fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF
    classDef wrk fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

Sequential — a pipeline; each stage builds on the previous and hands off.

flowchart LR
    SA[Stage 1]:::wrk
    SB[Stage 2]:::wrk
    SC[Stage 3]:::wrk
    SA --> SB --> SC
    classDef wrk fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

Roundtable — every agent answers the same prompt in parallel; later discussion rounds (default two in total) let each agent critique and reconcile against its peers' previous answers, and the orchestrator collects all responses.

flowchart TB
    RU((User)):::ext
    RA[Agent A]:::wrk
    RB[Agent B]:::wrk
    RC[Agent C]:::wrk
    RU --> RA
    RU --> RB
    RU --> RC
    classDef wrk fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A
    classDef ext fill:#D5C3B0,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

Single — one agent runs the ReAct loop alone. (quick-script)

flowchart TB
    SIA[Agent]:::wrk
    classDef wrk fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

Note

A fifth dispatch shape, dynamic-parallel, decides worker count at planning time and powers research-team.json. It is not promoted to a first-class topology — see §08 — Templates.

Template, Team, Agent, Project

How the nouns relate. A Workflow Template defines a Team (wired by a topology) of Agents (persisted as Role rows). Instantiating the template produces a Project, which owns the workspace, the container, and the per-project knowledge base, and runs the team.

flowchart TB
    WT[Workflow Template<br/>JSON blueprint]:::ext
    TEAM[Team<br/>wired by a Topology]:::comp
    AG[Agents<br/>persisted as Role rows]:::comp
    PROJ[Project]:::prim
    WS[Workspace<br/>bind-mounted directory]:::ext
    CT[Per-project container]:::ext
    KB[Knowledge base<br/>per-project collection]:::ext
    WT --> TEAM
    TEAM --> AG
    WT ==>|instantiated as| PROJ
    PROJ --> WS
    PROJ --> CT
    PROJ --> KB
    PROJ -.->|runs| TEAM
    classDef prim fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF
    classDef comp fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A
    classDef ext fill:#D5C3B0,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

→ §04 — Core Concepts · entity fields in the Schema Reference

From template to running project

Picking a template runs a fixed sequence: parse, clone the team block, scaffold directories, persist the project and its roles, provision a container, and — only if the template opts in — seed the knowledge base. Then the project opens in Unified Studio.

flowchart TB
    JSON[Template JSON<br/>embedded or user file]:::ext --> Parse[TemplateService parses + validates]
    Parse --> Build[BuildCreateRequest<br/>clones the team block]
    Build --> Scaffold[ScaffoldDirectories<br/>creates workspace folders]
    Scaffold --> Persist[ProjectService writes<br/>Project + Roles to PostgreSQL]
    Persist --> Container[Container provisioned]
    Container --> Seed{seedKnowledgeBase?}
    Seed -- yes --> KB[Knowledge seeder enqueued]
    Seed -- no --> Studio
    KB --> Studio([Project opens in Unified Studio]):::ext

    classDef ext fill:#D5C3B0,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

→ §08 — Templates