---
name: team-building
description: Design and create AI team packages — manifest format, member structure, directory layout
---

# Team Building

This skill teaches you how to create Markus team packages — self-contained directory-based artifacts that define a group of specialized AI agents with shared norms and coordination structure.

## Core Philosophy

**Every agent in a team must be a specialist.** Do NOT simply pick generic templates and give them names. Design each agent with a unique identity, expertise, and detailed role documentation. Safety constraints are defined in each agent's `POLICIES.md`, not through tool restrictions.

## Artifact Directory

**CRITICAL**: Team artifacts MUST be saved under this exact path — the Builder page, install system, and deliverable detection all depend on it:

```
~/.markus/builder-artifacts/teams/{team-name}/
├── team.json                    # Manifest (auto-created from your JSON output)
├── README.md                    # Public-facing team overview for Hub/Builder (REQUIRED)
├── ANNOUNCEMENT.md              # Team announcement (you write via file_write)
├── NORMS.md                     # Working norms (you write via file_write)
├── workflows/                   # Workflow templates (optional)
│   └── {workflow-name}.yaml     # YAML workflow DAG definition
└── members/
    ├── {manager-slug}/
    │   ├── ROLE.md              # Identity and system prompt (REQUIRED)
    │   ├── HEARTBEAT.md         # Periodic self-check checklist (RECOMMENDED)
    │   ├── POLICIES.md          # Constraints and guardrails (optional)
    │   └── CONTEXT.md           # Domain context and references (optional)
    └── {worker-slug}/
        ├── ROLE.md              # Identity and system prompt (REQUIRED)
        ├── HEARTBEAT.md         # Periodic self-check checklist (RECOMMENDED)
        ├── POLICIES.md          # Constraints and guardrails (optional)
        └── CONTEXT.md           # Domain context and references (optional)
```

**Do NOT write artifacts to `~/.markus/shared/`, your working directory, or any other location.** Only `~/.markus/builder-artifacts/teams/` is recognized by the system.

### Where files are deployed on install

| Package location | Deployed to | Purpose |
|---|---|---|
| `ANNOUNCEMENT.md` | `~/.markus/teams/{teamId}/ANNOUNCEMENT.md` | Injected into every member's context |
| `NORMS.md` | `~/.markus/teams/{teamId}/NORMS.md` | Injected into every member's context |
| `members/{name}/ROLE.md` | `~/.markus/agents/{agentId}/role/ROLE.md` | Agent's identity and system prompt |
| `members/{name}/HEARTBEAT.md` | `~/.markus/agents/{agentId}/role/HEARTBEAT.md` | Periodic self-check checklist (every ~30 min) |
| `members/{name}/POLICIES.md` | `~/.markus/agents/{agentId}/role/POLICIES.md` | Additional agent constraints |
| `members/{name}/CONTEXT.md` | `~/.markus/agents/{agentId}/role/CONTEXT.md` | Domain context and references |
| `workflows/*.yaml` | `~/.markus/teams/{teamId}/workflows/*.yaml` | Workflow templates (runnable as task DAGs) |

## Creation Workflow

Output the team in up to three steps — manifest first, then content files, then optional workflow YAML. **Never put file content inline in the JSON.**

### Chat Mode vs Task Mode

