/studio-assistant-team-guide

name: studio-assistant-team-guide
description: "Explains the current APM Studio Team contract: participants, relations, subscriptions, teamRules, safety, and package-safe field boundaries. Use for Team contract, relation, subscription, and runtime guardrail questions. For role split/topology decisions, load studio-assistant-workflow-guide."
compatibility: Designed for the APM Studio built-in assistant projection.

Team Contract Guide

Use this skill when the user asks about Team structure, relation fields, subscriptions, teamRules, safety, or contract-correct Team mutations.

Mental Model

• A Team is a participant workflow.
• Workspace Teams, canonical Team primitives, runtime definitions, and runtime thread state are different layers.
• Assistant mutations operate on the Studio workspace layer but should still aim for package-ready structure.

Contract Facts

• Participants are keyed records in Studio workspace state.
• Canonical Team primitives use participant `key` plus Agent URNs, not workspace `agentRef`.
• Relations use `between: [sourceKey, targetKey]`, `direction`, `name`, and `description`.
• For `one-way`, relation order matters.
• Opposite one-way relations are valid as separate relations.
• Participant subscriptions use `messagesFrom`, `messageTags`, `callboardKeys`, and `eventTypes`.
• `eventTypes` currently supports only `runtime.idle`.
• Use `callboardKeys` as the canonical field name.

Relation Rules

• A multi-participant workflow Team should have at least one relation unless the user explicitly asks for an unconnected group.
• Every new relation needs source, target, direction, non-empty `name`, and non-empty `description`.
• Use `source...` and `target...` locator fields in assistant payloads.
• Relation direction should follow real work, authority, approval, or escalation flow.
• Relation names should name the artifact or coordination moment, such as `research brief`, `review notes`, or `launch handoff`.
• Avoid generic relation names like `handoff`, `sync`, or `collaboration`.

teamRules, Safety, And Subscriptions

• Use `teamRules` for durable whole-team behavior.
• Put participant-specific focus in the linked Agent `description`.
• Put runtime caps, loop limits, quiet windows, and thread deadline behavior in `safety`.
• `safety.threadTimeoutMs` is a runtime limit, not a participant wake.
• Participant subscriptions are wake filters, not permissions.
• Add subscriptions only for concrete wake behavior.
• Align `messageTags` and `callboardKeys` with concrete handoffs.

Runtime Waiting Vocabulary

• Use `wait_until` condition names `message_received`, `board_key_exists`, `wake_at`, `all_of`, and `any_of`.
• `wake_at` is the scheduled self-wake condition name.
• Do not call scheduled waits `timeout`.

Removed Fields To Avoid

• participant `id`
• relation `permissions`
• relation `maxCalls`
• relation `timeout`
• relation `sessionPolicy`

Self-Check

• Load `studio-assistant-action-surface-guide` before emitting payloads.
• If a new Team has multiple participants and represents a workflow/team, include at least one relation.
• Keep relation payloads contract-correct and package-safe.