agenthub-multiagent-mcp 1.61.0 → 1.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +3 -3
  2. package/dist/brain/memvidBrain.d.ts +22 -0
  3. package/dist/brain/memvidBrain.d.ts.map +1 -1
  4. package/dist/brain/memvidBrain.js +41 -2
  5. package/dist/brain/memvidBrain.js.map +1 -1
  6. package/dist/brain/memvidBrain.test.js +90 -0
  7. package/dist/brain/memvidBrain.test.js.map +1 -1
  8. package/dist/brain/migrate.d.ts +43 -0
  9. package/dist/brain/migrate.d.ts.map +1 -1
  10. package/dist/brain/migrate.js +148 -23
  11. package/dist/brain/migrate.js.map +1 -1
  12. package/dist/brain/migrate.test.js +194 -1
  13. package/dist/brain/migrate.test.js.map +1 -1
  14. package/dist/channel.js +47 -5
  15. package/dist/channel.js.map +1 -1
  16. package/dist/channelDiagnostics.d.ts +36 -0
  17. package/dist/channelDiagnostics.d.ts.map +1 -1
  18. package/dist/channelDiagnostics.js +65 -0
  19. package/dist/channelDiagnostics.js.map +1 -1
  20. package/dist/channelDiagnostics.test.js +81 -1
  21. package/dist/channelDiagnostics.test.js.map +1 -1
  22. package/dist/client.d.ts +17 -0
  23. package/dist/client.d.ts.map +1 -1
  24. package/dist/client.js +32 -0
  25. package/dist/client.js.map +1 -1
  26. package/dist/daemon.js +16 -22
  27. package/dist/daemon.js.map +1 -1
  28. package/dist/index.js +36 -3
  29. package/dist/index.js.map +1 -1
  30. package/dist/lib/pending-items.d.ts +63 -0
  31. package/dist/lib/pending-items.d.ts.map +1 -0
  32. package/dist/lib/pending-items.js +96 -0
  33. package/dist/lib/pending-items.js.map +1 -0
  34. package/dist/pinSweep.d.ts +83 -0
  35. package/dist/pinSweep.d.ts.map +1 -0
  36. package/dist/pinSweep.js +105 -0
  37. package/dist/pinSweep.js.map +1 -0
  38. package/dist/pinSweep.test.d.ts +12 -0
  39. package/dist/pinSweep.test.d.ts.map +1 -0
  40. package/dist/pinSweep.test.js +110 -0
  41. package/dist/pinSweep.test.js.map +1 -0
  42. package/dist/pinSweepCli.d.ts +20 -0
  43. package/dist/pinSweepCli.d.ts.map +1 -0
  44. package/dist/pinSweepCli.js +287 -0
  45. package/dist/pinSweepCli.js.map +1 -0
  46. package/dist/run-claude.sh +36 -5
  47. package/dist/sessionCapture.d.ts.map +1 -1
  48. package/dist/sessionCapture.js +7 -1
  49. package/dist/sessionCapture.js.map +1 -1
  50. package/dist/sessionCapture.test.js +20 -0
  51. package/dist/sessionCapture.test.js.map +1 -1
  52. package/dist/setup.js +11 -0
  53. package/dist/setup.js.map +1 -1
  54. package/dist/shiftFiles.d.ts +33 -0
  55. package/dist/shiftFiles.d.ts.map +1 -0
  56. package/dist/shiftFiles.js +57 -0
  57. package/dist/shiftFiles.js.map +1 -0
  58. package/dist/shiftFiles.test.d.ts +2 -0
  59. package/dist/shiftFiles.test.d.ts.map +1 -0
  60. package/dist/shiftFiles.test.js +141 -0
  61. package/dist/shiftFiles.test.js.map +1 -0
  62. package/dist/skillInstaller.d.ts.map +1 -1
  63. package/dist/skillInstaller.gate.test.js +2 -0
  64. package/dist/skillInstaller.gate.test.js.map +1 -1
  65. package/dist/skillInstaller.js +8 -0
  66. package/dist/skillInstaller.js.map +1 -1
  67. package/dist/skillInstaller.test.js +8 -1
  68. package/dist/skillInstaller.test.js.map +1 -1
  69. package/dist/tools/goshtiRead.d.ts +72 -0
  70. package/dist/tools/goshtiRead.d.ts.map +1 -0
  71. package/dist/tools/goshtiRead.js +274 -0
  72. package/dist/tools/goshtiRead.js.map +1 -0
  73. package/dist/tools/goshtiRead.test.d.ts +8 -0
  74. package/dist/tools/goshtiRead.test.d.ts.map +1 -0
  75. package/dist/tools/goshtiRead.test.js +182 -0
  76. package/dist/tools/goshtiRead.test.js.map +1 -0
  77. package/dist/tools/inboxBounds.d.ts +80 -0
  78. package/dist/tools/inboxBounds.d.ts.map +1 -0
  79. package/dist/tools/inboxBounds.js +105 -0
  80. package/dist/tools/inboxBounds.js.map +1 -0
  81. package/dist/tools/inboxBounds.test.d.ts +15 -0
  82. package/dist/tools/inboxBounds.test.d.ts.map +1 -0
  83. package/dist/tools/inboxBounds.test.js +135 -0
  84. package/dist/tools/inboxBounds.test.js.map +1 -0
  85. package/dist/tools/index.d.ts +11 -0
  86. package/dist/tools/index.d.ts.map +1 -1
  87. package/dist/tools/index.js +106 -102
  88. package/dist/tools/index.js.map +1 -1
  89. package/dist/tools/intakeRequests.d.ts +35 -0
  90. package/dist/tools/intakeRequests.d.ts.map +1 -0
  91. package/dist/tools/intakeRequests.js +344 -0
  92. package/dist/tools/intakeRequests.js.map +1 -0
  93. package/dist/tools/intakeRequests.test.d.ts +8 -0
  94. package/dist/tools/intakeRequests.test.d.ts.map +1 -0
  95. package/dist/tools/intakeRequests.test.js +183 -0
  96. package/dist/tools/intakeRequests.test.js.map +1 -0
  97. package/dist/tools/openspec-viz/taskSync.d.ts +115 -0
  98. package/dist/tools/openspec-viz/taskSync.d.ts.map +1 -0
  99. package/dist/tools/openspec-viz/taskSync.js +144 -0
  100. package/dist/tools/openspec-viz/taskSync.js.map +1 -0
  101. package/dist/tools/openspec-viz/taskSync.test.d.ts +2 -0
  102. package/dist/tools/openspec-viz/taskSync.test.d.ts.map +1 -0
  103. package/dist/tools/openspec-viz/taskSync.test.js +198 -0
  104. package/dist/tools/openspec-viz/taskSync.test.js.map +1 -0
  105. package/dist/tools/pushedItemsSafety.test.d.ts +12 -0
  106. package/dist/tools/pushedItemsSafety.test.d.ts.map +1 -0
  107. package/dist/tools/pushedItemsSafety.test.js +179 -0
  108. package/dist/tools/pushedItemsSafety.test.js.map +1 -0
  109. package/dist/tools/tools.test.js +17 -5
  110. package/dist/tools/tools.test.js.map +1 -1
  111. package/dist/tools/wrapperCost.test.d.ts +13 -0
  112. package/dist/tools/wrapperCost.test.d.ts.map +1 -0
  113. package/dist/tools/wrapperCost.test.js +149 -0
  114. package/dist/tools/wrapperCost.test.js.map +1 -0
  115. package/dist/websocket.d.ts +30 -1
  116. package/dist/websocket.d.ts.map +1 -1
  117. package/dist/websocket.js +40 -3
  118. package/dist/websocket.js.map +1 -1
  119. package/dist/websocketQueue.test.d.ts +10 -0
  120. package/dist/websocketQueue.test.d.ts.map +1 -0
  121. package/dist/websocketQueue.test.js +78 -0
  122. package/dist/websocketQueue.test.js.map +1 -0
  123. package/package.json +4 -4
  124. package/skills/catalog.json +23 -10
  125. package/skills/commands/close-session.md +144 -144
  126. package/skills/commands/start-session.md +25 -6
  127. package/skills/manifest.json +8 -1
  128. package/skills/skills/code-brain-hook/SKILL.md +61 -61
  129. package/skills/skills/file-bug/SKILL.md +75 -75
  130. package/skills/skills/inbox/SKILL.md +99 -0
  131. package/skills/skills/multiagent-brainstorm/SKILL.md +164 -164
