@markus-global/cli 0.4.21 → 0.4.23

package/templates/skills/team-building/SKILL.md

@@ -22,11 +22,15 @@ This skill teaches you how to create Markus team packages — self-contained dir
 ├── NORMS.md                     # Working norms (you write via file_write)
 └── members/
     ├── {manager-slug}/
-    │   ├── ROLE.md              # Manager identity (you write via file_write)
-    │   └── POLICIES.md          # Manager constraints (you write via file_write, optional)
+    │   ├── 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              # Worker identity (you write via file_write)
-        └── POLICIES.md          # Worker constraints (you write via file_write, optional)
+        ├── 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.
@@ -37,8 +41,10 @@ This skill teaches you how to create Markus team packages — self-contained dir
 |---|---|---|
 | `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` | Overrides base role template prompt |
+| `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 |
 
 ## Two-Step Workflow
 
@@ -72,14 +78,12 @@ This JSON contains ONLY metadata and structure — **no file content**.
       {
         "name": "Manager Name",
         "role": "manager",
-        "roleName": "project-manager",
         "count": 1,
         "skills": ["skill-id-1"]
       },
       {
         "name": "Worker Name",
         "role": "worker",
-        "roleName": "developer",
         "count": 1,
         "skills": ["skill-id-1", "skill-id-2"]
       }
@@ -121,7 +125,16 @@ After the JSON is saved, write each file individually using `file_write`. The ba
    - For reviewers: review-then-merge workflow (git merge or gh pr)
    - For managers: file ownership planning, dependency graphs, `spawn_subagent` for analysis
 
-4. **POLICIES.md** (optional) — For members that need specific constraints.
+4. **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
+
+5. **POLICIES.md** (optional) — For members that need specific constraints.
+
+6. **CONTEXT.md** (optional) — Additional domain context, references, or knowledge specific to a member.
 
 **Example file_write calls:**
 
@@ -129,7 +142,9 @@ After the JSON is saved, write each file individually using `file_write`. The ba
 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.
@@ -148,10 +163,11 @@ file_write("~/.markus/builder-artifacts/teams/research-team/members/senior-resea
 ### `team.members[]` — Member Specifications (REQUIRED)
 - **`name`**: Display name (the slug for file paths is derived from this)
 - **`role`**: `"manager"` or `"worker"`
-- **`roleName`**: Base role template from the dynamic context
 - **`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
@@ -170,7 +186,7 @@ Once all files are written, tell the user:
 
 ## Rules
 
-- **DO NOT** invent role names or skill IDs. Only use values from the dynamic context.
+- **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}/`.