team.yml Reference

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

---

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 [].
outputs	OutputDef[]	Declared output parameters the team produces. 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"

---

Outputs

Each entry in the outputs array declares a named output the team produces. Outputs are metadata — they describe what the team delivers, used for A2A routing and documentation.

Field	Type	Required	Description
name	string	yes	Output name.
description	string	no	Human-readable description. Shown in A2A metadata and cliq team info.

outputs:
    - name: report
      description: "Final analysis report in Markdown"
    - name: findings
      description: "Structured findings as JSON"

---

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.
binaries	string[]	no	System binaries the agent requires (e.g. ["git"]). Checked at startup via cliq doctor.

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. Must not contain . characters. Determines the role file name (roles/<name>.md) for phases that require one.
type	string	(required)	All	One of standard, gate, or team.
depends_on	string[]	[]	All	Phases that must complete before this one starts. Creates DAG edges.
commands	CommandDef[]	[]	standard, gate	Shell commands. Required for agent: exec phases, optional for gates.
max_iterations	integer	3	gate	Maximum command-verdict-route loops before auto-escalation. Clamped to 1–5.
agent	string	(none)	standard, gate	Override the runtime agent for this phase. Must be a built-in or declared in agents. Use agent: hug for human review gates, agent: exec for command-only phases.
team	string	(none)	team	Required for team phases. Local ref (@acme/security-scan) or hub ref (hub://@acme/[email protected]). Not allowed on other types. Resolved recursively at assembly time.
inputs	Record<string, string>	{}	team	Static key-value pairs passed to the sub-team at req time. Validated against the sub-team’s declared inputs at assembly time.
action	string	(none)	standard	Connector action (e.g. get, list, create, update). Passed to the agent as ctx.action.
sources	SourceEntry[]	[]	standard	Connector data sources. Each entry has name, optional ref, url, headers, method, body.
target_entries	TargetEntry[]	[]	standard	Connector data targets. Each entry has name, file, optional ref, url, headers, method, mode.
model	string	(none)	standard, gate	Override the LLM model for this phase. Passed to the agent as ctx.model.
review	ReviewBlock	(none)	gate	Nested review configuration for human gates. Required when agent: hug. See HUG Review Block.
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	Team	HUG fields
standard	✓	✓	opt	—	—	—
gate	✓	✓	opt	opt	—	with agent: hug
team	built-in	✓	—	—	req	—

Standard phases with agent: exec require at least one command. Gate phases with agent: hug require the review: block with a reviewer field.

---

Commands

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

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

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

---

Sources

Each entry in a phase’s sources array defines a data source for a connector agent. Used with type: standard phases that have a connector agent. See Agent SDK — Connector Patterns for the full guide.

Field	Type	Required	Default	Description
name	string	yes	—	Identifier for the source. Used by the agent to write fetched content via ctx.write_file(name, content) to .cliq/files/{phase}/{name}.
ref	string	no	—	System-specific reference (e.g. Jira issue key, S3 path, Google Doc ID).
url	string	no	—	HTTP URL (used by the curl agent).
headers	Record<string, string>	no	{}	HTTP headers to include in the request.
method	string	no	"GET" ("POST" when body is present)	HTTP method override.
body	string	no	—	Request body (used by the curl agent). When present, method defaults to POST and Content-Type defaults to application/json.

sources:
    - name: ticket.json
      ref: PROJ-123
    - name: api-data.json
      url: "https://api.example.com/data"
      headers:
          Authorization: "Bearer ${API_TOKEN}"
    - name: search-results.json
      url: "https://api.example.com/graphql"
      body: '{ "query": "{ users { id name } }" }'

---

Target Entries

Each entry in a phase’s target_entries array defines a data target for a connector agent. Used with type: standard phases that have a connector agent. See Agent SDK — Connector Patterns for the full guide.

Field	Type	Required	Default	Description
name	string	yes	—	Identifier for the target.
file	string	yes	—	Local file path relative to the project root.
ref	string	no	—	System-specific destination (e.g. folder ID, document ID).
url	string	no	—	HTTP URL (used by the curl agent).
headers	Record<string, string>	no	{}	HTTP headers to include in the request.
method	string	no	"POST"	HTTP method override.
mode	string	no	"create"	Write mode: "create", "append", or "replace".

target_entries:
    - name: report
      file: reports/analysis.json
      url: "https://api.example.com/reports"
      method: PUT
      headers:
          Content-Type: application/json

---

HUG Review Block

Human review is configured by setting agent: hug on a type: gate phase and adding a nested review: block. See Configuring a HUG for the full guide.

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

- name: human-review
  type: gate
  agent: hug
  depends_on: [developer]
  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 role files, connector url fields, target_entries fields, and phase commands.

Variable	Resolves to	Available in
$(inputs.key)	Value of input named key	roles, connector entries
$(req_key)	Requirement key (e.g. PROJ-123)	roles, connector entries
$(team_name)	Current team name	roles, connector entries
$(date)	Current date (YYYY-MM-DD)	roles, connector entries
$(timestamp)	Current date-time (YYYY-MM-DDTHH-MM-SS)	roles, connector entries
$(phase)	Current phase name	roles, connector entries
$(instance_id)	Cliq instance ID	roles, connector entries
$(handoff.<phase>.<path>)	Scalar value from an upstream phase’s handoff data	roles, connector entries, commands
$(dirs.project)	Absolute path to the project root	team phase roles
$(dirs.self)	Absolute path to the current pipeline’s state directory	team phase roles
$(dirs.parent)	Absolute path to the parent pipeline’s state directory (null at top level)	team phase roles
$(dirs.<phase>)	Absolute path to a sibling team phase’s call frame	team phase roles

Handoff Variables — $(handoff.*)

Handoff variables let you wire structured data from an upstream phase’s handoff.json into downstream YAML fields. The syntax is:

$(handoff.<phase_name>.<field>[.<nested>...])

The <phase_name> identifies which upstream channel to read from, and the remaining dot-path traverses the data field of that phase’s HandoffEnvelope.

phases:
    - name: analyzer
      type: standard

    - name: deployer
      type: standard
      agent: exec
      depends_on: [analyzer]
      commands:
          - name: deploy
            run: "deploy --env $(handoff.analyzer.environment) --version $(handoff.analyzer.version)"

In this example, the analyzer phase writes structured data like { "environment": "staging", "version": "2.1.0" } in its handoff. The deployer phase uses those values directly in its commands without any agent interpretation.

Rules:

• Scalars only. $(handoff.*) variables must resolve to a string, number, or boolean. If the path resolves to an object or array, the pipeline escalates with an error.
• Embedding allowed. Variables can appear within strings: "deploy to $(handoff.analyzer.environment)".
• Missing values escalate. If the referenced phase or field doesn’t exist, the pipeline escalates — this is never silently ignored.
• Gate data access. For gate phases, you can reach into verdict details: $(handoff.reviewer.verdict.outcome), $(handoff.reviewer.verdict.reason), $(handoff.reviewer.iteration).

Working directory. Every agent’s cwd defaults to $(dirs.self). At top level, dirs.self equals the project root, so nothing changes for single-team projects. In sub-teams, dirs.self is the call frame, isolating bare relative paths from the project root and from parallel team phases.

To access project files from a sub-team, use $(dirs.project) explicitly. For call-frame-local artifacts, use $(dirs.self). For outputs from a specific upstream phase, use $(dirs.<phase>). cliq team validate warns about bare relative paths that should be qualified with one of these prefixes; cliq team publish blocks them, with --force available as an override for false positives. See Roles — Team Phase Roles for usage patterns.

---

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, and team.
Phase name contains .	Phase name 'foo.bar' must not contain '.' characters
Team phase without team	Team phase 'foo' must have a "team" field
team on non-team phase	Phase 'foo' has a "team" field but is not type "team"
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
agent: exec without commands	Phase 'foo' with agent 'exec' must have at least one command
agent: exec with max_iterations	Phase 'foo' with agent 'exec' must not have max_iterations
agent: hug without review: block	Phase 'foo' with agent 'hug' must have a review block with reviewer
review: without agent: hug	Phase 'foo' has review block but agent is not 'hug'
Missing role file	Every phase (except agent: exec) needs roles/<name>.md (including team phases)
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)
Team input mismatch	Phase 'foo' → sub-team '@acme/bar': missing required input 'key'
Team cycle detected	Cycle detected in team references: '@acme/a' is already being assembled
Team limit exceeded	Team limit exceeded: more than 50 teams resolved in a single project
Hub download failure	Assembly failed at [@local/parent → hub://@acme/ghost]: Team not found on hub

---

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: standard
          agent: curl
          action: get
          sources:
              - name: standards
                url: "https://example.com/coding-standards.md"

        - 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: gate
          agent: hug
          depends_on: [reviewer]
          review:
              reviewer: architects
              artifacts:
                  - reports/*.md
              timeout: 8h
              remind_every: 2h

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

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

        - name: publish-summary
          type: standard
          depends_on: [git-verify]
          agent: gdrive
          action: create
          target_entries:
              - name: summary
                file: reports/summary.md
                ref: "$(inputs.output_folder)"

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