Hello World

The best way to learn cliq is to run a pipeline and poke at every file it creates. @cliq/hello-world is a three-agent team — planner, writer, and reviewer — that produces a short article. It runs in about a minute, needs no external tools, and touches every core concept: workflows, roles, channels, gates, and signals. Before starting this tutorial make sure you have installed the official @cliq teams as detailed in the Quick Start guide.

Follow along command by cGommand.

Step 1: Create a project

mkdir hello && cd hello
cliq init

cliq init creates the .cliq/ directory. This is where all orchestration artifacts will live — prompts, handoffs, signals, logs, everything. Right now it’s mostly empty: just cliq.id (a unique instance identifier) and settings.json.

Step 2: Look at the team

Before you assemble anything, take a look at what you’re about to deploy. The @cliq/hello-world team lives in your cliq-teams clone and has this structure:

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

team.yml is the team definition — it declares the agents and how they connect. Here’s the full file:

name: "@cliq/hello-world"
description: "A minimal team that plans, writes, and reviews a markdown document. No external tools required — use this to learn how cliq teams work."
version: "1.0.0"

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

Let’s walk through it:

name and description — Metadata. The name is how you reference the team; the description shows up in cliq team list.
workflow.phases — Three phases that execute in dependency order.
planner is standard — it does its work and hands off to the next phase.
writer is standard with depends_on: [planner] — it waits for the planner to finish before starting.
reviewer is gate with depends_on: [writer] — a gate evaluates the preceding agent’s output rather than producing new work.
commands — Two shell commands the gate runs before the agent evaluates. The first verifies that output.md exists. The second verifies that it contains at least 50 words. If either command fails, the gate routes back to the writer without spending an agent turn.
max_iterations: 3 — The gate can route work back to the writer up to 3 times. After that, it escalates to you.

The roles/ directory contains one markdown file per phase. Each role file is the agent’s playbook — it tells the agent what to read, what to produce, and how to hand off. You’ll see these after assembly.

Step 3: Assemble the team

cliq assemble @cliq/hello-world

This copies the team’s workflow and roles into .cliq/. After assembly, the project is self-contained — it doesn’t need the team registry at runtime. Everything the agents need is local.

Take a look at what’s there now:

ls .cliq/roles/        # planner.md, writer.md, reviewer.md
cat .cliq/workflow.yml  # the deployed workflow

The roles are the agent playbooks. Open the planner’s role to see what it will do:

cat .cliq/roles/planner.md

You’ll find a responsibilities section that looks something like this:

Read and internalize the requirement spec

Produce a structured outline in .cliq/design/outline.md

Write a handoff note summarizing the plan for the writer

Signal completion

Every role follows this pattern: read inputs, produce artifacts, write a handoff, signal done. The roles are plain markdown — you can edit them, extend them, or replace them entirely.

Step 4: Provide a requirement

cliq req -m "Write a short article about why teamwork matters"

This resolves your requirement into a full task specification and builds the orchestration scaffolding. Here’s what it created:

.cliq/req_spec.md — The resolved requirement specification.
.cliq/prompts/ — Activation prompts for each agent, one per phase. These are the actual instructions each agent receives when it starts.
.cliq/channels/ — Handoff directories for each edge in the workflow DAG.
.cliq/task_board.md — A progress tracker that updates as agents complete work.

Look at the channels:

ls .cliq/channels/     # planner--writer/  writer--reviewer/

Each channel is a directory where one agent writes handoff notes for the next. The naming convention is sender--receiver. When the planner finishes, it writes a handoff.md inside planner--writer/. The writer reads that handoff before starting its own work.

Step 5: Run the pipeline

cliq run

cliq launches all three agents in a tmux session. They execute in dependency order:

Planner reads the requirement, thinks about structure, and writes an outline to .cliq/design/outline.md. Then it writes a handoff note for the writer in .cliq/channels/planner--writer/handoff.md summarizing the plan and key decisions. When done, it signals completion.
Writer waits for the planner to finish. Then it reads the planner’s handoff, reads the outline, and produces output.md in the project root — a complete article about teamwork. It writes its own handoff for the reviewer in .cliq/channels/writer--reviewer/handoff.md and signals done.
Reviewer (the gate) waits for the writer. First, the orchestrator runs the two automated commands: does output.md exist? Is it at least 50 words? If both commands pass, the reviewer agent evaluates the article against the original requirement and the planner’s outline. Three possible outcomes:
- PASS — The article meets the bar. Pipeline completes.
- ROUTE:writer — The article needs work. The writer gets specific feedback and tries again.
- ESCALATE — Something is fundamentally wrong. The pipeline halts for human intervention.

Step 6: Inspect the results

Once the pipeline completes, everything it produced is on disk:

cat output.md                                    # the final article
cat .cliq/design/outline.md                      # the planner's outline
cat .cliq/channels/planner--writer/handoff.md    # what the planner told the writer
cat .cliq/channels/writer--reviewer/handoff.md   # what the writer told the reviewer
ls .cliq/signals/                                # completion signals
cat .cliq/orchestrator.log                       # full execution log

Walk through each one:

output.md is the deliverable — the article the team produced.
.cliq/design/outline.md shows the planner’s thinking: the structure it designed before any writing happened.
.cliq/channels/planner--writer/handoff.md is the context that flowed from planner to writer. You can see exactly what instructions the writer received.
.cliq/channels/writer--reviewer/handoff.md is the context that flowed from writer to reviewer. The writer explains what it produced and any decisions it made.
.cliq/signals/ contains the completion signals — one per agent — showing the order things finished.
.cliq/orchestrator.log is the full timeline: when each agent started, when it finished, what the gate decided, how long each phase took.

Everything is on disk, everything is readable. No hidden state, no opaque APIs, no dashboards you need to log into. If you want to understand what happened, read the files. This transparency is cliq’s core design principle.

Step 7: Check status

cliq status
cliq status -v     # verbose — verdict history, timing, signals

cliq status gives you a summary: which phases completed, which are pending, what the gate decided. The -v flag shows the full picture — verdict history across iterations, per-phase timing, signal details, and current settings.

tmux Controls

Your pipeline runs inside a tmux session. Navigate between agent panes:

Shortcut	Action
`Ctrl+B` then arrow key	Switch between panes
`Ctrl+B` then `z`	Zoom current pane (toggle fullscreen)
`Ctrl+B` then `d`	Detach from session (agents keep running)
`tmux attach -t cliq`	Reattach to the session

Re-run After Failures

If a pipeline escalates or fails, fix the issue and run again:

cliq run           # auto-cleans if no real work was done
cliq run -f        # force re-run when agents completed some phases

You don’t need to re-run cliq req — the requirements haven’t changed.

What’s Next

Try a real engineering team — @cliq/feature-dev-js adds architect, tester, developer, and reviewer with TDD, git branching, and PR automation. Same commands, bigger pipeline.
Build your own — Copy hello-world and customize it, or generate a team from a description with cliq builder. See Team Development.
Explore capabilities — Git Integration, Integrations, Human Gates, Notifications.
Full reference — CLI Reference, Settings.