Teams

Team is a combination of multiple specialized Agents: a set of AI workers each with its own role + shared norms (ANNOUNCEMENT / NORMS) + a collaboration/orchestration structure, optionally accompanied by runnable workflow templates. This page explains how to build a team package: member structure, orchestration config, repository layout, and publishing rules. For a single Agent, see Agents. ← Back to Assets · 中文原版


1. Concept Overview & Core Philosophy

ConceptDescription
Team PackageA self-contained, Hub-publishable directory artifact defining a group of Agents + shared norms + orchestration
Manifest (team.json)team.members[] member structure, team.workflow orchestration, team.workflows workflow files
MemberAgent definitions under members/{slug}/, including ROLE.md etc.
Norms injectionANNOUNCEMENT.md + NORMS.md injected into each member’s context after installation
WorkflowYAML DAG templates that can run automatically as task sequences

Core philosophy: every Agent in a team must be specialized. Don’t take a generic template and just rename it — each member needs a unique identity, expertise, and detailed role documentation; safety constraints live in each member’s POLICIES.md, not by removing tools.


2. Repository Structure (Artifact Directory)

~/.markus/builder-artifacts/teams/{team-name}/   ← {name} must be a valid slug
├── team.json                    # main config (manifest)
├── README.md                    # public description (Hub/Builder display, REQUIRED)
├── ANNOUNCEMENT.md              # team announcement
├── NORMS.md                     # working norms
├── images/
│   └── icon.png                 # team icon (becomes avatar after install)
├── workflows/                   # workflow templates (optional)
│   └── {workflow-name}.yaml     # YAML workflow DAG
└── members/
    ├── {manager-slug}/
    │   ├── ROLE.md              # identity & system prompt (REQUIRED)
    │   ├── HEARTBEAT.md         # periodic patrol (RECOMMENDED)
    │   ├── POLICIES.md          # constraints/guardrails (optional)
    │   ├── CONTEXT.md           # domain context (optional)
    │   └── images/              # member avatars
    └── {worker-slug}/           # (same structure)

Only ~/.markus/builder-artifacts/teams/ is recognized by package_list / package_install. Don’t write to ~/.markus/shared/, the workspace, or anywhere else.

Install Destinations

