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

---

Team Portability

Teams can be embedded as sub-teams inside larger workflows via type: team phases. When this happens, the sub-team’s agents run with their working directory set to the call frame ($(dirs.self)), not the project root. This isolation prevents parallel team phases from colliding on bare relative paths.

What this means for authors:

• Bare relative paths are fragile. A role that says “read src/app.ts” works fine at top level (where dirs.self equals the project root) but breaks when embedded as a sub-team (where dirs.self is the call frame).
• Use a $(dirs.*) prefix for portable paths. Pick the right one for the context: $(dirs.project) for project-root files, $(dirs.self) for orchestrator state and call-frame-local artifacts, $(dirs.<phase>) for outputs from a specific upstream phase.
• Bare paths in the call frame are fine. If a sub-team needs scratch files that stay in the call frame, bare relative paths work as intended.

Validation tooling:

Command	Behavior
cliq team validate	Warns about bare relative paths
cliq assemble	Warns about bare relative paths after assembly
cliq doctor --team <ref>	Warns about bare relative paths in team preflight
cliq team publish	Blocks bare relative paths — fix before publishing, or override with --force after confirming false positive

Example — portable role:

roles/analyzer.md

# Analyzer

Read the source code at $(dirs.project)/src/ for context.
Write your analysis to $(dirs.project)/reports/analysis.md.
Store intermediate work at $(dirs.self)/scratch/ (call-frame-local).

If you never plan to embed your team as a sub-team, bare relative paths work fine. But qualifying paths with the right $(dirs.*) prefix from the start makes your team portable and avoids surprises later.

---

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.