Skill: intercom

Source: ludus/skills/intercom/SKILL.md

---

name: intercom description: Team coordination via the intercom CLI metadata: openclaw: emoji: "\U0001F4FF" requires: bins: - intercom

Intercom — Your Team Communication Channel

Intercom is your Slack and email combined. Every bead is a message in a shared channel. You post tasks (like Slack requests), claim work (like picking up a ticket), leave comments (like thread replies), and close beads (like resolving a thread). The intercom CLI is your client — always connected, works from any directory.

The key rule: If you need something from another agent, use intercom. If you need to do focused work yourself, use ca-leash.

Both BEADS_DIR and BD_ACTOR are pre-set in your environment, so intercom works from any directory — while you are in a code repo, from your home directory, anywhere. No setup, no cd, just intercom <command>.

Quick Reference

Command	What it does
intercom	Inbox: conversations needing your attention
intercom new @agent "subject"	Start a new conversation
intercom read <id>	Read full conversation thread
intercom post <id> "message"	Post a message
intercom done <id> "result"	Wrap up + close + notify parent
intercom claim <id>	Take ownership
intercom threads	Your active conversations
intercom children <id>	Sub-conversations of a parent
intercom list [filters]	Search conversations
intercom dep <a> <b>	Add dependency
intercom doctor	Health check

Your Team

Actor	Role	What they do
main-agent	Apex (Chief of Staff)	Translates human requests into beads. Never codes.
priya-agent	Product Manager	Requirements, user stories, feature prioritization. Never codes.
atlas-agent	Architect	Architecture decisions, ADRs, PR review for arch consistency.
rio-agent	Engineering Manager	Triages, decomposes into sub-tasks. Never codes.
forge-agent	Backend Developer	Claims tasks, writes code, opens PRs.
helm-agent	DevOps Engineer	Infrastructure health, drift detection, deployment proposals.
indago-agent	Research Agent	Information retrieval, source analysis, competitive research.
glue-agent	Agent Reliability Engineer	Agent health monitoring, handoff verification, conformance.

Your identity is $BD_ACTOR. Every bead you create or claim is stamped with your actor name.

How Work Finds You

An automated watcher monitors intercom for new beads. When it sees a bead labeled for your role, it wakes you up. Labels are the routing mechanism:

Label	Who gets woken up
priya	Product Manager — requirements, user stories
atlas	Architect — architecture decisions, PR review
rio	Engineering Manager — triages and decomposes
forge	Backend Developer — implements and ships
helm	DevOps Engineer — infrastructure, drift detection
indago	Research Agent — information retrieval, source analysis
glue	Agent Reliability Engineer — health monitoring, conformance

When you create a bead, choose the label for the agent that should handle it. If unsure, label it rio — the EM triages unknown work. Beads without labels go to rio for triage.

Delegation Chain

main → creates bead (label: rio | forge | priya | atlas | helm | indago | glue)
rio → triages, creates sub-beads (label: forge | atlas | helm | indago)
forge → implements, discovers work → creates bead (label: rio | atlas | helm)

Routing guidance lives in each agent's AGENTS.md. There is no fixed chain — any agent can delegate to any other.

When to Use Intercom

You want to...	Intercom action
Ask another agent to do something	intercom new @<label> "subject"
Ask a question about a task	intercom post <id> "QUESTION: ..."
Report progress	intercom post <id> "STATUS: ..."
Hand off a result	intercom done <id> "..."
Discover what needs doing	intercom (no args)

Intercom vs ca-leash

	Intercom (beads)	ca-leash
What	Team communication channel	Your personal sub-agent
Analogy	Slack / email	Hiring a focused temp worker
When	Need another agent's expertise	Need to do deep work yourself
Example	"Atlas, review this architecture"	"Analyze these 20 files for me"
Creates	Beads (visible to all)	Sessions (private to you)

Rule of thumb: If the work requires a different role's expertise → intercom. If it requires your role's expertise but lots of turns → ca-leash.

Core Workflow: Read → Claim → Work → Close

# 1. Read the conversation
intercom read <id>

# 2. Claim it (atomic — fails if someone else took it)
intercom claim <id>

# 3. Do the work...

# 4. Close with a meaningful result
intercom done <id> "Implemented X by modifying Y"

All changes are immediately visible to the next agent — no sync step needed.

Creating Beads

intercom new @<label> "Title" --priority <N> --body "Description"

• Priority: 0 (critical) → 4 (backlog)
• Labels determine who gets the work — use the right label for the target role
• Always provide --body with enough context for the recipient to act without asking back

Communication

# Ask a question
intercom post <id> "QUESTION: What framework should I use?"

# Answer a question
intercom post <id> "ANSWER: Use React for the frontend"

# Status update
intercom post <id> "STATUS: 2/3 sub-tasks complete"

# Relay from human
intercom post <id> "FROM HUMAN: Also handle negative numbers."

# Read conversation with comments
intercom read <id>

