team.yml Reference

Exhaustive schema reference for every field recognized in team.yml. For conceptual guides, see Teams, Workflows, and Pull & Push.

---

Top-Level Fields

Field	Type	Description
name	string	Required. Scoped team name (@scope/name). Must be quoted in YAML.
description	string	Human-readable summary shown in cliq team list, A2A, and CliqHub.
version	string	Semver (e.g. 1.2.0). Managed by cliq team version. Required for publishing. See Versioning.
cliq_version	string	Minimum cliq version (semver range, e.g. >=1.0.0).
tools	string[]	External tools needed (e.g. ["git", "npm"]). Checked at startup. Default [].
tags	string[]	Tags for discovery (e.g. [code, git, tdd]). Default [].
inputs	InputDef[]	Template parameters used via $(inputs.key). Default [].
use_when	string[]	When this team is appropriate. Used for A2A routing. Default [].
not_for	string[]	When not to use this team. Used for A2A routing. Default [].
agents	Record<string, AgentDef>	Custom agent declarations, keyed by name. Default {}.
workflow	WorkflowDef	Required. The workflow — phases and optional support.

---

Inputs

Each entry in the inputs array defines a template parameter.

Field	Type	Required	Description
name	string	yes	Parameter name. Referenced as $(inputs.name) in the workflow.
description	string	no	Human-readable description. Shown in cliq req prompts and A2A metadata.

Every declared input must be referenced via $(inputs.key) somewhere in the workflow — unused inputs are a validation error.

inputs:
    - name: data_room_id
      description: "Google Drive folder ID for the data room"
    - name: company_name
      description: "Target company name"

---

Agents

The agents block is a map of agent name → agent definition. These agents are bundled with the team and resolved during assembly.

Field	Type	Required	Description
entry	string	yes	Path to the agent entry point, relative to the team directory.
env	string[]	no	Environment variable names the agent requires.

Built-in agents (cursor, claude-code, gemini, codex, hug) don’t need entries — they’re available by name. See Cliq SDK for building custom agents.

agents:
    openai-analyst:
        entry: agents/analyst/index.js
        env:
            - OPENAI_API_KEY

---

Workflow

The workflow key contains a phases array and an optional support array.

workflow:
    phases:
        - ...
    support:
        - ...

---

Phases

Each entry in workflow.phases defines a pipeline stage.

Field	Type	Default	Applies to	Description
name	string	(required)	All	Unique identifier. Determines the role file name (roles/<name>.md).
type	string	(required)	All	One of standard, gate, hug, exec, pull, or push.
depends_on	string[]	[]	All	Phases that must complete before this one starts. Creates DAG edges.
commands	CommandDef[]	[]	gate, hug, exec	Shell commands. Required for exec phases, optional for gates and hug phases.
max_iterations	integer	3	gate, hug	Maximum command-verdict-route loops before auto-escalation. Clamped to 1–5.
agent	string	(none)	standard, gate, hug	Override the runtime agent for this phase. Must be a built-in or declared in agents.
sources	SourceDef[]	[]	pull	External content to fetch. Required for pull phases.
targets	TargetDef[]	[]	push	Files to push externally. Required for push phases.
review	ReviewDef	(none)	hug	Human review configuration. Required on hug phases, not allowed on other types.
is_support	boolean	false	(internal)	Set automatically for phases in the support section. Do not set manually.

Type-specific constraints

Type	Agent	Role	Cmds	Iters	Sources	Targets	Review
standard	✓	✓	—	—	—	—	—
gate	✓	✓	opt	opt	—	—	—
hug	✓	opt	opt	opt	—	—	req
exec	—	—	req	—	—	—	—
pull	—	—	—	—	req	—	—
push	—	—	—	—	—	req	—

---

Commands

Each entry in a phase’s commands array defines a shell command.

