Builder

You have a problem. You know what you want a team of agents to do. You don’t want to hand-wire a workflow DAG, write five role prompts, figure out gate commands, and structure the handoff channels yourself.

So don’t.

cliq builder generate -m "Due diligence team that reads a data room from Google Drive, produces financial analysis, legal risk assessment, and a consolidated report, with a quality gate before delivery"

That’s it. One sentence. The builder reads your intent, designs a workflow DAG, writes every role prompt, adds quality gates with real shell commands, wires up connectors for external data, generates A2A metadata for discovery, validates the whole thing, and writes it to your current directory — ready to run.

✓ Team 'due-diligence-pipeline' created

  Path:   /Users/you/teams/due-diligence-pipeline
  Phases: 5
  Roles:  4

  Workflow:
    financial-analyst [standard] (root)
    legal-analyst [standard] (root)
    report-writer [standard] → depends on financial-analyst, legal-analyst
    quality-gate [gate] → depends on report-writer
    fixer [support section]

  Install: cliq team install /Users/you/teams/due-diligence-pipeline
  Then:    cliq assemble due-diligence-pipeline

From there:

cliq team install .
cd ~/src/my-project
cliq assemble due-diligence-pipeline
cliq req -m "Evaluate the Series B data room for Acme Corp"
cliq run

---

Setup

The builder needs an LLM provider to generate teams. Add a builder section to ~/.cliqrc/settings.json:

{
  "builder": {
    "provider": "google",
    "api_key": "AIza...",
    "model": "gemini-2.5-pro"
  }
}

Three providers are supported:

Provider	provider value	Default model	Best for
Google	"google"	gemini-2.0-flash	Fast generation, good value
OpenAI	"openai"	gpt-4o	Strong reasoning, reliable structure
Anthropic	"anthropic"	claude-sonnet-4-20250514	Nuanced role prompts, detailed analysis

You can override the provider or model on any command with --provider and --model:

cliq builder generate -m "..." --provider anthropic --model claude-sonnet-4-20250514

---

Generating a Team

The generate command is the builder’s main act. Give it a description — as brief or as detailed as you like — and it produces a complete, validated team.

From a sentence

cliq builder generate -m "TDD pipeline for a Node.js Express API with linting, type checking, and security audit"

The builder infers the right phases, dependencies, gate commands, and role prompts. It knows that a TDD pipeline needs an architect, a developer, a test gate with npm test, and probably a fixer support phase for when tests fail.

From a file

For complex teams, write a detailed spec and pass it with -f:

cliq builder generate -f team-spec.txt

From stdin

Pipe from scripts or heredocs with --stdin:

cat <<'EOF' | cliq builder generate --stdin
Content production pipeline for a technical blog.

Phases:
1. A researcher who gathers background material on the topic
2. A writer who produces a draft blog post (1500-2000 words)
3. A technical reviewer who checks accuracy and code examples
4. An editor who polishes prose and ensures consistent tone
5. A quality gate that verifies the final post meets our style guide

The researcher should read source material from a Google Drive folder.
The final approved post should be pushed back to Google Drive.
EOF

Dry run

Not sure what you’ll get? Preview without writing anything:

cliq builder generate -m "Security audit team" --dry-run

This shows the full file list, workflow DAG, and role names — but writes nothing to disk.

Output directory

The builder writes directly into the current directory (or the [path] argument if provided). Create a directory for your team first:

mkdir my-team && cd my-team
cliq builder generate -m "TDD pipeline for Node.js"

Or specify a path:

cliq builder generate -m "TDD pipeline for Node.js" ./my-team

If team.yml already exists in the target directory, use --force to overwrite:

cliq builder generate -m "..." --force

Naming

The builder picks a name from your description. Override it with --name:

cliq builder generate -m "..." --name my-custom-team

The --name flag sets the name field in team.yml — it doesn’t affect where files are written.

---

What Gets Generated

A single generate call produces an entire team directory:

