hub-collab - SKILL.md Agent Skill

name: hub-collab description: Orchestrate a multi-agent collaboration demo on the Thoughtbox Hub. Spawns MANAGER, ARCHITECT, and DEBUGGER agents that coordinate through shared workspaces, problems, proposals, and channels. user_invocable: true

Hub Collaboration Demo

Orchestrate a multi-agent demo showing 3 agents (MANAGER, ARCHITECT, DEBUGGER) collaborating on the Thoughtbox Hub.

Hub Surface

The hub is exposed as tb.hub.* inside the thoughtbox_execute MCP tool (the only registered Thoughtbox MCP tools are thoughtbox_search, thoughtbox_execute, and thoughtbox_peer_notebook). Submit at most ONE state-mutating hub call per thoughtbox_execute invocation; read-only calls (tb.hub.whoami, tb.hub.listWorkspaces, tb.hub.readChannel, tb.hub.workspaceStatus) may be freely chained.

Prerequisites

Before running, verify:

Docker is running and the Thoughtbox server is accessible at http://localhost:1731/mcp
The thoughtbox MCP server is configured in .mcp.json

Check with:

curl -s http://localhost:1731/mcp | head -c 100

MCP Session Behavior (Empirically Verified 2026-02-07; tb.hub semantics per PR #374)

Sub-agents spawned via the Task tool share the parent's MCP HTTP connection but each tb.hub.register call creates a separate agentId. The hub keeps a per-MCP-session identity registry: the first registration becomes the session's implicit default agentId, and an explicit agentId override is only accepted if that agentId was registered in the SAME session. Key findings:

Session isolation works: Each sub-agent gets a unique agentId on the hub
Cross-workspace visibility works: Sub-agents see workspaces created by other agents
Cross-agent review works: A Debugger sub-agent can review an Architect's proposal
Coordinator role caveat: Re-registering creates a new identity, losing coordinator role. The orchestrator must create workspace + problems BEFORE spawning sub-agents, and not re-register afterward if merge is needed — tb.hub.mergeProposal must run from the coordinator's own session.
Explicit agentId required in sub-agents: Because all sub-agents share the parent's MCP session, the FIRST registration (normally the Orchestrator's) is the implicit default identity. Any tb.hub.* mutation that omits agentId is attributed to that default — silently breaking cross-agent attribution and review. Each sub-agent must capture the agentId returned by its own tb.hub.register/tb.hub.quickJoin and pass it as an explicit top-level agentId field in every subsequent hub call (e.g. tb.hub.claimProblem({ agentId, workspaceId, problemId })). Explicit agentId is accepted only for identities registered in the same session.
Sequential spawning recommended: Run sub-agents sequentially (not in parallel). Each agent should complete registration → join → claim → propose before the next starts, which keeps the demo's ordering deterministic (e.g. the Architect's proposal exists before the Debugger reviews it).

Two approaches:

Approach A: Single-Session Orchestration (Recommended)

Parent session acts as MANAGER (registers, creates workspace/problems). Sub-agents spawn sequentially via Task tool, each registering with their own identity. Cross-agent review works. Merge requires the parent to maintain its original coordinator identity.

Approach B: Multi-Process Demo (CLI agents)

Each agent runs as a separate Codex --agent process. Fully independent MCP connections with no shared state concerns. Best for video demos where you want visible parallel terminals.

For Approach B, open 3 terminal tabs and run:

# Terminal 1 - Manager
Codex --agent hub-manager -p "Register on the hub, create workspace 'demo-collab' with description 'Demo of multi-agent collaboration'. Create 2 problems: (1) 'Design caching strategy' - a design problem for the architect, (2) 'Fix profile priming bug' - a bug where profile content is appended to every thought response instead of just once. Report the workspace ID and problem IDs."

# Terminal 2 - Architect (after Manager reports workspace ID)
Codex --agent hub-architect -p "Register on the hub, join workspace '<WORKSPACE_ID>'. Claim the design problem, analyze the codebase for caching patterns, create a thought chain with your analysis, and submit a proposal."

# Terminal 3 - Debugger (after Manager reports workspace ID)
Codex --agent hub-debugger -p "Register on the hub, join workspace '<WORKSPACE_ID>'. Claim the bug problem about profile priming. Investigate gateway-handler.ts lines 504-516. Use five-whys on your branch. Review the Architect's proposal when it's ready."

