> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Teams, phases, agent types, roles (LLM only), depends_on, gates, and upstream outputs.

A Cliq **team** is a portable **manifest**: ordered **phases**, each bound to an **agent**. A **run** executes that team against your **inputs** (the requirement).

Coordination is **daemon-mediated**: phase outputs become run **artifacts** and are passed to later phases as **upstream**. Cliq does not coordinate work through a shared on-disk channel or signal layout.

Product story first? [What is Cliq?](/).

***

## Team

A team is identified by **scope** and **slug** (for example `@cliq/hello-world`). Its definition lives in the team catalog as a manifest (phases, agents, dependencies, optional role text for LLM phases).

You **install** / **assemble** a team into a workspace, then **run** it. The manifest is the playbook; the run is one performance with concrete inputs.

***

## Phase

A **phase** is one named step in the manifest:

```yaml theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
phases:
  - name: fetch
    type: standard
    agent: gdrive
    sources:
      - url: "{{inputs.folder}}"
        name: docs

  - name: write
    type: standard
    agent: cursor
    depends_on: [fetch]

  - name: check
    type: gate
    agent: cursor
    depends_on: [write]
    commands:
      - run: npm test
    max_iterations: 3
```

| Field | Meaning |
| - | - |
| `name` | Id used in `depends_on`, status, logs, upstream |
| `type` | `standard` (default), `gate`, `team`, or `map` |
| `agent` | Which registered agent runs this phase (not used for `team` / `map`) |
| `depends_on` | Predecessors that must finish first |
| `commands` | Shell checks (gates) or the command list for `exec` |
| `max_iterations` | Gate revision budget |
| `timeout` | Wall-clock phase limit in seconds (`-1` = none) |
| `team` | Nested team ref when `type: team` or `type: map` (map may use `{{item.team}}`) |
| `args` | Explicit inputs for nested `team` / `map` children |
| `over` / `over_file` / `over_field` / `key` / `concurrency` | Map fan-out fields |
| `sources` / `target_entries` / `action` | Connector-phase fields |
| `output` | Optional structured output schema |

There is no separate “job” object. The phase is the step; the **agent type** decides which inputs matter.

### Phase types

| `type` | What the daemon does |
| - | - |
| `standard` | Invoke the phase’s agent with upstream (+ that agent’s own inputs) |
| `gate` | Run optional `commands`, then ask a gate-capable agent for **PASS / ROUTE / ESCALATE** |
| `team` | Run another team **once** as one step |
| `map` | Run a nested team **N times** over a list (`over` or `over_file`; optional per-item `team`) |

See [Workflows & phases](/workflows) for map syntax and examples.

***

## Agents

An **agent** is a registered runtime the daemon can invoke. Every phase picks one with `agent: <name>`.

| `agent_type` | What it is | Driven by | Examples |
| - | - | - | - |
| **`llm`** | Model-backed work (API or coding CLI) | **Role** + requirement + upstream → prompt | `cursor`, `claude-code`, `codex`, `gemini`, `claude-api`, `gemini-api`, `openai-api` |
| **`exec`** | Deterministic command execution | **`commands`** | `exec`, `echo` |
| **`connector`** | External systems | **`action`**, **`sources`**, **`target_entries`**, credentials in settings | `jira`, `gdrive`, `s3`, `curl`, `confluence`, `zendesk`, `hubspot`, `datadog`, `git`, `mesh` |
| **`gate`** | Specialized gate runtimes | Gate / review config | `hug`, `auto-gate` |
| **`notify`** | Lifecycle notifications | Channel config in settings | `slack`, `email` |
| **`meta`** | Orchestration helpers | Nested team ref | `team` |

Switching `agent` changes *how* a step runs. It does not change the DAG.

### How agents are abstracted (SDK)

Invoke is **data in / data out** over the agent protocol. Context layers add only what each kind needs:

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
BaseContext          identity, requirement, settings, complete/error
  └── StandardContext   + upstream, + commands
        ├── LlmContext       + model, api_key, assembled prompt   ← uses role
        │     ├── CliContext    + binary / args for coding CLIs
        │     └── GateContext   + check_results, pass/route/escalate
        └── ConnectorContext + action, sources, targets, credentials