- **Chat mode** (user conversation): Output the manifest JSON in a ```json code block → system auto-saves and creates the directory → then use `file_write` for each content file.
- **Task mode** (assigned task): Use `file_write` to write the manifest JSON file directly (e.g., `file_write("~/.markus/builder-artifacts/teams/{name}/team.json", ...)`) → then use `file_write` for each content file. When submitting deliverables, set the reference to the artifact directory path.
- **A2A mode** (agent-to-agent): Same as task mode — write all files via `file_write`.

### Step 1: Output Manifest JSON

**In chat mode**: Output the team structure as a JSON code block. The system auto-saves it.
**In task/A2A mode**: Write the manifest JSON file directly via `file_write`.

This JSON contains ONLY metadata and structure — **no file content**.

```json
{
  "type": "team",
  "name": "team-name-kebab-case",
  "displayName": "Team Display Name",
  "version": "1.0.0",
  "description": "Team purpose and goals",
  "author": "",
  "category": "development | devops | management | productivity | general",
  "tags": ["tag1", "tag2"],
  "team": {
    "members": [
      {
        "name": "Manager Name",
        "role": "manager",
        "count": 1,
        "skills": ["skill-id-1"]
      },
      {
        "name": "Worker Name",
        "role": "worker",
        "count": 1,
        "skills": ["skill-id-1", "skill-id-2"]
      }
    ],
    "workflow": {
      "phases": ["plan", "implement", "review", "validate"],
      "parallelImplementation": true,
      "worktreeIsolation": true,
      "requireReviewBeforeComplete": true
    },
    "workflows": ["workflows/my-workflow.yaml"]
  }
}
```

The system automatically saves this JSON and creates the directory. After that, you proceed to write files.

### Step 2: Write Files with file_write

After the JSON is saved, write each file individually using `file_write`. The base path is `~/.markus/builder-artifacts/teams/{team-name}/` (use the `name` from your JSON).

**Write files in this order:**

1. **README.md** (REQUIRED) — The public-facing overview displayed on Markus Hub and the Builder detail page. This is what users see first when browsing the team. Write 2-4 paragraphs covering:
   - What this team does and what problem it solves
   - Team composition overview (who the key members are)
   - Key capabilities and workflow highlights
   - Example use cases or when to deploy this team

2. **ANNOUNCEMENT.md** — Team mission, member introduction, how the team works, key capabilities. At least 3 paragraphs.

3. **NORMS.md** — Phase-based workflow documentation aligned with `team.workflow.phases`. This is critical for team effectiveness. Structure it as:
   - A section for each workflow phase (e.g., "### 1. Plan", "### 2. Implement", "### 3. Review & Merge")
   - Each phase explains what happens, who is responsible, and which platform capabilities to use
   - Include file/module ownership rules if the team does parallel development
   - Include communication protocols (when to use `agent_send_message`, `agent_broadcast_status`)
   - Reference platform capabilities: `spawn_subagent`, `background_exec`, `shell_execute` (git/gh), worktree isolation, `deliverable_create`, etc.

4. **Each member's ROLE.md** — Write one at a time. **Before writing, read the existing base role template** via `file_read` to understand the expected depth and conventions. Each ROLE.md should be at least 5 paragraphs, covering:
   - Who this agent is (identity, personality)
   - Core expertise and responsibilities
   - **Workflow with platform capabilities** — when to use `spawn_subagent`, `background_exec`, `shell_execute`, etc.
   - Output standards and quality criteria
   - Collaboration expectations within the team
   - For developers: worktree isolation, TDD, submit-for-review flow
   - For reviewers: review-then-merge workflow (git merge or gh pr)
   - For managers: file ownership planning, dependency graphs, `spawn_subagent` for analysis

5. **Each member's HEARTBEAT.md** (RECOMMENDED) — Defines what the agent proactively checks every ~30 minutes. Without this file, the agent is purely reactive and will only respond to direct messages. Write a role-specific checklist covering:
   - Check mailbox for new messages and respond to urgent items
   - Review assigned tasks — update progress, unblock if possible
   - Check team announcements and norms for updates
   - Role-specific patrol items (e.g., managers: check team task board and unblock members; developers: check build status and PR reviews; reviewers: check tasks awaiting review)
   - Scan recent channel messages for anything requiring attention

6. **POLICIES.md** (optional) — For members that need specific constraints.

7. **CONTEXT.md** (optional) — Additional domain context, references, or knowledge specific to a member.

**Example file_write calls:**

```
file_write("~/.markus/builder-artifacts/teams/research-team/README.md", "# Research Team\n\nA collaborative AI research team that...\n\n## Team Composition\n- Research Director (manager)...\n- Senior Researcher (worker)...\n\n## Use Cases\n- Academic literature review and synthesis...")
file_write("~/.markus/builder-artifacts/teams/research-team/ANNOUNCEMENT.md", "# Research Team — Team Announcement\n\n...")
file_write("~/.markus/builder-artifacts/teams/research-team/NORMS.md", "# Research Team — Working Norms\n\n...")
file_write("~/.markus/builder-artifacts/teams/research-team/members/research-director/ROLE.md", "# Research Director\n\nYou are **Research Director** — ...\n\n...")
file_write("~/.markus/builder-artifacts/teams/research-team/members/research-director/HEARTBEAT.md", "# Heartbeat Checklist\n\n- [ ] Check mailbox ...\n- [ ] Review team task board ...\n- [ ] Unblock members ...")
file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-researcher/ROLE.md", "# Senior Researcher\n\nYou are **Senior Researcher** — ...\n\n...")
file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-researcher/HEARTBEAT.md", "# Heartbeat Checklist\n\n- [ ] Check mailbox ...\n- [ ] Review assigned tasks ...\n- [ ] Check build status ...")
```

**IMPORTANT**: The member directory slug is derived from the member's `name` field — lowercased, spaces to hyphens, non-alphanumeric removed.

### Step 3: Write Workflow YAML (optional)

If the team has repeatable multi-step processes that should run as automated DAGs, add workflow templates. Each workflow is a YAML file that defines a sequence of tasks with dependencies, role assignments, and optional scheduling.

**When to include workflows:**
- The team has a process that runs repeatedly (e.g., weekly content publishing, daily reports)
- Multiple members need to collaborate in a defined sequence
- You want steps to run in parallel where possible and wait on dependencies automatically

**Write each workflow YAML to `workflows/`:**

```
file_write("~/.markus/builder-artifacts/teams/{team-name}/workflows/content-publishing.yaml", "<YAML content>")
```

Make sure `team.workflows` in your manifest references the file:
```json
"workflows": ["workflows/content-publishing.yaml"]
```

**Minimal workflow example:**

```yaml
name: content-publishing
displayName: Content Publishing
description: Plan, write, and review content
version: "1.0.0"