Field	Type	Required	Default	Applies to	Description
name	string	yes	—	gate, hug, exec	Human-readable label. Must be unique within the phase.
run	string	yes	—	gate, hug, exec	Shell command. Exit 0 = pass, non-zero = fail.
if	string	no	—	gate, hug, exec	Condition command. If it exits non-zero, the command is skipped (treated as passing).
scope	string	no	"workspace"	gate, hug, exec	"workspace" or "repo". Controls where the command runs in multi-repo setups.
escalate_on_fail	boolean	no	true	exec only	When false, failures log as warnings without halting. Not allowed on gate or hug commands.

commands:
    - name: build
      run: npm run build
      scope: repo
      if: "test -f package.json"
    - name: tests
      run: npm test
    - name: changelog
      run: "test -f CHANGELOG.md"
      escalate_on_fail: false    # exec phases only

---

Sources (Pull)

Each entry in a pull phase’s sources array defines external content to fetch. See Pull & Push for source types, conversion rules, and authentication.

Field	Type	Required	Default	Description
url	string	yes	—	Source URL. Supports HTTP(S), Google Docs/Sheets/Drive, and SharePoint/OneDrive. Supports $(inputs.*) template variables.
name	string	yes	—	Slug for the pulled content. Lowercase alphanumeric + hyphens. Determines output path under .cliq/pull/.
format	string	no	"auto"	"auto" converts to Markdown/CSV where possible. "raw" stores the original binary.

sources:
    - url: "gdrive://$(inputs.data_room_id)"
      name: data-room
    - url: "https://example.com/report.pdf"
      name: market-report
      format: raw

---

Targets (Push)

Each entry in a push phase’s targets array defines a file to deliver externally. See Pull & Push for destination URIs, modes, and security.

Field	Type	Required	Default	Description
file	string	yes	—	Local file path relative to project root.
to	string	yes	—	Destination URI. Accepts gdrive://, gdoc://, sharepoint://, and standard web URLs. Supports $(inputs.*) template variables. Trailing / = container (for create), no trailing / = document (for append/replace).
mode	string	no	"create"	"create", "append", or "replace".
name	string	conditional	—	Display name for the created file. Required when mode is "create". Supports template variables.

targets:
    - file: reports/final-report.md
      to: "gdrive://$(inputs.output_folder)/"
      mode: create
      name: "$(inputs.company_name)-report-$(date)"
    - file: reports/final-report.md
      to: "gdoc://$(inputs.report_doc_id)"
      mode: replace

---

Review

The review block is required on hug phases and not allowed on other types. See Configuring a HUG for the full guide.

Field	Type	Required	Default	Description
reviewer	string | string[]	yes	—	Named reviewer(s) from hug.reviewers in settings.
artifacts	string[]	no	[]	Files or globs to include in the review page.
timeout	string	no	"24h"	Auto-escalate after this duration. Supports s, m, h, d suffixes.
remind_every	string	no	(none)	Re-notification interval. Omit to notify once.