./
├── team.yml         # Workflow DAG, phase definitions, A2A metadata
├── roles/
│   ├── architect.md
│   ├── developer.md
│   ├── reviewer.md  # Gate role with evaluation criteria
│   └── fixer.md     # Support phase role (activated by gate routing)
└── README.md        # Auto-generated overview

team.yml

The workflow definition includes correctly ordered phases, dependency edges, gate commands with real shell commands, and (when your description mentions external data) pull and push declarations:

name: tdd-express-api
description: TDD pipeline for a Node.js Express API with linting, type checking, and security audit.
tags: [code, tdd, nodejs, express, api]

use_when:
  - Building a new Express API endpoint or service
  - Adding features that require comprehensive test coverage
not_for:
  - Frontend-only changes with no backend component
  - Infrastructure or deployment tasks

workflow:
  phases:
    - name: architect
      type: standard
    - name: developer
      type: standard
      depends_on: [architect]
    - name: quality-gate
      type: gate
      depends_on: [developer]
      commands:
        - name: lint
          run: npm run lint
        - name: typecheck
          run: npx tsc --noEmit
        - name: tests
          run: npm test
        - name: security
          run: npm audit --audit-level=moderate
      max_iterations: 3
  support:
    - name: fixer
      type: standard

Role prompts

Each role gets a detailed prompt with identity, objective, context, deliverables, constraints, and handoff instructions. Gate roles describe evaluation criteria in plain language — the orchestrator automatically injects the verdict protocol at runtime:

# Role: Quality Gate

You are a senior QA engineer responsible for verifying that the implementation
meets all quality standards before release.

## Context
Read the implementation from the developer's outgoing channel and review it
against the architectural design.

## Gate Evaluation
Run the automated commands and review code quality:

- If ALL commands pass and the code follows the design:
  approve and proceed

- If tests fail or linting issues are fixable:
  route to fixer for remediation

- If the implementation has fundamental design flaws:
  escalate to a human

A2A metadata

Every generated team includes top-level A2A metadata fields, making it discoverable by other agents in A2A meshes:

tags: [code, tdd, nodejs, express, api]

use_when:
  - Building a new Express API endpoint or service
  - Adding features that require comprehensive test coverage
not_for:
  - Frontend-only changes with no backend component
  - Infrastructure or deployment tasks

---

Refining a Team

Generated teams are good. With a few rounds of refinement, they’re great.

Improve a role

The improve command takes an existing role and makes it sharper — more specific instructions, better-defined deliverables, concrete examples:

cliq builder improve my-team --role architect

Without any instruction, the LLM reviews the role in context of the full team and improves it using its own judgement. With an instruction, you direct the improvement:

cliq builder improve my-team --role developer --instruction "add error handling patterns and logging conventions"
cliq builder improve my-team --role reviewer --instruction "add OWASP top 10 security checklist"

The output shows what changed:

ℹ Improving role 'developer' — "add error handling patterns"...

ℹ Changes:
  Added structured error handling section with try/catch patterns,
  custom error classes, and logging conventions using Winston.

  Original: 45 lines, 2340 chars
  Improved: 72 lines, 3891 chars

✓ Role 'developer' updated in ~/.cliqrc/teams/@local/my-team/roles/developer.md

Use --dry-run to preview changes before writing.

Pipe longer instructions from stdin:

echo "Focus on making the deliverables section extremely specific, with exact file paths and content structure for each output file" | cliq builder improve my-team --role writer --instruction -

Analyse gaps

The gaps command is your team’s peer review. It examines the workflow structure, role prompts, and overall coverage, then suggests concrete improvements:

cliq builder gaps my-team

ℹ Analysing team 'my-team'...

ℹ 3 suggestion(s):

  1. [missing gate] Add integration test gate
     The pipeline runs unit tests but has no integration test phase.
     Tests may pass individually but fail when components interact.
     → suggested phase: integration-gate [gate]

  2. [workflow improvement] Parallelize independent analysts
     The financial-analyst and legal-analyst phases have no dependency
     on each other but are currently sequential. Running them in
     parallel would halve the pipeline time.

  3. [metadata enhancement] Add output definitions
     The team is missing output definitions. Adding them
     enables downstream A2A agents to understand what this team produces.

