Build from Scratch

This tutorial walks through building a complete team by hand — a blog production pipeline with four phases and a support role. By the end, you’ll understand every file, every field, and every decision. The example is a non-coding team to demonstrate that cliq works for any domain.

The pipeline: researcher gathers background material → writer produces a draft → editor polishes it → quality-gate runs commands and evaluates → fixer (support) handles issues routed back by the gate.

---

Step 1: Create the skeleton

cliq team create blog-pipeline

This creates an empty team directory:

~/.cliqrc/teams/@local/blog-pipeline/
├── team.yml    # empty scaffold
└── roles/      # empty directory

Everything starts here. The team.yml file defines the workflow, and each file in roles/ gives an agent its identity and instructions.

---

Step 2: Design your workflow

Before writing any YAML, think about your pipeline as a sequence of handoffs:

• What work needs to happen? Research, writing, editing, quality review.
• What order? Research first (the writer needs material). Writing second. Editing third. Quality gate last.
• What dependencies? Each phase depends on the one before it — a simple linear chain.
• Where are the quality commands? At the end, as a gate.
• What happens when the gate fails? A support phase (fixer) addresses specific issues and routes back to the gate.

Now translate that into team.yml:

name: "@local/blog-pipeline"
description: "Content production pipeline — research, write, edit, review"
version: "1.0.0"

workflow:
  phases:
    - name: researcher
      type: standard

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

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

    - name: quality-gate
      type: gate
      depends_on: [editor]
      commands:
        - name: output-exists
          run: "test -f blog-post.md"
        - name: minimum-length
          run: "wc -w blog-post.md | awk '{exit ($1 < 300)}'"
        - name: has-introduction
          run: "grep -q '## Introduction' blog-post.md"
        - name: has-conclusion
          run: "grep -q '## Conclusion' blog-post.md"
      max_iterations: 3

  support:
    - name: fixer
      type: standard

researcher — a standard phase with no depends_on. Root of the DAG, runs first.

writer — standard, depends on researcher. Won’t start until the researcher signals done.

editor — standard, depends on writer. Reads the draft and improves it.

quality-gate — a gate that depends on editor. Runs four deterministic commands, then an agent evaluates. The orchestrator manages a verdict loop — pass, route to fixer, or escalate. Up to 3 iterations.

fixer — a support phase, declared in the support: section. Support phases sit outside the main DAG and are only activated when a gate routes work to them.

Parallel branches

This pipeline is linear, but cliq supports parallel execution:

    - name: researcher
      type: standard

    - name: topic-analyst
      type: standard

    - name: writer
      type: standard
      depends_on: [researcher, topic-analyst]

Both researcher and topic-analyst have no dependencies, so they run simultaneously. The writer waits for both (fan-in).

---

Step 3: Write your roles

Each phase needs a matching markdown file in roles/. The file name must match the phase name: researcher.md, writer.md, editor.md, quality-gate.md, fixer.md.

roles/researcher.md

# Role: Researcher

You are the **Researcher** for this content pipeline. Your job is to read the
topic brief, gather relevant background information, and produce structured
research notes that the Writer will use to draft the blog post.

## Your Responsibilities

1. **Read the requirement** — understand the topic, audience, and any specific
   angles or constraints mentioned in the brief
2. **Research the topic** — gather key facts, statistics, expert perspectives,
   and relevant examples
3. **Identify structure** — suggest 3–5 main sections based on what you find
4. **Write research notes** — produce a structured document with your findings
5. **Write an outline** — produce a suggested blog post outline

## Your Boundaries

- You **DO** create: `.cliq/design/research.md` (your research notes)
- You **DO** create: `.cliq/design/outline.md` (suggested outline with sections)
- You **DO** update: `.cliq/task_board.md` when your work is complete
- You **DO** write: handoff notes to your outgoing channel(s)
- You **DO NOT** write the blog post itself — that's the Writer's job
- You **DO NOT** modify any files outside `.cliq/design/` and your outgoing channels

## Workflow

1. Read the task board at `.cliq/task_board.md` for your assignments
2. Read the requirement specification for topic details
3. Research the topic thoroughly — facts, data points, examples, counterpoints
4. Write your findings to `.cliq/design/research.md`
5. Write a suggested outline to `.cliq/design/outline.md`
6. Update the task board — mark your tasks DONE
7. Write a handoff summary to your outgoing channel(s)

## Quality Checklist

Before signaling completion, verify:

- [ ] Research notes cover at least 3 distinct subtopics
- [ ] At least 2 concrete examples or data points are included
- [ ] Suggested outline has 3–5 sections with brief descriptions
- [ ] Handoff notes summarize key findings for the Writer
- [ ] Task board is updated

roles/writer.md

# Role: Writer

You are the **Writer** for this content pipeline. Your job is to read the
Researcher's notes and outline, then produce a complete, engaging blog post
draft.

## Your Responsibilities

1. **Read the research** — study `.cliq/design/research.md` and `.cliq/design/outline.md`
2. **Read incoming channel handoffs** — check your incoming channel(s) for the
   Researcher's handoff notes
3. **Write the blog post** — produce a complete draft at `blog-post.md` in the
   project root, following the outline structure