Package fileDeployed toPurpose
ANNOUNCEMENT.md~/.markus/teams/{teamId}/ANNOUNCEMENT.mdInjected into each member’s context
NORMS.md~/.markus/teams/{teamId}/NORMS.mdInjected into each member’s context
members/{name}/ROLE.md~/.markus/agents/{agentId}/role/ROLE.mdMember identity / system prompt
members/{name}/HEARTBEAT.md~/.markus/agents/{agentId}/role/HEARTBEAT.md~30-min patrol
members/{name}/POLICIES.md~/.markus/agents/{agentId}/role/POLICIES.mdAdditional constraints
members/{name}/CONTEXT.md~/.markus/agents/{agentId}/role/CONTEXT.mdDomain context
members/{name}/images/~/.markus/agents/{agentId}/role/images/Member avatar
workflows/*.yaml~/.markus/teams/{teamId}/workflows/*.yamlRunnable workflow templates

3. Three-Step Workflow

Manifest first, then content files, then optional workflow YAML. Never inline file content into JSON. This rule applies to every mode (chat / task / A2A).

  1. file_write team.json (manifest, see §4).
  2. file_write each file in turn: README / ANNOUNCEMENT / NORMS / each member’s ROLE.md, etc. (see §5).
  3. Optional: write workflows/*.yaml workflow templates.

4. Manifest (team.json) Core Fields

{
  "type": "team",
  "name": "dev-squad",                       // slug, kebab-case, same rules as agent
  "displayName": "Development Squad",         // human-readable (may be Chinese)
  "version": "2.0.0",
  "description": "Team purpose and goals",
  "author": "",
  "icon": "images/icon.png",
  "category": "development",                 // development | devops | management | productivity | general
  "tags": ["development", "sprint"],
  "i18n": { "zh-CN": { "displayName": "开发小队", "description": "…", "members": { "Tech Lead": "技术负责人" } } },
  "team": {
    "members": [
      { "name": "Tech Lead", "slug": "tech-lead", "roleName": "Tech Lead",
        "role": "manager", "count": 1, "skills": ["team-building"] },
      { "name": "Backend Developer", "role": "worker", "roleName": "backend-developer",
        "skills": ["coding-tools"] }
    ],
    "workflow": {
      "phases": ["plan", "implement", "review", "validate"],
      "parallelImplementation": true,
      "worktreeIsolation": true,
      "requireReviewBeforeComplete": true
    },
    "workflows": ["workflows/content-publishing.yaml"]
  }
}

Package Name (Slug) — Hard Rule

name is the package slug (directory name, Hub URL segment, share/publish ID). Rules are the same as Agent: English kebab-case only (lowercase letters/digits/hyphens), 2–64 chars, starts with a letter; not allowed: Chinese / space / underscore / uppercase / emoji; the human-readable name goes in displayName. Member directory slugs under members/ must also be English kebab-case. When the user only gives a Chinese name, invent an English kebab slug and keep the original name in displayName.

User languagename (slug)displayName
智库研究团队 (Chinese)think-tank-research智库研究团队
”Frontend Squad” (English)frontend-squadFrontend Squad

Member Fields (team.members[]) — REQUIRED

FieldDescription
nameDisplay name — may be Chinese (e.g. 技术负责人)
slug (recommended)kebab-case slug matching the members/{slug}/ directory name. Required when name contains non-ASCII — Chinese auto-kebab drops Unicode, causing directory misalignment and broken avatars
roleName (recommended)English display name, fallback for directory matching
roleOnly "manager" or "worker" — the UI uses it for coloring and management
countInstance count (usually 1), required
skillsSkill IDs (from the dynamic context) — assign proactively; don’t leave empty

⚠️ Hard rules: members must be nested under team (not at the root level); role can only be manager/worker; count is required; category must be in the enum; don’t put members/skills at the root level; each team has exactly 1 manager + ≥1 worker.

Orchestration (team.workflow) & Workflow Templates

  • phases: array of team work phases (e.g. ["plan", "implement", "review", "validate"]).
  • parallelImplementation: whether multiple members work in parallel during implementation; worktreeIsolation: true recommended for coding teams (git worktree isolation); requireReviewBeforeComplete: whether tasks must pass review before completing.
  • workflows/*.yaml: step DAGs with dependencies (steps[].id/name/type/role/prompt/depends_on/inputs). After install, copied to ~/.markus/teams/{teamId}/workflows/ and runnable via the Workflows UI or workflow_run. Full YAML format: see the workflow-building skill.

5. Content File Specs

  • README.md (REQUIRED): public description shown on Hub/Builder — what the team does, what it solves, member composition, key capabilities, deployment scenarios (2–4 paragraphs).
  • ANNOUNCEMENT.md: team mission, member introductions, collaboration style, key capabilities (at least 3 paragraphs).
  • NORMS.md: phased process matching team.workflow.phases — who owns each phase, which platform capabilities to use, file/module ownership for parallel development, communication protocol (when to agent_send_message / agent_broadcast_status), referencing spawn_subagent / background_exec / shell_execute / worktree / deliverable_create. This is crucial for team effectiveness.
  • Each member’s ROLE.md: written individually, at least 5 substantive paragraphs (refer to existing base role templates), same style as Agents / ROLE.md.
  • HEARTBEAT.md (RECOMMENDED), POLICIES.md (optional), CONTEXT.md (optional).

Visual Assets

  • Team icon images/icon.png: abstract logo/badge style (shield / gear / nodes / stars), no portraits.
  • Member avatars members/{slug}/images/avatar.jpg: realistic digital portraits, same rules as Agent avatars.

6. Create ≠ Install (Red Line)

Creating an artifact ≠ installing/deploying. Only use package_install / hub_install when the user explicitly says “install” / “deploy” / “hire”. Once installed into an organization, each member of the team becomes a real Agent — assignable to tasks and collaborating together.


7. Next Steps

  • Single Agent structure & building → Agents.
  • Give members reusable capabilities → Skills.
  • Publish the team package to the community → Markus Hub.