```

* **`LlmAgent`** builds a prompt from **role + upstream\_text + requirement**, then calls a model (or a coding CLI that wraps one).
* **`CliAgent`** extends `LlmAgent` — same prompt assembly, then runs a coding CLI tool.
* **`ConnectorAgent`** does not use role; it uses action/sources/targets and settings credentials.
* **`exec`** runs the phase’s `commands`; no role, no model.

The invoke payload may include an empty `role` string for every agent; **only LLM agents treat it as meaningful input**.

***

## Role (LLM agents only)

A **role** is the specialist brief for an **`agent_type: llm`** phase: who this agent is, what to produce, and what not to do.

* Declared as required input on LLM agent manifests.
* Carried on the run as role text for that phase (assembled into the LLM prompt with upstream and the requirement).
* **Not** a coordination surface — agents do not discover work by reading role files from a shared layout.

**Not used by** `exec`, connectors, notify agents, or nested `team` phases. Those use commands, sources/targets, or a team ref.

A good role is specific. “Implement the failing tests until they pass” beats “write code.” For LLM phases, tightening the role usually beats swapping models.

***

## Dependencies (`depends_on`)

`depends_on` encodes order. The daemon builds a DAG and starts a phase when every predecessor is done.

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
planner → writer → reviewer
```

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
                 ┌─→ design ──┐
intake ────────┤             ├──→ implement → review
                 └─→ research ┘
```

***

## Gates

A **gate** (`type: gate`) judges earlier work.

1. Optional `commands` run (exit `0` = check passed)
2. A gate-capable agent issues a verdict — typically an **`llm`** agent, or **`hug`** / **`auto-gate`**
3. The daemon acts on the verdict

| Verdict | Effect |
| - | - |
| **PASS** | Continue (or finish) |
| **ROUTE** | Re-run an earlier phase with feedback, then re-check (`max_iterations`) |
| **ESCALATE** | Stop for human intervention |

Only agents that can produce verdicts belong on gate phases (`llm` or specialized `gate` types).

***

## Outputs, upstream, artifacts

When a phase finishes, its result is stored on the **run** as a phase **artifact** (`output`: text + optional data).

The next invoke receives **upstream**: map of predecessor name → that output. Dependents do not re-read a chat transcript or pick up handoffs from a directory tree.

**phase completes → artifact on the run → dependents see upstream.**

***

## Inputs and requirements

The run still needs a **what**: the team's declared inputs, passed with `cliq run -i key=value`. Same team, different inputs → different outcomes; the process stays stable.

***

## Where it runs

The **daemon** (`cliqd`) executes the pipeline. The **CLI** (`cliq`) is a client (start run, status, logs). See [cliqd](/cliqd).

More machines → more daemons in a realm. Each daemon belongs to **exactly one realm** (or none, in [local mode](/local-development)). A daemon's runs show up in CliqHub once their team is on the realm's team list. Credentials: [Auth](/auth). Architecture: [Realms](/realms).

***

## Picture

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
Team (catalog manifest)
  └── phases[]
        ├── name / type / depends_on
        ├── agent ──► registry.agent_type
        │                 ├── llm        → role text (+ model settings)
        │                 ├── exec       → commands
        │                 ├── connector  → action, sources, targets
        │                 ├── gate       → hug / auto-gate
        │                 ├── notify     → channels
        │                 └── meta       → nested team
        └── output → run artifact → upstream for dependents

Run = inputs + each phase’s recorded output
```

***

## Next

| Goal | Go to |
| - | - |
| Try it | [Get started](/get-started) |
| Run a team | [Running teams](/running-teams) |
| Local dev loop | [Local Development](/local-development) |
| Agent catalog | [Agents](/agents) |
| Sign-in and tokens | [Auth](/auth) |
| Commands | [CLI](/cli) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.