How It Works

The Core Idea

One team, one requirement, one run.

A cliq team is a group of specialist AI agents, each with a defined role, connected by a workflow that governs who goes first, who hands off to whom, and what quality commands must pass before the work is considered done. You bring the requirement. cliq handles the rest.

Here’s the entire flow for the @cliq/hello-world team — the simplest built-in team, and the running example for this page:

cliq assemble @cliq/hello-world
cliq req -m "Write a short article about why teamwork matters"
cliq run

assemble pulls the team definition into your project. req sets the requirement and generates prompts. run launches the agents, coordinates handoffs, enforces quality gates, and writes the final result to disk. Three commands, and the pipeline does the rest.

Teams

A team is a portable directory: a team.yml file that defines the workflow, and a roles/ folder with a markdown file per agent. Teams encode methodology — the how of getting work done. You assemble a team into your project, and every run uses that same process.

Here’s what the hello-world team looks like on disk:

@cliq/hello-world/
├── team.yml
├── README.md
└── roles/
    ├── planner.md
    ├── writer.md
    └── reviewer.md

Three roles, one workflow file. That’s the entire team.

Teams come from several sources. The CliqHub registry lets you discover and install community teams with cliq team install hub://. The Builder generates custom teams from a natural language description. And @local is your personal namespace for teams you create yourself — see Team Development for a full walkthrough. For the complete reference on team structure and resolution, see Teams.

Roles

Each agent’s identity is a markdown file. It defines what the agent does, what files it reads and writes, and what it must not touch. Roles are the single biggest lever on agent behavior — a well-written role produces focused, reliable work; a vague one produces drift.

Here’s the opening of the hello-world planner role:

# Planner

You are the **Planner** — the first phase in the hello-world pipeline.
Your job is to read the requirement and produce a structured outline
that the Writer will use to draft the article.

## Responsibilities

- Read the requirement specification
- Analyze the topic and identify key themes
- Produce a structured outline at `.cliq/design/outline.md`
- Write a handoff summarizing the plan for the Writer

The role file continues with boundaries (what the planner must not do), workflow instructions (where to read input, where to write output), and a quality checklist. Every agent gets one of these — it’s the complete briefing for the job. See Roles for the full anatomy.

Workflows and the DAG

The workflow is defined in team.yml under workflow.phases. Each phase has a name, a type, and optionally a list of phases it depends on. Here’s the hello-world workflow:

workflow:
  phases:
    - name: planner
      type: standard

    - name: writer
      type: standard
      depends_on: [planner]

    - name: reviewer
      type: gate
      depends_on: [writer]
      commands:
        - name: output-exists
          run: "test -f output.md"
        - name: minimum-length
          run: "wc -w output.md | awk '{exit ($1 < 50)}'"
      max_iterations: 3

This says: planner runs first (no dependencies). Writer waits for planner to finish. Reviewer is a gate that waits for the writer, runs two automated commands, and allows up to three revision cycles before escalating.

These dependencies form a directed acyclic graph — a DAG. cliq resolves the graph automatically and runs independent phases concurrently. The hello-world team is a simple chain, but real teams can fan out and fan in:

                 ┌─→ [ux-designer] ──┐
[product-mgr] ──┤                    ├──→ [tester] → [developer] → [reviewer]
                 └─→ [architect] ────┘

Here, the product manager feeds both the UX designer and architect in parallel. The tester waits for both to finish before proceeding. cliq handles all of this from the depends_on declarations — you define the edges, and the orchestrator figures out the execution order. See Workflows for the complete reference.

Channels — How Agents Talk

Agents don’t share memory. They don’t call each other’s APIs. Instead, each edge in the DAG gets a dedicated directory under .cliq/channels/ where one agent writes a handoff for the next. The naming convention is {from}--{to}.

Here are the channels for the hello-world team:

.cliq/channels/
├── planner--writer/
│   └── handoff.md      # planner's outline notes for the writer
└── writer--reviewer/
    └── handoff.md      # writer's summary for the reviewer

