# `Planck.Agent.Team`
[🔗](https://github.com/alexdesousa/planck/blob/v0.1.0/lib/planck/agent/team.ex#L1)

A named collection of agents that share a `team_id` and can address each
other via the inter-agent tools.

Teams can be hydrated from a directory on disk (static) or constructed
in-memory by an orchestrator using `spawn_agent` (dynamic). Both paths
produce the same struct.

## Directory layout

    .planck/teams/
      elixir-dev-workflow/
        TEAM.json                  # required — member list and metadata
        members/
          orchestrator.md          # system prompt for the orchestrator
          planner.md
          builder.md

Each member's system prompt lives in `members/<name>.md` by convention, where
`<name>` is the member's `name` (which defaults to `type` when not set).

## TEAM.json format

    {
      "name":        "elixir-dev-workflow",
      "description": "Plan, build, and test Elixir changes.",
      "members": [
        {
          "type":          "orchestrator",
          "provider":      "anthropic",
          "model_id":      "claude-sonnet-4-6",
          "system_prompt": "members/orchestrator.md"
        },
        {
          "type":          "builder",
          "provider":      "anthropic",
          "model_id":      "claude-sonnet-4-6",
          "system_prompt": "members/builder.md",
          "tools":         ["read", "write", "edit", "bash"],
          "skills":        ["refactor"]
        }
      ]
    }

Member entries follow the schema documented on `Planck.Agent.AgentSpec`.
Exactly one member must have `"type": "orchestrator"`; the rest are workers.
All `system_prompt` file paths are resolved relative to the team directory.

Tools and skills are global (loaded by `planck_headless` from
`~/.planck/tools` and `~/.planck/skills`). Each member declares which of
them it should see via the `"tools"` and `"skills"` arrays; names are
resolved against the global pool at agent-start time.

# `t`

```elixir
@type t() :: %Planck.Agent.Team{
  alias: String.t() | nil,
  description: String.t() | nil,
  dir: Path.t() | nil,
  id: String.t() | nil,
  members: [Planck.Agent.AgentSpec.t()],
  name: String.t() | nil,
  source: :filesystem | :dynamic
}
```

A team definition.

- `:id` — team_id generated at materialization; `nil` before `start_session`.
- `:alias` — folder name for static teams; `nil` for dynamic teams.
- `:source` — `:filesystem` or `:dynamic`.
- `:name` — informational label from TEAM.json.
- `:description` — one-line purpose shown in team listings.
- `:dir` — absolute path to the team directory, `nil` for dynamic teams.
- `:members` — agent specs; exactly one has `type: "orchestrator"`.

# `dynamic`

```elixir
@spec dynamic(Planck.Agent.AgentSpec.t()) :: t()
```

Build a dynamic team from a single orchestrator spec.

Dynamic teams have no filesystem footprint. Workers may be added later via
the orchestrator's `spawn_agent` tool. Used both when `start_session/1`
runs with no `template:` (team of one) and when the orchestrator grows
the team at runtime.

# `load`

```elixir
@spec load(Path.t()) :: {:ok, t()} | {:error, String.t()}
```

Load a team from a directory containing a `TEAM.json` file.

Resolves member `system_prompt` paths relative to the team directory.

Returns `{:ok, team}` or `{:error, reason}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*