params:
  - name: topic
    type: string
    required: true

steps:
  - id: plan
    name: Plan Content
    type: agent_task
    role: editor
    prompt: "Create a content plan for: {{topic}}"

  - id: write
    name: Write Draft
    type: agent_task
    role: writer
    depends_on: [plan]
    inputs: [{ from: plan, as: content_plan }]
    prompt: "Write content about {{topic}} following the plan."

  - id: review
    name: Review & Publish
    type: agent_task
    role: editor
    depends_on: [write]
    inputs: [{ from: write, as: draft }]
    prompt: "Review the draft and finalize for publishing."
```

For the full YAML format reference, DAG patterns, scheduling, and more examples, activate the **`workflow-building`** skill.

## Field Reference

### Top-level fields
- **`type`**: Always `"team"`
- **`name`**: **MUST be English kebab-case** (e.g., `frontend-squad`, `research-team`). Even for Chinese teams, use English slug.
- **`displayName`**: Human-readable name, any language (e.g., `"前端开发小队"`)
- **`version`**: Semver (default `"1.0.0"`)
- **`description`**: Team purpose (any language)
- **`category`**: One of `development`, `devops`, `management`, `productivity`, `general`
- **`tags`**: Descriptive tags

### `team.members[]` — Member Specifications (REQUIRED)
- **`name`**: Display name (the slug for file paths is derived from this)
- **`role`**: `"manager"` or `"worker"`
- **`count`**: Number of instances (default 1)
- **`skills`**: Skill IDs from the dynamic context. **Actively assign skills — don't leave empty!**

**Note**: The `roleName` field is **not needed** for team members. Each member's identity is fully defined by their `ROLE.md` file under `members/{slug}/`. Do NOT include `roleName` unless you specifically want to inherit defaults from a built-in role template (rare).

### `team.workflow` — Workflow Configuration (recommended)
- **`phases`**: Array of phase names defining the team's workflow (e.g., `["plan", "implement", "review", "validate"]`)
- **`parallelImplementation`**: `true` if multiple members work in parallel during implementation
- **`worktreeIsolation`**: `true` if developers should work in isolated git worktrees (recommended for coding teams)
- **`requireReviewBeforeComplete`**: `true` if tasks must pass review before completion

### `team.workflows` — Workflow Template Files (optional)
- Array of YAML file paths relative to the package root, e.g. `["workflows/content-publishing.yaml"]`
- These files are copied to `~/.markus/teams/{teamId}/workflows/` on install and become runnable via the Workflows UI or `workflow_run` tool
- See the `workflow-building` skill for the full YAML format

## After Creation

> **CRITICAL**: Creating an artifact is NOT the same as installing/deploying it. Creating writes files to `builder-artifacts/`; installing deploys live agents that consume resources and join the org. **NEVER auto-install.** Only install when the user explicitly says "install", "deploy", or "hire". This applies to ALL modes (chat, task, A2A).

Once all files are written, tell the user:

1. **The team has been created and saved** — summarize the team composition (name, members, their roles).
2. **Ready to install** — the user can install from the Builder page, or ask you to install it (you would use `package_install`). Do NOT install unless asked.
3. **To modify or improve** this team (e.g., add new members, update roles, change team norms), just continue the conversation here — describe what you want to change and I'll update the files directly.

## Rules

- **DO NOT** invent skill IDs. Only use values from the dynamic context.
- **DO NOT** leave skills empty when relevant skills are available. Review the skills list!
- **DO NOT** put file content in the JSON. Always use `file_write` for files.
- **DO NOT** write artifacts to `~/.markus/shared/` or your working directory. Always use `~/.markus/builder-artifacts/teams/{name}/`.
- **The `name` field MUST be English kebab-case**.
- **All top-level fields must be the correct type**: `author` must be a plain string (e.g. `"John"`) — NOT an object. `tags` must be an array of strings. `version` must be semver string. `description` must be a string. The system validates the manifest on write and will reject malformed files.
- Every team MUST have exactly **one** member with `"role": "manager"` and at least **one** `"worker"`.
- Write each ROLE.md with **full attention** — at least 5 substantive paragraphs per member.
- Do NOT rush through members. Each one deserves careful, tailored content.
- After outputting the JSON, write files one by one — announce what you're writing each time.