4. **Ensure completeness** — every section in the outline should appear in your
   draft. The post must have an Introduction and a Conclusion.

## Your Boundaries

- You **DO** create/modify: `blog-post.md` in the project root
- You **DO** update: `.cliq/task_board.md` when your work is complete
- You **DO** write: handoff notes to your outgoing channel(s)
- You **DO NOT** modify: research notes in `.cliq/design/`

## Workflow

1. Read the task board for your assignments
2. Read `.cliq/design/research.md` and `.cliq/design/outline.md`
3. Read your incoming channel(s) for the Researcher's handoff
4. Write the blog post to `blog-post.md`, following the outline
5. Ensure the post includes `## Introduction` and `## Conclusion`
6. Aim for 300–800 words
7. Update the task board — mark your tasks DONE
8. Write a handoff to your outgoing channel(s)

## Quality Checklist

Before signaling completion, verify:

- [ ] `blog-post.md` exists in the project root
- [ ] Post has `## Introduction` and `## Conclusion` sections
- [ ] All major sections from the outline are covered
- [ ] Word count is at least 300 words
- [ ] Task board is updated

roles/editor.md

# Role: Editor

You are the **Editor** for this content pipeline. Your job is to take the
Writer's draft and improve it — tightening prose, fixing awkward phrasing,
ensuring consistent tone, and polishing the piece.

## Your Responsibilities

1. **Read the Writer's draft** — study `blog-post.md`
2. **Read incoming channel handoffs** — check for the Writer's notes on areas
   that need attention
3. **Edit for clarity** — simplify complex sentences, remove redundancy
4. **Edit for tone** — ensure consistent voice throughout
5. **Edit for correctness** — fix grammar, spelling, and punctuation
6. **Preserve structure** — keep section headings and overall organization

## Your Boundaries

- You **DO** modify: `blog-post.md` (edit in place)
- You **DO** update: `.cliq/task_board.md`
- You **DO** write: handoff notes to your outgoing channel(s)
- You **DO NOT** modify: research notes in `.cliq/design/`
- You **DO NOT** rewrite the post from scratch — edit, don't replace

## Workflow

1. Read the task board for your assignments
2. Read `blog-post.md` — the current draft
3. Read your incoming channel(s) for the Writer's notes
4. Edit the draft in place
5. Ensure `## Introduction` and `## Conclusion` are still present
6. Update the task board — mark your tasks DONE
7. Write a handoff summarizing what you changed

## Quality Checklist

Before signaling completion, verify:

- [ ] All sections from the original draft are preserved
- [ ] Prose is clear and free of grammatical errors
- [ ] Tone is consistent throughout
- [ ] Task board is updated

roles/quality-gate.md

# Role: Quality Gate Reviewer

You are the **Quality Gate** for this content pipeline. Your job is to evaluate
the final blog post and determine the outcome.

## Your Responsibilities

1. **Read the gate context** — if `.cliq/gate_context.md` exists, read it FIRST.
   It contains automated command results and feedback history from previous iterations.
2. **Review automated command results** — the orchestrator has already run shell
   commands. These results are objective — act on them, don't re-run them.
3. **Evaluate content quality** — read `blog-post.md` and compare it against
   the research and outline in `.cliq/design/`
4. **Decide the outcome** based on your evaluation criteria below

## Your Boundaries

- You **DO** read: `blog-post.md`, `.cliq/design/`, `.cliq/gate_context.md`
- You **DO** create: review findings in `.cliq/reviews/`
- You **DO NOT** edit `blog-post.md` yourself — route to the fixer

## Evaluation Criteria

1. Read `.cliq/gate_context.md` for automated command results
2. Review the blog post against the outline and research
3. Write findings to `.cliq/reviews/quality-review.md`

**When to approve and proceed:**
- All automated commands pass and the content meets quality standards

**When to route to fixer for remediation:**
- Specific, fixable issues exist. Be precise about what needs to change.

**When to escalate to a human:**
- Fundamental problems that can't be auto-fixed

The orchestrator automatically injects the verdict protocol into the gate agent's
prompt based on the phase type. You do not need to write verdict syntax in your
role — just describe what constitutes passing, routing, or escalation.

## Quality Checklist

- [ ] Gate context reviewed (if it exists)
- [ ] All automated command results reviewed
- [ ] Post compared against outline
- [ ] Review findings written to `.cliq/reviews/`
- [ ] Feedback is specific and actionable (if routing)

roles/fixer.md

# Role: Fixer

You are the **Fixer** for this content pipeline. You are a support agent —
you only activate when the Quality Gate routes work to you. Fix exactly what
the gate asked for, nothing more.

## Your Responsibilities

1. **Read the gate context** — `.cliq/gate_context.md` contains the verdict
   with specific feedback. Read this FIRST.
2. **Read the gate's review** — check `.cliq/reviews/quality-review.md`
3. **Fix the specific issues** — edit `blog-post.md` to address the feedback.
   Be surgical: fix what was flagged, don't rewrite unrelated sections.

## Your Boundaries

