Team Agent

The team agent invokes a child team pipeline as a single phase within a parent pipeline. It’s a built-in agent used automatically for type: team phases — you don’t set agent: team explicitly. Instead, declare type: team and provide a team reference.

Use team phases to compose complex workflows from specialized sub-teams, delegate entire feature slices to dedicated pipelines, or reuse pre-built team definitions from a registry.

Sample Phase

- name: security-scan
  type: team
  team: "@acme/security-scan"
  inputs:
      target: src/
  depends_on: [implement]

Phase Configuration

Team phases use type: team instead of setting agent: team directly. The team agent activates automatically when this type is detected.

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	Yes	Must be `"team"`
`role`	`string`	Yes	Role file that becomes the sub-team’s requirements spec
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`team`	`string`	Yes	Team reference (e.g., `"@local/child-team"` or `"hub://name@version"`)
`inputs`	`Record<string, string>`	No	Key-value pairs passed to the sub-team at req time

Behavior

When the orchestrator reaches a team phase:

Resolves the team reference (local path or hub registry)
Runs assemble → req → run for the child pipeline in a nested context
The child pipeline inherits the parent’s settings (merged with any overrides)
The parent phase completes with the child pipeline’s outcome

Limitations

Max nesting depth: 1 — child pipelines cannot themselves contain type: team phases
Shared workspace — the child pipeline runs in the parent’s workspace, so file conflicts are possible
Escalation propagates — if the child pipeline escalates, the parent phase escalates too

Settings

No agent-specific settings required. The team agent uses the parent pipeline’s settings, merged with any overrides from the child team’s configuration.

Output

Handoff Structure

{
    "data": {
        "team_ref": "@local/child-team",
        "exit_code": 0,
        "task_board": "All 4 phases completed successfully."
    },
    "text": "Sub-team pipeline results and task board summary"
}

Field Reference

Field	Location	Description
`team_ref`	`data.team_ref`	The resolved team reference that was invoked
`exit_code`	`data.exit_code`	Child pipeline exit code (0 = success)
`task_board`	`data.task_board`	Summary of the child pipeline’s task board outcome

Downstream Access

commands:
    - name: check-child
      run: 'test $(handoff.sub-task.data.exit_code) -eq 0'

Examples

Example: Delegate a feature to a specialized team

Architect the approach in the parent, then delegate implementation to a child team.

phases:
    - name: architect
      agent: cursor
      role: architect

    - name: implement-feature
      type: team
      team: "@local/frontend-team"
      depends_on: [architect]
      inputs:
          feature: user-dashboard
          priority: high

    - name: review
      type: gate
      agent: hug
      depends_on: [implement-feature]
      review:
          reviewer: tech-lead
          artifacts:
              - src/**/*.tsx

Example: Hub-hosted team reference

Invoke a versioned team definition from the hub registry.

phases:
    - name: fetch-requirements
      agent: jira
      action: get_issue
      sources:
          - name: ticket.json
            ref: PROJ-101

    - name: implement
      type: team
      team: "hub://[email protected]"
      depends_on: [fetch-requirements]
      inputs:
          ticket: PROJ-101

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [implement]

Example: Local team with no inputs

Simple delegation to a local team that derives context from upstream handoffs.

phases:
    - name: design
      agent: cursor
      role: designer

    - name: build-components
      type: team
      team: "@local/component-library"
      depends_on: [design]

    - name: integration-tests
      agent: exec
      depends_on: [build-components]
      commands:
          - name: test
            run: npm run test:integration
            escalate_on_fail: true

Setup

No setup required. The team agent is built-in and has no external dependencies. Team references are resolved from:

Local teams: directories in the workspace or local registry (e.g., @local/child-team)
Hub teams: published team definitions fetched from the hub (e.g., hub://name@version)

Ensure referenced teams exist and are accessible before running the pipeline.