Team Development

cliq’s official teams cover common workflows, but the real power is building your own. A team is just a directory with a team.yml and a roles/ folder — you can create one in minutes.

This section covers the full developer experience: building teams, iterating on them, versioning, publishing to CliqHub, sharing via git, and extending teams with custom agents via the SDK.

---

Three paths to a team

Path	When to use it
Generate with Builder	Describe what you want in plain English. The Builder generates a complete team — workflow, roles, gate commands — in seconds.
Copy an Existing Team	An existing team is structurally close to what you need. Copy it and customize.
Build from Scratch	You want full control. Hand-craft every file. Best for learning how teams work and for non-standard workflows.

By default, teams are created in the current directory. Teams with a bare name go to @local/ when installed. Scoped names (e.g. @yourname/my-team) retain their scope. Once created, install and assemble like any team:

cliq assemble @local/my-team
cliq req -m "your requirement"
cliq run

---

Development lifecycle at a glance

Workflow	Key commands
Author	team new → add-role → gen-workflow → team install → team version → team publish
@local	team new → develop → team install ./path → assemble
Builder	builder generate → builder improve → team install → team publish

See Development Lifecycle for full step-by-step walkthroughs of each workflow.

---

Prerequisites

Before building a team, make sure you’ve completed Quick Start — cliq setup done, an agent installed, cliq doctor passing.

---

What’s in a Team

Every team is a directory containing:

my-team/
├── team.yml       # workflow definition — phases, dependencies, commands
└── roles/         # one markdown file per phase
    ├── planner.md
    ├── writer.md
    └── reviewer.md

team.yml defines the phases and how they connect. Each file in roles/ is an agent’s playbook — identity, responsibilities, boundaries, workflow steps. See Roles for the full anatomy, and Workflows & Phases for phase types, commands, and the gate verdict loop.

---

Quick Reference Checklist

Use this when building or reviewing a team:

• Team directory created (cliq team create or cliq builder generate)
• team.yml has name and workflow.phases
• Each phase has a name and type
• Each non-exec phase has a matching roles/<name>.md
• Gate phases have commands with shell commands (exit 0 = pass, exit 1 = fail)
• Support phases have no depends_on
• depends_on edges form a valid DAG (no cycles, at least one root phase)
• Role files include identity, responsibilities, boundaries, workflow steps, and quality checklist
• Role files specify exact file paths for reads and writes
• Gate roles include instructions for reading .cliq/gate_context.md
• cliq team validate passes with no errors
• cliq assemble + cliq req -m "..." + cliq run works end-to-end

---

What’s in this section

Page	Description
Building with Builder	AI-powered team generation — describe a team in plain English, generate, refine, analyse gaps.
Copying an Existing Team	Start from a team that’s close to what you need and customize.
Building from Scratch	Hand-craft a team step by step — full tutorial with a blog pipeline example.
Versioning	Semantic versioning for teams — how to bump versions and how immutability works.
Publishing	Publish to CliqHub, authenticate, share via git, CI/CD publishing.
Development Lifecycle	End-to-end recipes for author, @local, and builder workflows.
Cliq SDK	Build custom agents with @cliqhub/cliq-sdk — standard and gate agents, the execute function, testing, and examples.

When you’re ready to share your team with others, see Publishing for CliqHub or Sharing without CliqHub for git-based sharing.