The planner writes its handoff into planner--writer/. The writer reads it, does its work, and writes its own handoff into writer--reviewer/. The reviewer reads that. Each agent only sees its incoming channels — it has no visibility into other parts of the pipeline.

Why files? Three reasons. Transparency — you can read any handoff at any time to understand exactly what one agent told another. Auditability — every run leaves a complete record on disk, not in ephemeral memory. Debuggability — if an agent produces bad output, edit its incoming handoff and re-run just that phase to see what changes. See Channels & Signals for the full reference.

Signals — How the Orchestrator Knows

Signals are lightweight coordination files in .cliq/signals/. When an agent finishes its work, it writes a _done file. The orchestrator detects it and advances the pipeline by launching the next ready phases. Gate phases also produce verdict signals that tell the orchestrator whether to continue, route back, or escalate. See Channels & Signals for the full reference.

Gates — Quality Control

A gate is a special phase type that evaluates work before the pipeline can continue. It runs automated commands — shell commands that exit 0 on success — and then an agent reviews the results. The gate produces one of three verdicts:

PASS — the quality bar is met. The pipeline continues to the next phase.
ROUTE — the work needs revision. The gate sends feedback back to an earlier phase for another round.
ESCALATE — the gate cannot resolve the issue. The pipeline halts and a human needs to intervene.

In the hello-world team, the reviewer is a gate. It first verifies that output.md exists and meets a minimum word count (the two commands entries in the workflow YAML). Then the reviewer agent reads the article, compares it against the planner’s outline, and evaluates overall quality. If the article is solid, it passes. If the article is weak or misses key points, the reviewer routes back to the writer with specific feedback — and the writer revises. This loop can repeat up to three times (max_iterations: 3). If the article still doesn’t pass after three rounds, the reviewer escalates to you.

Gates are where cliq goes beyond a simple agent chain. They create feedback loops that let work improve iteratively, with clear criteria and a hard limit on retries. See Workflows for the complete gate configuration reference.

Human Gates (HUG)

A human gate is a special gate type that pauses the pipeline and waits for a real person to decide. cliq creates a web-based review page where the reviewer can inspect all artifacts, chat with an AI assistant for context, and submit a verdict using the same PASS / ROUTE / ESCALATE model. Reviewers are notified via configured notification channels when their input is needed, are taken through a review flow, and the pipeline resumes when they submit their review.

This bridges AI automation with human judgment — useful for compliance reviews, sensitive decisions, or anywhere a person must sign off before work continues. See Human Gate for setup and configuration.

Everything on Disk

No hidden state. No opaque runtime. No framework internals to decipher.

Prompts are markdown files in .cliq/prompts/. Handoffs are directories you can browse. Signals are files you can check. Logs are in .cliq/orchestrator.log. When something goes wrong, you don’t step through a stack trace — you look at the filesystem.

This isn’t a limitation — it’s the design. Every handoff is inspectable. Every signal is auditable. Every prompt is editable. Copy .cliq/ to a colleague and they can reproduce your exact run.

Beyond the Basics

cliq’s coordination model supports a broad set of capabilities beyond the core pipeline:

Git integration — branch creation, PR automation, merge conflict resolution. Git Integration
External files — pull content from Google Drive, SharePoint, or any URL into your workspace; push results back when done. Pull & Push
Notifications — Slack and Jira updates at pipeline events — start, complete, escalate, and more. Notifications
Integrations — GitHub, Bitbucket, Jira, Slack, Google Drive, SharePoint. Integrations
Docker isolation — run agents in containers for security and reproducibility. Docker
A2A protocol — expose teams as services other AI agents can invoke over HTTP. A2A
Builder — generate complete teams from natural language descriptions. Builder
CliqHub — discover, install, and share teams with the community. CliqHub
Kubernetes — run pipelines as Kubernetes Jobs for cloud-native deployment. Kubernetes

Try It

Now that you understand the model, run it yourself. The hello-world walkthrough takes about five minutes and covers assembly, requirements, execution, and inspection end to end.

Hello World Walkthrough