These prefixes (QUESTION:, ANSWER:, STATUS:, FROM HUMAN:, CANCELLED:, BLOCKED:) are conventions — use them so other agents (and tooling) can parse intent.

Work Discovery

When you wake up:

# Check for stale work first (conversations you started but didn't finish)
intercom threads

# Check inbox for new work
intercom

Process beads in priority order. Stop when the queue is empty.

Querying

intercom                              # Inbox: what needs my attention?
intercom list --status open           # All open conversations
intercom read <id>                    # Conversation details
intercom children <id>                # Sub-conversations

Closing Beads with GitHub Issue Links

When a bead title contains a GitHub issue reference (e.g., GH#42), use the ludus run close command to close both the bead and the linked issue:

ludus run close <bead-id> "Reason" [--repo owner/repo]

For beads without GitHub references, use intercom done directly.

Critical Rules

1. Read before acting — always intercom read a bead before claiming it
2. Meaningful close reasons — describe what you did, not just "Done"
3. Claim is atomic — if it fails, someone else took the bead; move on
4. Labels may be missing — beads without labels omit the labels key entirely; check for missing key, not empty array
5. intercom works from anywhere — BEADS_DIR is set globally, no need to cd into intercom
6. intercom doctor — run this if you suspect environment issues

---

Communication Scenarios

These scenarios trace how messages flow through intercom between humans and agents.

Scenario 1: Feature Request (Happy Path)

Human (Telegram): "The calculator needs a modulo operator"

Main receives the message and delegates:

parent_id=$(intercom new @rio "Add modulo operator to calculator" \
  --priority 2 \
  --body "Repo: test-calculator. Add % operator support to calc.sh." | jq -r '.id')
# Replies to human: "Delegated to the team: $parent_id. I'll keep you posted."

Rio wakes up (watcher sees ready bead labeled rio):

intercom read <parent-id>                          # read the request
intercom claim <parent-id>                         # claim it
child_id=$(intercom new @forge "Implement modulo in calc.sh" \
  --parent <parent-id> --priority 2 \
  --body "Repo: test-calculator. Add case for '%' in calc.sh. Add test case." | jq -r '.id')
intercom post <parent-id> "Triaged. Created sub-task $child_id for forge."

Forge wakes up (watcher sees ready bead labeled forge):

intercom read <child-id>                           # read the bead details
intercom claim <child-id>
# ... implements, tests, pushes PR ...
intercom done <child-id> "Fixed in PR #17"

Rio checks parent and closes:

intercom children <parent-id>                      # verify all children closed
intercom done <parent-id> "All sub-tasks complete: PR #17"

Main reports back:

intercom read <parent-id>
# Sees <parent-id> is closed
# Replies to human: "Done — modulo operator added in PR #17."

Scenario 2: Forge Has a Question

Forge encounters ambiguity while working on a bead:

intercom post <child-id> \
  "QUESTION: calc.sh uses eval(). Should I add input validation to prevent injection, or just the modulo operator?"
# Forge moves to next bead or stops if queue is empty

Known gap (G-1): The watcher only polls intercom (inbox) — a comment on an in_progress bead does not make it "ready." The question sits until rio is woken for another reason and checks in-progress beads. If blocked, stop and wait.

Scenario 3: Human Asks for Status

Main does not create any beads — it just reads intercom state:

intercom list --status open                        # search for relevant beads
intercom read <parent-id>                          # status: in_progress, has children
intercom children <parent-id>                      # <child-id> in_progress, assigned to forge-agent
# Replies: "In progress. Forge is working on <child-id> (implement modulo). No blockers."

Scenario 4: Human Cancels a Task

Main closes beads top-down, adding a comment so forge sees the reason before the bead is closed:

intercom read <parent-id>                          # find it and its children
intercom post <child-id> "CANCELLED: Human requested cancellation. Abandon current work."
intercom done <child-id> "Cancelled by human request"
intercom done <parent-id> "Cancelled by human request"
# Replies: "Cancelled. Both <parent-id> and its sub-task are closed."

Edge case (G-4): If forge is currently active with a PR in flight, the bead is closed but forge does not know until it next queries intercom. The comment-before-close convention mitigates this — forge sees the cancellation reason and can abandon the PR.

Scenario 5: Forge Discovers Additional Work

Forge finds a related bug while working on a bead:

intercom post <child-id> \
  "Found additional bug: division by zero crashes calc.sh. Filing separate bead."
intercom new @rio "Fix division-by-zero crash in calc.sh" \
  --priority 1 \
  --body "Repo: test-calculator. calc.sh crashes on divide-by-zero. Discovered while working on <child-id>."
# Continues working on the current task

Forge creates the new bead labeled rio because it needs triage — the fix may be more complex than forge should decide alone.

Scenario 6: Human Provides Additional Context

Main relays information to the active sub-task:

# Finds the active sub-task
intercom post <child-id> \
  "FROM HUMAN: Handle negative numbers. Python's % already works correctly, but add a test case for negative inputs."
# Replies: "Got it, I've added that note to the dev task."