@@ -1,75 +1,75 @@
1
- ---
2
- name: file-bug
3
- description: File a reproducible bug as a first-class AgentHub ticket via the report_bug MCP tool. Use when you hit a defect, a failing test/CI step, or any reproducible misbehavior worth tracking — captures severity, repro steps, environment, and a defect lifecycle.
4
- license: MIT
5
- ---
6
-
7
- # File a Bug
8
-
9
- AgentHub has a first-class bug workflow (`add-bug-tracking-workflow`). A bug is a
10
- `type=bug` ticket carrying **severity**, **reproduction steps**, an
11
- **environment** tag, and a **defect lifecycle** (`bug_state`) that is separate
12
- from work `status`. Use this skill whenever you find a reproducible defect worth
13
- tracking — a failing test, a broken endpoint, a CI step that fails, or any
14
- misbehavior you can describe steps for.
15
-
16
- ## File it with `report_bug`
17
-
18
- Call the `report_bug` MCP tool. `repro_steps` is **required**; severity defaults
19
- to `sev3` if omitted.
20
-
21
- ```jsonc
22
- report_bug({
23
- "title": "login returns 500",
24
- "repro_steps": "1. POST /login with valid creds\n2. observe 500",
25
- "severity": "sev1", // optional (default sev3)
26
- "environment": "prod", // optional — e.g. "staging", "prod", "v1.12.0"
27
- "expected": "200 + session cookie", // optional → folded into description
28
- "actual": "500 Internal Server Error" // optional → folded into description
29
- })
30
- ```
31
-
32
- The tool returns the new bug's `id`/`key`. With no `story_id`/`openspec_change`
33
- the bug is auto-anchored under the project's reserved **"Bugs"** epic+story — you
34
- don't need to know the hierarchy. `report_bug` is a **reversible** internal
35
- action, so active employees (including `qa-triage`) may call it without
36
- break-glass.
37
-
38
- > Requires `agent_register` first (the project binding is read from local state).
39
- > A `400 repro_steps_required` means you left repro steps empty — always include
40
- > concrete, numbered steps.
41
-
42
- ## Write a good bug
43
-
44
- - **Title**: one line, specific. "Roadmap PDF export 500s on >50 entries", not "PDF broken".
45
- - **repro_steps**: numbered, minimal, deterministic. Someone else should be able
46
- to follow them and see the same failure.
47
- - **severity** (impact, distinct from priority):
48
-
49
- | Severity | Meaning |
50
- |----------|---------|
51
- | `sev1` | Critical — outage, data loss, security |
52
- | `sev2` | High — major feature broken, no workaround |
53
- | `sev3` | Medium — feature broken, workaround exists (default) |
54
- | `sev4` | Low — cosmetic / minor |
55
-
56
- - **environment**: where you saw it (`staging`, `prod`, a version/commit).
57
- - **expected** / **actual**: the delta, when not obvious from repro steps.
58
-
59
- ## Lifecycle (don't overthink it at filing time)
60
-
61
- Filing always starts at `bug_state=unverified`. Triage walks it forward with
62
- `update_ticket` (`bug_state=...`):
63
- `unverified → verified → in_progress → fixed → verified_fixed → closed`
64
- (`wont_fix`/`duplicate` are terminal; `reopened` revives a terminal bug to
65
- `verified`). Transitions are validated server-side — an illegal jump returns
66
- `409 invalid_bug_transition`. You usually only set `unverified` (automatic) at
67
- filing time and leave the rest to triage / the dashboard.
68
-
69
- ## Other paths (same result)
70
-
71
- - **Dashboard**: the Issues page → **Open Bugs** board has a *File a bug* form.
72
- - **HTTP**: `POST /api/projects/{projectId}/bugs` with `{title, repro_steps, severity?, environment?}`.
73
- - **Reclassify a task you already created**: `update_ticket(type="bug", severity=..., repro_steps=...)` promotes it (defaults `bug_state=unverified`).
74
-
75
- Full reference: the `bug-tracking-guide` doc.
1
+ ---
2
+ name: file-bug
3
+ description: File a reproducible bug as a first-class AgentHub ticket via the report_bug MCP tool. Use when you hit a defect, a failing test/CI step, or any reproducible misbehavior worth tracking — captures severity, repro steps, environment, and a defect lifecycle.
4
+ license: MIT
5
+ ---
6
+
7
+ # File a Bug
8
+
9
+ AgentHub has a first-class bug workflow (`add-bug-tracking-workflow`). A bug is a
10
+ `type=bug` ticket carrying **severity**, **reproduction steps**, an
11
+ **environment** tag, and a **defect lifecycle** (`bug_state`) that is separate
12
+ from work `status`. Use this skill whenever you find a reproducible defect worth
13
+ tracking — a failing test, a broken endpoint, a CI step that fails, or any
14
+ misbehavior you can describe steps for.
15
+
16
+ ## File it with `report_bug`
17
+
18
+ Call the `report_bug` MCP tool. `repro_steps` is **required**; severity defaults
19
+ to `sev3` if omitted.
20
+
21
+ ```jsonc
22
+ report_bug({
23
+ "title": "login returns 500",
24
+ "repro_steps": "1. POST /login with valid creds\n2. observe 500",
25
+ "severity": "sev1", // optional (default sev3)
26
+ "environment": "prod", // optional — e.g. "staging", "prod", "v1.12.0"
27
+ "expected": "200 + session cookie", // optional → folded into description
28
+ "actual": "500 Internal Server Error" // optional → folded into description
29
+ })
30
+ ```
31
+
32
+ The tool returns the new bug's `id`/`key`. With no `story_id`/`openspec_change`
33
+ the bug is auto-anchored under the project's reserved **"Bugs"** epic+story — you
34
+ don't need to know the hierarchy. `report_bug` is a **reversible** internal
35
+ action, so active employees (including `qa-triage`) may call it without
36
+ break-glass.
37
+
38
+ > Requires `agent_register` first (the project binding is read from local state).
39
+ > A `400 repro_steps_required` means you left repro steps empty — always include
40
+ > concrete, numbered steps.
41
+
42
+ ## Write a good bug
43
+
44
+ - **Title**: one line, specific. "Roadmap PDF export 500s on >50 entries", not "PDF broken".
45
+ - **repro_steps**: numbered, minimal, deterministic. Someone else should be able
46
+ to follow them and see the same failure.
47
+ - **severity** (impact, distinct from priority):
48
+
49
+ | Severity | Meaning |
50
+ |----------|---------|
51
+ | `sev1` | Critical — outage, data loss, security |
52
+ | `sev2` | High — major feature broken, no workaround |
53
+ | `sev3` | Medium — feature broken, workaround exists (default) |
54
+ | `sev4` | Low — cosmetic / minor |
55
+
56
+ - **environment**: where you saw it (`staging`, `prod`, a version/commit).
57
+ - **expected** / **actual**: the delta, when not obvious from repro steps.
58
+
59
+ ## Lifecycle (don't overthink it at filing time)
60
+
61
+ Filing always starts at `bug_state=unverified`. Triage walks it forward with
62
+ `update_ticket` (`bug_state=...`):
63
+ `unverified → verified → in_progress → fixed → verified_fixed → closed`
64
+ (`wont_fix`/`duplicate` are terminal; `reopened` revives a terminal bug to
65
+ `verified`). Transitions are validated server-side — an illegal jump returns
66
+ `409 invalid_bug_transition`. You usually only set `unverified` (automatic) at
67
+ filing time and leave the rest to triage / the dashboard.
68
+
69
+ ## Other paths (same result)
70
+
71
+ - **Dashboard**: the Issues page → **Open Bugs** board has a *File a bug* form.
72
+ - **HTTP**: `POST /api/projects/{projectId}/bugs` with `{title, repro_steps, severity?, environment?}`.
73
+ - **Reclassify a task you already created**: `update_ticket(type="bug", severity=..., repro_steps=...)` promotes it (defaults `bug_state=unverified`).
74
+
75
+ Full reference: the `bug-tracking-guide` doc.
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: inbox
3
+ description: Read your AgentHub inbox safely and acknowledge only what you actually read. Use when checking messages from other agents, or when asked to go through your inbox. Replaces ad-hoc inbox commands that bulk-mark messages read and silently lose them.
4
+ license: MIT
5
+ ---
6
+
7
+ # Read your inbox
8
+
9
+ **This file supersedes any other `inbox` instruction on this machine.** If you
10
+ also see a `~/.claude/commands/inbox.md` or a flat `~/.claude/skills/inbox.md`
11
+ that tells you to "mark all messages as read after displaying them", that file
12
+ is the bug this one exists to fix — ignore it, follow this, and tell your human
13
+ to delete it. The installer cannot: it never deletes, and it skips files it did
14
+ not ship. `/inbox` resolves to the **command** file, so the stale copy is the one
15
+ most likely to be reached.
16
+
17
+ Messages from other agents arrive in your AgentHub inbox. Reading them is safe.
18
+ **Acknowledging them is not, unless you did actually read them** — and that is
19
+ the whole reason this skill exists.
20
+
21
+ ## The rule
22
+
23
+ Once a message's status is `read`, `check_inbox` with `unread_only: true` will
24
+ **never return it again**. It is invisible to you and to anyone who does not
25
+ already know its id. So:
26
+
27
+ > Mark read **only** the specific message ids whose bodies you actually read,
28
+ > one `mark_read` call each. Never bulk-acknowledge.
29
+
30
+ This is not a hypothetical. On 2026-10-14 four messages to `krishi-dev` were
31
+ flipped to `read` inside a two-second window after an oversized `check_inbox`
32
+ result never reached the model at all — the earlier ad-hoc `inbox` command said
33
+ "mark all messages as read after displaying them" with no condition attached,
34
+ and a model obeying it acknowledged four messages nobody had seen. See bug
35
+ `AGHUB-1426` and openspec change `fix-inbox-delivery-and-tool-wrapping`.
36
+
37
+ ## Steps
38
+
39
+ ### 1. Read a bounded page
40
+
41
+ ```
42
+ check_inbox(unread_only: true, limit: 10)
43
+ ```
44
+
45
+ Always pass `limit`. The default is 10 and the ceiling is 50.
46
+
47
+ ### 2. Check what you were given
48
+
49
+ The response carries four fields that tell you whether it is complete:
50
+
51
+ | Field | Meaning |
52
+ |---|---|
53
+ | `returned` | how many messages are in this response |
54
+ | `total` | how many matched your query |
55
+ | `omitted_count` | `total - returned` — how many you did **not** get |
56
+ | `truncated` | `true` if any message was withheld **or** any body was clipped |
57
+
58
+ A message whose body was clipped carries
59
+ `_truncated: { original_bytes: N }`. You have its beginning, not the whole
60
+ thing.
61
+
62
+ ### 3. Display them
63
+
64
+ Show each message's sender, subject, and body concisely.
65
+
66
+ ### 4. Acknowledge — conditionally
67
+
68
+ **If `truncated` is `false`:** you received everything. Call `mark_read` once
69
+ per message you displayed.
70
+
71
+ **If `truncated` is `true`:** do **not** call `mark_read` at all. Instead:
72
+
73
+ - say how many were withheld (`omitted_count`);
74
+ - for any message with a `_truncated` marker, say its body is incomplete and
75
+ how long the original was;
76
+ - page through the rest with further `check_inbox(limit: …)` calls and
77
+ acknowledge each page you genuinely read.
78
+
79
+ **Also do not acknowledge** — regardless of what `truncated` says — any message
80
+ whose body you did not actually see: because the tool result was too large and
81
+ got spilled to a file, because the call errored, or because you skipped it.
82
+
83
+ ## If a message needs an answer
84
+
85
+ Reply with `reply(message_id, body)`. A reply does **not** mark the message
86
+ read, so still `mark_read` it once you are done with it.
87
+
88
+ Answer what you can establish yourself — from the repo, the org brain, your
89
+ tools. Escalate to your human only for secrets, decisions that are genuinely
90
+ theirs, or a request to take an action with side effects.
91
+
92
+ ## What is NOT a problem
93
+
94
+ If `check_inbox` returns a message whose status is already `delivered`, that is
95
+ normal and nothing is wrong. `unread_only` means `pending` **or** `delivered`;
96
+ a message is only hidden once it is `read`. This is deliberate — it means a
97
+ call that died mid-flight cannot lose anything, and the server never marks a
98
+ message read on a read path. Only an explicit `mark_read` does that, which is
99
+ why the rule above is the one that matters.
@@ -1,164 +1,164 @@
1
- ---
2
- name: multiagent-brainstorm
3
- description: Brainstorm a design with another AgentHub agent, mostly autonomously. Use when you want two agents (e.g. krishi-dev ↔ sumit-mobile) to work through a topic together — a background subagent drives each side, polling the shared session and exchanging turns, pausing for a human only on real decisions, and concluding with a structured outcome that seeds an OpenSpec change.
4
- license: MIT
5
- ---
6
-
7
- # Multi-Agent Brainstorm
8
-
9
- Two AgentHub agents brainstorm a topic through a **server-tracked session**. Each
10
- side is driven by a **fully autonomous background subagent** that polls the
11
- session, reasons, and posts turns — surfacing to a human only when a decision
12
- genuinely needs one. A concluded brainstorm produces a structured outcome that
13
- seeds an OpenSpec change.
14
-
15
- Requires the server kill switch `AGENTHUB_BRAINSTORM_ENABLED=true` (tools return
16
- `brainstorm_disabled` otherwise) and `agent_register` first (the tools bind to
17
- your project). Runs on the latest Sonnet fine — no special model needed.
18
-
19
- ## Two roles
20
-
21
- You are one of:
22
-
23
- - **initiator** — your human said "brainstorm X with `<peer>`". You call
24
- `brainstorm_open`, which delivers an invite to the peer.
25
- - **responder** — you received a `[[BRAINSTORM INVITE]]` message (via your
26
- auto-inbox at session start, or mid-session). Call `brainstorm_accept` and
27
- mirror the initiator.
28
-
29
- If you got a brainstorm invite in your inbox, run the **responder** flow below.
30
- Otherwise, if the user asked you to brainstorm with someone, run **initiator**.
31
-
32
- ## Initiator flow
33
-
34
- 1. `brainstorm_open({ peer, topic, escalation })` — `escalation` is `local`
35
- (default; you'll ask your local human via a decision prompt) or `slack` (the
36
- subagent DMs the operator and polls for the reply). Note the returned
37
- `session_id`.
38
-
39
- **You cannot post the first turn until the peer accepts.** A session is `open`
40
- until then, and `brainstorm_turn` on a non-active session returns
41
- `brainstorm_not_active`. That is the state machine working, not a fault — do
42
- **not** call `brainstorm_accept` yourself to unblock it. The server refuses
43
- (`self_accept`); before it did, an initiator that accepted its own session
44
- ended up in both slots, which silently made `brainstorm_conclude` unreachable
45
- for the rest of the session.
46
- 2. **Spawn the autonomous subagent** (see below) with role `initiator`,
47
- the `session_id`, `after_seq=0`, the topic, and your human's framing.
48
- 3. Wait. Handle any `NEED_HUMAN` return (see *Human escalation*).
49
- 4. When the subagent reports `concluded`, run the **Conclusion → OpenSpec** step.
50
-
51
- ## Responder flow
52
-
53
- 1. `brainstorm_accept({ session_id })` — idempotent **for you**: re-accepting a
54
- session you already joined is safe if the invite was redelivered. Only the
55
- invited peer can accept. Accepting a session someone else already joined
56
- returns `brainstorm_already_accepted` naming the holder, and the initiator
57
- accepting its own session returns `self_accept`.
58
- 2. Spawn the autonomous subagent with role `responder`, the `session_id`,
59
- `after_seq=0`, and the topic from the invite.
60
- 3. Handle `NEED_HUMAN` the same way. When the subagent reports `concluded`, you're
61
- done — **only the initiator authors the OpenSpec** (avoids double-proposing).
62
-
63
- ## The autonomous subagent
64
-
65
- Spawn it with the `Agent` tool (background). Give it this loop, verbatim in
66
- spirit — it holds the whole transcript in its own context so your main session
67
- stays clean:
68
-
69
- ```
70
- after_seq = 0
71
- loop:
72
- { turns, state, turn_count } = brainstorm_poll(session_id, after_seq)
73
- after_seq = max(seq of turns, after_seq)
74
-
75
- if state != "active":
76
- return { done: state } # concluded | aborted | exhausted | abandoned
77
-
78
- peer_turns = turns authored by the OTHER agent
79
- if peer's latest turn.kind == "propose_conclude":
80
- if you agree with their outcome:
81
- brainstorm_conclude(session_id, outcome) # mutual consensus
82
- else:
83
- brainstorm_turn(session_id, "<why not yet, what's open>")
84
- continue
85
-
86
- if it's your turn (peer has posted since your last, or you're the initiator on seq 0):
87
- reason about the dialogue and form your next contribution
88
- if a decision here really needs a human (scope, tradeoff, commitment):
89
- return { need_human: { question, digest, after_seq } }
90
- else:
91
- brainstorm_turn(session_id, "<your turn>")
92
- # when you believe you're done, post kind="propose_conclude" with a draft outcome instead
93
- continue
94
-
95
- # nothing new and not your move → wait for the peer
96
- backoff sleep (start ~5s, cap ~30s), then re-poll
97
- # if last_turn_at is older than the silence deadline, brainstorm_close(state="abandoned")
98
- ```
99
-
100
- **Discipline:** one contribution per turn; stay on the topic; don't rubber-stamp
101
- — push back when the design isn't right yet; propose_conclude only when the
102
- problem, approach, and key decisions are actually settled.
103
-
104
- ## Human escalation (return-and-resume)
105
-
106
- A background subagent can't ask a human directly. When it returns
107
- `{ need_human: { question, digest, after_seq } }`:
108
-
109
- - **`escalation=local`** — ask your human with `AskUserQuestion` (include the
110
- `digest` for context).
111
- - **`escalation=slack`** — `slack_dm` the operator and poll your inbox for the
112
- reply.
113
-
114
- Then **resume the same subagent** (SendMessage to its agent id, context intact)
115
- with the human's answer and the `after_seq` it gave you. It posts the
116
- human-informed turn and continues. Do **not** spawn a fresh subagent — you'd lose
117
- the transcript.
118
-
119
- ## Peer is a headless daemon?
120
-
121
- Employee daemons (eng-ic, expert, …) can't run a live loop — one inbound message
122
- is one shift. If the peer never `brainstorm_accept`s but replies via ordinary
123
- A2A, the subagent should **fall back to async round-trips**: post a turn, then
124
- `check_inbox`/`brainstorm_poll` on a longer cadence, one shift per turn. The
125
- session still tracks turns; you just can't expect a mirror subagent on their end.
126
-
127
- ## Conclusion → OpenSpec (initiator only)
128
-
129
- On `concluded`, `brainstorm_get(session_id)` returns the structured `outcome`
130
- (`problem`, `agreed_approach`, `key_decisions`, `open_questions`,
131
- `suggested_change_id`, `summary`). Then:
132
-
133
- 1. **Render the outcome to your human** and ask (via `AskUserQuestion`): author
134
- the OpenSpec now? — matches the repo's plan-first mandate; a human verifies the
135
- agreed design before any spec is written.
136
- 2. On approval, invoke the **`openspec:proposal`** skill seeded from the outcome
137
- (use `suggested_change_id` as the change id), then `openspec_publish` to sync
138
- to AgentHub (the mandate: a change on disk only isn't done).
139
- 3. `brainstorm_link_change(session_id, change_id)` to stamp the change onto the
140
- session — closes the traceability loop (brainstorm → change).
141
-
142
- ## Stopping early
143
-
144
- Either operator can halt: `brainstorm_close({ session_id, reason })` →
145
- `aborted`. This works from `open` as well as `active`, so an initiator can
146
- withdraw an invite nobody accepted.
147
-
148
- Both safety backstops fire automatically, so a runaway loop or an offline peer
149
- can't hang: `exhausted` at `max_turns`, and `abandoned` once a session has been
150
- silent past `silence_deadline_secs` (default 3600). The silence backstop covers
151
- two cases — an `active` session with no new turn, and an `open` invite nobody
152
- accepted. A session the backstop closed says so in `closed_by`, so it is
153
- distinguishable from one a human stopped.
154
-
155
- Set `silence_deadline_secs` deliberately at open time if your peer is a headless
156
- daemon or a human decision is likely mid-session: the deadline is measured from
157
- the last turn, so a long escalation counts as silence.
158
-
159
- ## Tool reference
160
-
161
- `brainstorm_open` · `brainstorm_accept` · `brainstorm_turn` · `brainstorm_poll` ·
162
- `brainstorm_conclude` · `brainstorm_close` · `brainstorm_get` ·
163
- `brainstorm_link_change`. Full design: the `multiagent-brainstorm-design` doc;
164
- guide: `multiagent-brainstorm-guide`.
1
+ ---
2
+ name: multiagent-brainstorm
3
+ description: Brainstorm a design with another AgentHub agent, mostly autonomously. Use when you want two agents (e.g. krishi-dev ↔ sumit-mobile) to work through a topic together — a background subagent drives each side, polling the shared session and exchanging turns, pausing for a human only on real decisions, and concluding with a structured outcome that seeds an OpenSpec change.
4
+ license: MIT
5
+ ---
6
+
7
+ # Multi-Agent Brainstorm
8
+
9
+ Two AgentHub agents brainstorm a topic through a **server-tracked session**. Each
10
+ side is driven by a **fully autonomous background subagent** that polls the
11
+ session, reasons, and posts turns — surfacing to a human only when a decision
12
+ genuinely needs one. A concluded brainstorm produces a structured outcome that
13
+ seeds an OpenSpec change.
14
+
15
+ Requires the server kill switch `AGENTHUB_BRAINSTORM_ENABLED=true` (tools return
16
+ `brainstorm_disabled` otherwise) and `agent_register` first (the tools bind to
17
+ your project). Runs on the latest Sonnet fine — no special model needed.
18
+
19
+ ## Two roles
20
+
21
+ You are one of:
22
+
23
+ - **initiator** — your human said "brainstorm X with `<peer>`". You call
24
+ `brainstorm_open`, which delivers an invite to the peer.
25
+ - **responder** — you received a `[[BRAINSTORM INVITE]]` message (via your
26
+ auto-inbox at session start, or mid-session). Call `brainstorm_accept` and
27
+ mirror the initiator.
28
+
29
+ If you got a brainstorm invite in your inbox, run the **responder** flow below.
30
+ Otherwise, if the user asked you to brainstorm with someone, run **initiator**.
31
+
32
+ ## Initiator flow
33
+
34
+ 1. `brainstorm_open({ peer, topic, escalation })` — `escalation` is `local`
35
+ (default; you'll ask your local human via a decision prompt) or `slack` (the
36
+ subagent DMs the operator and polls for the reply). Note the returned
37
+ `session_id`.
38
+
39
+ **You cannot post the first turn until the peer accepts.** A session is `open`
40
+ until then, and `brainstorm_turn` on a non-active session returns
41
+ `brainstorm_not_active`. That is the state machine working, not a fault — do
42
+ **not** call `brainstorm_accept` yourself to unblock it. The server refuses
43
+ (`self_accept`); before it did, an initiator that accepted its own session
44
+ ended up in both slots, which silently made `brainstorm_conclude` unreachable
45
+ for the rest of the session.
46
+ 2. **Spawn the autonomous subagent** (see below) with role `initiator`,
47
+ the `session_id`, `after_seq=0`, the topic, and your human's framing.
48
+ 3. Wait. Handle any `NEED_HUMAN` return (see *Human escalation*).
49
+ 4. When the subagent reports `concluded`, run the **Conclusion → OpenSpec** step.
50
+
51
+ ## Responder flow
52
+
53
+ 1. `brainstorm_accept({ session_id })` — idempotent **for you**: re-accepting a
54
+ session you already joined is safe if the invite was redelivered. Only the
55
+ invited peer can accept. Accepting a session someone else already joined
56
+ returns `brainstorm_already_accepted` naming the holder, and the initiator
57
+ accepting its own session returns `self_accept`.
58
+ 2. Spawn the autonomous subagent with role `responder`, the `session_id`,
59
+ `after_seq=0`, and the topic from the invite.
60
+ 3. Handle `NEED_HUMAN` the same way. When the subagent reports `concluded`, you're
61
+ done — **only the initiator authors the OpenSpec** (avoids double-proposing).
62
+
63
+ ## The autonomous subagent
64
+
65
+ Spawn it with the `Agent` tool (background). Give it this loop, verbatim in
66
+ spirit — it holds the whole transcript in its own context so your main session
67
+ stays clean:
68
+
69
+ ```
70
+ after_seq = 0
71
+ loop:
72
+ { turns, state, turn_count } = brainstorm_poll(session_id, after_seq)
73
+ after_seq = max(seq of turns, after_seq)
74
+
75
+ if state != "active":
76
+ return { done: state } # concluded | aborted | exhausted | abandoned
77
+
78
+ peer_turns = turns authored by the OTHER agent
79
+ if peer's latest turn.kind == "propose_conclude":
80
+ if you agree with their outcome:
81
+ brainstorm_conclude(session_id, outcome) # mutual consensus
82
+ else:
83
+ brainstorm_turn(session_id, "<why not yet, what's open>")
84
+ continue
85
+
86
+ if it's your turn (peer has posted since your last, or you're the initiator on seq 0):
87
+ reason about the dialogue and form your next contribution
88
+ if a decision here really needs a human (scope, tradeoff, commitment):
89
+ return { need_human: { question, digest, after_seq } }
90
+ else:
91
+ brainstorm_turn(session_id, "<your turn>")
92
+ # when you believe you're done, post kind="propose_conclude" with a draft outcome instead
93
+ continue
94
+
95
+ # nothing new and not your move → wait for the peer
96
+ backoff sleep (start ~5s, cap ~30s), then re-poll
97
+ # if last_turn_at is older than the silence deadline, brainstorm_close(state="abandoned")
98
+ ```
99
+
100
+ **Discipline:** one contribution per turn; stay on the topic; don't rubber-stamp
101
+ — push back when the design isn't right yet; propose_conclude only when the
102
+ problem, approach, and key decisions are actually settled.
103
+
104
+ ## Human escalation (return-and-resume)
105
+
106
+ A background subagent can't ask a human directly. When it returns
107
+ `{ need_human: { question, digest, after_seq } }`:
108
+
109
+ - **`escalation=local`** — ask your human with `AskUserQuestion` (include the
110
+ `digest` for context).
111
+ - **`escalation=slack`** — `slack_dm` the operator and poll your inbox for the
112
+ reply.
113
+
114
+ Then **resume the same subagent** (SendMessage to its agent id, context intact)
115
+ with the human's answer and the `after_seq` it gave you. It posts the
116
+ human-informed turn and continues. Do **not** spawn a fresh subagent — you'd lose
117
+ the transcript.
118
+
119
+ ## Peer is a headless daemon?
120
+
121
+ Employee daemons (eng-ic, expert, …) can't run a live loop — one inbound message
122
+ is one shift. If the peer never `brainstorm_accept`s but replies via ordinary
123
+ A2A, the subagent should **fall back to async round-trips**: post a turn, then
124
+ `check_inbox`/`brainstorm_poll` on a longer cadence, one shift per turn. The
125
+ session still tracks turns; you just can't expect a mirror subagent on their end.
126
+
127
+ ## Conclusion → OpenSpec (initiator only)
128
+
129
+ On `concluded`, `brainstorm_get(session_id)` returns the structured `outcome`
130
+ (`problem`, `agreed_approach`, `key_decisions`, `open_questions`,
131
+ `suggested_change_id`, `summary`). Then:
132
+
133
+ 1. **Render the outcome to your human** and ask (via `AskUserQuestion`): author
134
+ the OpenSpec now? — matches the repo's plan-first mandate; a human verifies the
135
+ agreed design before any spec is written.
136
+ 2. On approval, invoke the **`openspec:proposal`** skill seeded from the outcome
137
+ (use `suggested_change_id` as the change id), then `openspec_publish` to sync
138
+ to AgentHub (the mandate: a change on disk only isn't done).
139
+ 3. `brainstorm_link_change(session_id, change_id)` to stamp the change onto the
140
+ session — closes the traceability loop (brainstorm → change).
141
+
142
+ ## Stopping early
143
+
144
+ Either operator can halt: `brainstorm_close({ session_id, reason })` →
145
+ `aborted`. This works from `open` as well as `active`, so an initiator can
146
+ withdraw an invite nobody accepted.
147
+
148
+ Both safety backstops fire automatically, so a runaway loop or an offline peer
149
+ can't hang: `exhausted` at `max_turns`, and `abandoned` once a session has been
150
+ silent past `silence_deadline_secs` (default 3600). The silence backstop covers
151
+ two cases — an `active` session with no new turn, and an `open` invite nobody
152
+ accepted. A session the backstop closed says so in `closed_by`, so it is
153
+ distinguishable from one a human stopped.
154
+
155
+ Set `silence_deadline_secs` deliberately at open time if your peer is a headless
156
+ daemon or a human decision is likely mid-session: the deadline is measured from
157
+ the last turn, so a long escalation counts as silence.
158
+
159
+ ## Tool reference
160
+
161
+ `brainstorm_open` · `brainstorm_accept` · `brainstorm_turn` · `brainstorm_poll` ·
162
+ `brainstorm_conclude` · `brainstorm_close` · `brainstorm_get` ·
163
+ `brainstorm_link_change`. Full design: the `multiagent-brainstorm-design` doc;
164
+ guide: `multiagent-brainstorm-guide`.