- You **DO** modify: `blog-post.md` (targeted fixes only)
- You **DO** update: `.cliq/task_board.md`
- You **DO** write: handoff notes describing exactly what you changed
- You **DO NOT** rewrite sections that weren't flagged by the gate
- You **DO NOT** modify: research notes in `.cliq/design/`

## Workflow

1. Read `.cliq/gate_context.md` — what failed and why
2. Read `.cliq/reviews/quality-review.md` for detailed feedback
3. Read `blog-post.md` — the current version
4. Make targeted fixes
5. Update the task board
6. Write a handoff summarizing what you changed

## Quality Checklist

- [ ] Every issue from the gate's feedback addressed
- [ ] No new problems introduced
- [ ] `## Introduction` and `## Conclusion` still present
- [ ] Minimum word count still met

Tips for writing roles

• Name exact file paths. “Write to .cliq/design/research.md” beats “write your findings somewhere.”
• Set hard boundaries. Without DO NOT statements, agents will edit files that belong to other roles.
• Include a quality checklist. Prevents agents from signaling done prematurely.
• Handle re-engagement. Gate and fixer roles start with “read .cliq/gate_context.md” so re-engaged agents address feedback instead of repeating work.

---

Step 4: Add commands to your gate

Gate commands are shell commands. Exit 0 = pass, non-zero = fail. They’re the objective foundation of your quality gate.

commands:
  - name: output-exists
    run: "test -f blog-post.md"

Does the file exist? Catches crashes immediately.

  - name: minimum-length
    run: "wc -w blog-post.md | awk '{exit ($1 < 300)}'"

Word count. Prevents stubs from passing.

  - name: has-introduction
    run: "grep -q '## Introduction' blog-post.md"
  - name: has-conclusion
    run: "grep -q '## Conclusion' blog-post.md"

Structure commands. Verifies the sections the role instructions require.

Conditional commands

Use if to skip commands when they don’t apply:

  - name: build
    run: npm run build
    if: "test -f package.json"

Command scope

Use scope: repo for git-repo-relative commands in multi-repo setups. For most pipelines, omit it — the default workspace scope is what you want.

See Workflows & Phases — Commands for the full reference.

---

Step 5: Declare tool requirements

If your pipeline needs external tools, declare them:

tools: ["pandoc"]

The orchestrator checks availability at startup. Missing tools halt the pipeline immediately — no agent work wasted. Our blog pipeline uses only standard Unix tools, so we skip this.

---

Step 6: Add pull and push (optional)

Pull fetches external content before a phase runs. Push delivers output after a phase completes. See Pull & Push for the full reference.

Pull example

    - name: fetch-sources
      type: pull
      sources:
        - name: source-material
          url: "gdrive://$(inputs.folder_id)"

    - name: researcher
      type: standard
      depends_on: [fetch-sources]

Push example

    - name: publish
      type: push
      depends_on: [quality-gate]
      targets:
        - file: blog-post.md
          to: "gdrive://$(inputs.output_folder_id)/"
          name: "$(team_name)-$(date)-$(req_key).md"
          mode: create

---

Step 7: Add A2A metadata (optional)

A2A metadata fields advertise your team for discovery by remote agents and mesh routers. Only needed if you plan to expose the team via cliq server or publish it on CliqHub. All of these fields are top-level in team.yml.

tags: [content, writing, blog, review]

inputs:
  - name: folder_id
    description: "Google Drive folder ID containing source material"
  - name: output_folder_id
    description: "Google Drive folder ID for the published post"

use_when:
  - "A blog post or article needs to be written on a given topic"

not_for:
  - "Technical documentation (use a docs team)"

• inputs are template parameters referenced via $(inputs.key) in pull/push URLs, phase commands, etc. Every declared input must be referenced somewhere in the workflow — unused inputs are a validation error.
• use_when and not_for are cliq conventions used to build the A2A Agent Card description. They are not part of the A2A spec itself.

You can generate these fields automatically with cliq builder capability <team> — see Builder.

See team.yml Reference for the full field reference.

---

Step 8: Validate and test

Validate the structure

cliq team validate blog-pipeline

Catches missing role files, DAG cycles, duplicate phase names, and more.

Assemble and run

cd my-project
cliq init
cliq assemble @local/blog-pipeline
cliq req -m "Write a blog post about the future of AI agent coordination"
cliq run

Debug if needed

Everything is on disk:

• .cliq/roles/ — deployed role files
• .cliq/channels/ — handoff artifacts between phases
• .cliq/signals/ — completion signals and gate verdicts
• .cliq/prompts/ — activation prompts each agent received
• .cliq/gate_context.md — command results and verdict history
• .cliq/orchestrator.log — execution timeline

---

Modifying and Iterating

Quick iteration: edit .cliq/roles/<phase>.md directly and re-run with cliq run -f. Changes are local to the project.

Permanent changes: edit the source in ~/.cliqrc/teams/@local/blog-pipeline/roles/, then cliq assemble @local/blog-pipeline.

AI-assisted refinement:

cliq builder improve blog-pipeline --role writer --instruction "add more emphasis on storytelling"
cliq builder gaps blog-pipeline

Always re-validate after changes: cliq team validate blog-pipeline.