Approach A: Single-Session Orchestration

When this skill is invoked, execute the following steps sequentially. Each step is JavaScript passed to thoughtbox_execute (we're in the parent session, so the registered identity persists across steps).

Step 1: Register as Manager

async () => tb.hub.register({ name: "Orchestrator", profile: "MANAGER" })

Record the agentId (it also becomes the session's implicit identity).

Step 2: Create Workspace

async () => tb.hub.createWorkspace({
  name: "demo-collaboration",
  description: "Demonstration of multi-agent hub collaboration with problem decomposition, proposals, and reviews"
})

Record the workspaceId.

Step 3: Create Problems

Create 2 problems (one thoughtbox_execute call each):

Problem 1 - Design:

async () => tb.hub.createProblem({
  workspaceId: "<ID>",
  title: "Design caching strategy for thought retrieval",
  description: "Analyze current thought retrieval patterns and design a caching layer to reduce filesystem reads. Consider: cache invalidation, memory bounds, branch-aware caching."
})

Problem 2 - Bug:

async () => tb.hub.createProblem({
  workspaceId: "<ID>",
  title: "Fix profile priming on every thought call",
  description: "BUG: gateway-handler.ts:504-516 appends full mental model payload to EVERY thought response. Should only prime once per session. Root cause analysis needed."
})

Step 4: Spawn Architect (Task tool)

Use Task tool with subagent_type matching the hub-architect agent:

Prompt: "You are the ARCHITECT agent. Using thoughtbox_execute, register on the hub (tb.hub.register({ name: 'Architect', profile: 'ARCHITECT' })) and record the agentId from the result. You share the MCP session with the Orchestrator, whose earlier registration is the session's implicit default identity — you MUST pass your own agentId explicitly in EVERY subsequent tb.hub.* call, or your work is attributed to the Orchestrator. Join workspace <ID> (tb.hub.joinWorkspace({ agentId, workspaceId })). Check tb.hub.readyProblems({ agentId, workspaceId }), claim the design problem (tb.hub.claimProblem({ agentId, workspaceId, problemId })). Create a thought chain analyzing caching approaches via tb.thought. Create a proposal (tb.hub.createProposal({ agentId, ... })) with your design recommendation. Post a summary to the problem channel (tb.hub.postMessage({ agentId, workspaceId, problemId, content }))."

Step 5: Spawn Debugger (Task tool)

Use Task tool with subagent_type matching the hub-debugger agent:

Prompt: "You are the DEBUGGER agent. Using thoughtbox_execute, register on the hub (tb.hub.register({ name: 'Debugger', profile: 'DEBUGGER' })) and record the agentId from the result. You share the MCP session with the Orchestrator, whose earlier registration is the session's implicit default identity — you MUST pass your own agentId explicitly in EVERY subsequent tb.hub.* call, or your work is attributed to the Orchestrator. Join workspace <ID> (tb.hub.joinWorkspace({ agentId, workspaceId })). Check tb.hub.readyProblems({ agentId, workspaceId }), claim the bug problem (tb.hub.claimProblem({ agentId, workspaceId, problemId })). Use five-whys investigation on the profile priming bug in gateway-handler.ts via tb.thought. Create a proposal (tb.hub.createProposal({ agentId, ... })) with your fix. Review the Architect's proposal (tb.hub.reviewProposal({ agentId, workspaceId, proposalId, verdict, reasoning })) if one exists."

Important: Spawn Architect FIRST, wait for completion, then spawn Debugger, so the Architect's proposal exists before the Debugger looks for it. Cross-agent attribution and review only work when each sub-agent passes its own explicit agentId — calls without it are credited to the session default (the Orchestrator's first registration).

Step 6: Report Status

async () => tb.hub.workspaceStatus({ workspaceId: "<ID>" })

Report the final state: agents registered, problems created/claimed, proposals submitted, channels active.

Expected Demo Output

A successful run demonstrates:

Agent registration with profiles (MANAGER, ARCHITECT, DEBUGGER)
Workspace creation and joining
Problem decomposition with dependencies
Branch-based investigation (thought chains)
Proposal creation linked to thought evidence
Cross-agent review (both approaches — verified empirically)
Channel communication with thought references
Workspace status showing coordinated progress