review:
    reviewer: architects
    artifacts:
        - .cliq/design/architecture.md
        - reports/*.md
    timeout: 8h
    remind_every: 2h

---

Support Phases

Entries in workflow.support use the same fields as regular phases but with constraints:

• Must not have depends_on — support phases are only reachable through gate routing
• Use their real functional type (standard, gate, etc.)
• Sit outside the main DAG until activated

Field	Type	Required	Description
name	string	yes	Unique identifier. Must have a matching roles/<name>.md.
type	string	yes	Functional type: standard or gate.
agent	string	no	Agent override, same as main phases.

workflow:
    phases:
        - ...
    support:
        - name: git-resolver
          type: standard
        - name: security-fixer
          type: standard

---

Template Variables

Template variables can be used in pull url fields, push to and name fields.

Variable	Resolves to
$(inputs.key)	Value of input named key
$(req_key)	Requirement key (e.g. PROJ-123)
$(team_name)	Current team name
$(date)	Current date (YYYY-MM-DD)
$(timestamp)	Current date-time (YYYY-MM-DDTHH-MM-SS)
$(phase)	Current phase name
$(instance_id)	Cliq instance ID

---

Validation Rules

cliq team validate, cliq assemble, and cliq team publish all enforce these rules:

Rule	Error
Missing name	Team missing required "name" field
Missing type on phase	Phase 'foo' missing required "type" field
Invalid type	Phase 'foo' has invalid type "custom". Valid types are standard, gate, hug, exec, pull, and push.
Duplicate phase names	Duplicate phase name: 'foo'
Unknown dependency	Phase 'foo' depends on unknown phase 'bar'
Dependency cycle	Cycle detected involving 'foo'
No root phase	No root phase found
Exec without commands	Exec 'foo' must have at least one command
Exec with max_iterations	Exec 'foo' must not have max_iterations
Pull without sources	Pull phase 'foo' must have at least one source
Push without targets	Push phase 'foo' must have at least one target
Pull/push with commands	Pull phase 'foo' must not have commands
hug without review	Hug phase 'foo' must have a review block
review on non-hug	Phase 'foo' must not have a review block
escalate_on_fail on gate/hug	escalate_on_fail is only allowed on exec phase commands
Missing role file	Every non-exec, non-pull, non-push phase needs roles/<name>.md
Unknown agent	Phase 'foo' references unknown agent 'bar'
Duplicate command names	Gate 'foo' has duplicate command name: 'bar'
Unused input	Input 'key' is declared but never referenced
Invalid version	Invalid version 'abc' — expected semver (e.g. 1.0.0)

---

Complete Annotated Example

name: "@local/feature-dev-js"
description: "Feature development with git lifecycle for JavaScript/TypeScript projects"
version: "1.1.0"
cliq_version: ">=1.0.0"
tools: ["git", "npm"]

tags: [code, git, tdd, quality-gates, pr]

inputs:
    - name: output_folder
      description: "Google Drive folder ID for publishing deliverables"

use_when:
    - The task requires code changes delivered as a pull request
    - A buildable project with package.json exists in the repository

not_for:
    - Exploratory work without a clear implementation target
    - Repositories without an npm-based build system

agents:
    security-scanner:
        entry: agents/scanner/index.js
        env:
            - SCANNER_API_KEY

workflow:
    phases:
        - name: fetch-context
          type: pull
          sources:
              - url: "https://example.com/coding-standards.md"
                name: standards

        - name: git-setup
          type: gate
          depends_on: [fetch-context]
          commands:
              - name: clean-tree
                run: 'git status --porcelain | wc -l | xargs test 0 -eq'
                scope: repo
          max_iterations: 1

        - name: architect
          type: standard
          depends_on: [git-setup]

        - name: tester
          type: standard
          depends_on: [architect]

        - name: developer
          type: standard
          depends_on: [tester]

        - name: reviewer
          type: gate
          depends_on: [developer]
          commands:
              - name: build
                run: npm run build
                scope: repo
                if: "test -f package.json"
              - name: tests
                run: npm test
                scope: repo
                if: "test -f package.json"
          max_iterations: 3

        - name: human-review
          type: hug
          depends_on: [reviewer]
          review:
              reviewer: architects
              artifacts:
                  - reports/*.md
              timeout: 8h
              remind_every: 2h

        - name: git-finalize
          type: standard
          depends_on: [human-review]

        - name: git-verify
          type: exec
          depends_on: [git-finalize]
          commands:
              - name: pushed
                run: 'git ls-remote --heads origin $(git branch --show-current) | grep -q .'
                scope: repo
              - name: pr-exists
                run: "cliq tool run pr-exists"
                scope: repo

        - name: publish-summary
          type: push
          depends_on: [git-verify]
          targets:
              - file: reports/summary.md
                to: "gdrive://$(inputs.output_folder)/"
                mode: create
                name: "$(team_name)-$(date)"

    support:
        - name: git-resolver
          type: standard
        - name: hotfix-dev
          type: standard