Each suggestion includes a type, explanation, and when applicable, a fully-defined phase and role that you can add manually.

Regenerate A2A metadata

If you’ve modified a team’s workflow or roles, regenerate the A2A metadata fields (tags, use_when, not_for) to keep them accurate:

cliq builder capability my-team

  A2A metadata:
    tags:    finance, legal, analysis, due-diligence
    use_when:
      - Evaluating a company for investment or acquisition
      - Performing regulatory compliance review
    not_for:
      - Real-time market trading decisions
      - Personal tax preparation
✓ A2A metadata updated in ~/.cliqrc/teams/@local/my-team/team.yml

---

Tutorial: Build a Research Team from Scratch

Let’s walk through the full builder workflow — from idea to running pipeline.

Step 1: Generate

You want a team that reads a Google Doc, researches the topic, writes a comprehensive analysis, and pushes the result to Google Drive.

mkdir research-team && cd research-team
cliq builder generate -m "Research team that pulls a question from a Google Doc, researches the topic using the document's context, writes a detailed analysis with citations, and pushes the final report to a Google Drive folder. Include a quality gate to verify completeness."

The builder produces a team with phases like researcher, writer, quality-gate, and a fixer support phase. The first phase uses a connector agent with sources for the Google Doc, and a later phase uses target_entries for Google Drive.

Step 2: Review

Look at what was generated:

cat team.yml

Read a specific role (team packages store one file per role under roles/):

cat roles/researcher.md

Step 3: Refine

Maybe the writer role is too generic. Sharpen it:

cliq builder improve research-team --role writer --instruction "emphasize structured arguments with evidence, include a methodology section, and require inline citations in [Author, Year] format"

Run a gap analysis:

cliq builder gaps research-team

If it suggests adding a fact-checker phase, you can add it manually with cliq team add-phase or regenerate with a more detailed description.

Step 4: Install, deploy, and run

cliq team install .
cd ~/src/my-project
cliq init
cliq assemble research-team
cliq req -m "What are the competitive dynamics in the enterprise AI agent market?" \
  --input source_document_url="https://docs.google.com/document/d/abc123/edit" \
  --input output_folder_url="gdrive://1NheCF5I0pB_c4SJ1s0EJhUbsQ7cyPmrE"
cliq run

The pipeline fetches the Google Doc, runs the research and writing phases, verifies quality, and publishes the final report to Google Drive — all automated, all from one command.

Step 5: Iterate

After a run, improve based on what you observed:

cliq builder improve research-team --role researcher --instruction "be more thorough about finding contrarian viewpoints"
cliq builder improve research-team --role quality-gate --instruction "add check for minimum word count of 2000"

Each improvement is instant. Reassemble, re-req, re-run.

---

Composing Teams

The builder can embed existing teams as sub-steps in a larger workflow. Reference installed teams by their @scope/name in your description:

cliq builder generate -m "CI pipeline that runs @acme/security-audit on the source, then @acme/perf-suite for benchmarks, then synthesizes both into a release-readiness report"

The builder resolves each referenced team from your local registry, injects its metadata (inputs, outputs, phases) into the LLM context, and generates:

• A type: team phase for each referenced sub-team
• A role-as-spec for each team phase — a requirement document that the sub-team executes against (not agent instructions)
• Correct $(dirs.*) path stitching so sub-team outputs are wired to downstream phases

How it works

1. The builder extracts @scope/name references from your intent
2. Each must be locally installed — if any are missing, the builder errors immediately
3. The LLM receives each team’s inputs, outputs (with scope), and phase structure
4. It generates team phases with role-as-spec content and correct path wiring
5. The validator enforces that only the referenced teams appear in the output

Role-as-spec

Team phases are different from standard phases. Their role file is a requirement specification passed to the sub-team via cliq req, not instructions for an AI agent. The builder writes them in spec voice:

# Security Audit

Scan the application source at $(dirs.project)/src/ for vulnerabilities.
Focus on high and critical severity findings only.

## Inputs
- **target**: $(dirs.project)/src/
- **severity**: high

## Expected Output
Write the full audit report to $(dirs.self)/reports/security-audit.md.
Include vulnerability count, severity breakdown, and remediation steps.

Path stitching

The builder’s primary value for team composition is correct $(dirs.*) wiring:

Variable	Usage
$(dirs.project)/	Project root — for source files and project-scoped deliverables
$(dirs.self)/	Sub-team’s local output directory — for intermediate artifacts
$(dirs.<phase-name>)/	Sibling team phase’s output — for cross-references

Downstream standard phases access sub-team output via $(dirs.<team-phase>)/path and receive an automatic channel handoff summary.

Requirements

• Referenced teams must be installed locally (cliq team install <path>)
• If no @scope/name references appear in your intent, team phases are disabled entirely
• The builder never proactively suggests team composition — it only follows explicit references

---

Tips

Be descriptive. The more context you give the builder, the better the output. “Code review team” produces something generic. “Code review team for a React TypeScript monorepo with Playwright e2e tests, focusing on accessibility compliance and performance budgets” produces something you can actually use.

Use --dry-run first. Especially for complex teams. Preview the structure before committing.

Iterate with improve. The first generation is a starting point. Two or three rounds of targeted improvements — with specific instructions — produce significantly better role prompts.

Run gaps after manual edits. If you’ve added phases or modified roles by hand, gaps catches structural issues you might have introduced.

Use -f for complex descriptions. For teams with many requirements, write the description in a file and pass it with -f. The builder handles multi-paragraph, detailed specifications.

Override models for quality. For critical teams, use a stronger model: --provider anthropic --model claude-sonnet-4-20250514 or --provider google --model gemini-2.5-pro. For quick experiments, the defaults are fast and cheap.

---

How It Works

Under the hood, the builder is a structured generation pipeline:

1. Team context resolution — If your intent references @scope/name teams, the builder resolves each from your local registry, extracts their metadata (inputs, outputs, scope, embedding-awareness), and prepares context for the LLM. If any referenced team isn’t installed, the builder errors before calling the LLM.

2. Prompt composition — Your description is combined with a comprehensive platform reference that teaches the LLM everything about cliq: phase types, channel conventions, signal protocols, connector semantics, gate verdicts, and the filesystem contract. When team context is present, it also includes sub-team metadata, role-as-spec writing rules, and $(dirs.*) stitching rules. The LLM doesn’t guess how cliq works — it’s told.

3. LLM generation — The composed prompt is sent to your configured provider. The LLM returns a structured JSON object containing the team name, description, A2A metadata, workflow phases (with dependencies, commands, connectors, team refs), and full role prompts (including role-as-spec for team phases).

4. Parsing — The raw LLM output is parsed and extracted into typed structures. The parser handles JSON embedded in markdown fences, trailing commas, and other common LLM output quirks.

5. Validation — Every generated team is validated before writing: phase names are unique and kebab-case, role names match phase names, gate phases have commands, dependencies reference real phases, support phases are referenced by gates, the DAG has no cycles, team phase refs match the resolved set, and team phase roles use spec voice (not agent instructions).

6. Write to disk — The validated team is written directly to the target directory as a team.yml, individual role files under roles/, and an auto-generated README.md.

The same engine powers improve (targeted role refinement), gaps (structural analysis), capability (A2A metadata generation), and the server-side A2A builder skills.

---

Command Reference

Command	What it does
cliq builder generate -m <text> / -f <file> / --stdin	Generate a complete team from a description
cliq builder improve <team> --role <name>	Improve a specific role with optional --instruction
cliq builder gaps <team>	Analyse a team for structural gaps and suggest improvements
cliq builder capability <team>	Generate or regenerate A2A metadata (tags, use_when, not_for)

All commands accept --provider <name> and --model <model> overrides. See the full CLI Reference for all options.