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.
- package/README.md +3 -3
- package/dist/brain/memvidBrain.d.ts +22 -0
- package/dist/brain/memvidBrain.d.ts.map +1 -1
- package/dist/brain/memvidBrain.js +41 -2
- package/dist/brain/memvidBrain.js.map +1 -1
- package/dist/brain/memvidBrain.test.js +90 -0
- package/dist/brain/memvidBrain.test.js.map +1 -1
- package/dist/brain/migrate.d.ts +43 -0
- package/dist/brain/migrate.d.ts.map +1 -1
- package/dist/brain/migrate.js +148 -23
- package/dist/brain/migrate.js.map +1 -1
- package/dist/brain/migrate.test.js +194 -1
- package/dist/brain/migrate.test.js.map +1 -1
- package/dist/channel.js +47 -5
- package/dist/channel.js.map +1 -1
- package/dist/channelDiagnostics.d.ts +36 -0
- package/dist/channelDiagnostics.d.ts.map +1 -1
- package/dist/channelDiagnostics.js +65 -0
- package/dist/channelDiagnostics.js.map +1 -1
- package/dist/channelDiagnostics.test.js +81 -1
- package/dist/channelDiagnostics.test.js.map +1 -1
- package/dist/client.d.ts +17 -0
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +32 -0
- package/dist/client.js.map +1 -1
- package/dist/daemon.js +16 -22
- package/dist/daemon.js.map +1 -1
- package/dist/index.js +36 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/pending-items.d.ts +63 -0
- package/dist/lib/pending-items.d.ts.map +1 -0
- package/dist/lib/pending-items.js +96 -0
- package/dist/lib/pending-items.js.map +1 -0
- package/dist/pinSweep.d.ts +83 -0
- package/dist/pinSweep.d.ts.map +1 -0
- package/dist/pinSweep.js +105 -0
- package/dist/pinSweep.js.map +1 -0
- package/dist/pinSweep.test.d.ts +12 -0
- package/dist/pinSweep.test.d.ts.map +1 -0
- package/dist/pinSweep.test.js +110 -0
- package/dist/pinSweep.test.js.map +1 -0
- package/dist/pinSweepCli.d.ts +20 -0
- package/dist/pinSweepCli.d.ts.map +1 -0
- package/dist/pinSweepCli.js +287 -0
- package/dist/pinSweepCli.js.map +1 -0
- package/dist/run-claude.sh +36 -5
- package/dist/sessionCapture.d.ts.map +1 -1
- package/dist/sessionCapture.js +7 -1
- package/dist/sessionCapture.js.map +1 -1
- package/dist/sessionCapture.test.js +20 -0
- package/dist/sessionCapture.test.js.map +1 -1
- package/dist/setup.js +11 -0
- package/dist/setup.js.map +1 -1
- package/dist/shiftFiles.d.ts +33 -0
- package/dist/shiftFiles.d.ts.map +1 -0
- package/dist/shiftFiles.js +57 -0
- package/dist/shiftFiles.js.map +1 -0
- package/dist/shiftFiles.test.d.ts +2 -0
- package/dist/shiftFiles.test.d.ts.map +1 -0
- package/dist/shiftFiles.test.js +141 -0
- package/dist/shiftFiles.test.js.map +1 -0
- package/dist/skillInstaller.d.ts.map +1 -1
- package/dist/skillInstaller.gate.test.js +2 -0
- package/dist/skillInstaller.gate.test.js.map +1 -1
- package/dist/skillInstaller.js +8 -0
- package/dist/skillInstaller.js.map +1 -1
- package/dist/skillInstaller.test.js +8 -1
- package/dist/skillInstaller.test.js.map +1 -1
- package/dist/tools/goshtiRead.d.ts +72 -0
- package/dist/tools/goshtiRead.d.ts.map +1 -0
- package/dist/tools/goshtiRead.js +274 -0
- package/dist/tools/goshtiRead.js.map +1 -0
- package/dist/tools/goshtiRead.test.d.ts +8 -0
- package/dist/tools/goshtiRead.test.d.ts.map +1 -0
- package/dist/tools/goshtiRead.test.js +182 -0
- package/dist/tools/goshtiRead.test.js.map +1 -0
- package/dist/tools/inboxBounds.d.ts +80 -0
- package/dist/tools/inboxBounds.d.ts.map +1 -0
- package/dist/tools/inboxBounds.js +105 -0
- package/dist/tools/inboxBounds.js.map +1 -0
- package/dist/tools/inboxBounds.test.d.ts +15 -0
- package/dist/tools/inboxBounds.test.d.ts.map +1 -0
- package/dist/tools/inboxBounds.test.js +135 -0
- package/dist/tools/inboxBounds.test.js.map +1 -0
- package/dist/tools/index.d.ts +11 -0
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +106 -102
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/intakeRequests.d.ts +35 -0
- package/dist/tools/intakeRequests.d.ts.map +1 -0
- package/dist/tools/intakeRequests.js +344 -0
- package/dist/tools/intakeRequests.js.map +1 -0
- package/dist/tools/intakeRequests.test.d.ts +8 -0
- package/dist/tools/intakeRequests.test.d.ts.map +1 -0
- package/dist/tools/intakeRequests.test.js +183 -0
- package/dist/tools/intakeRequests.test.js.map +1 -0
- package/dist/tools/openspec-viz/taskSync.d.ts +115 -0
- package/dist/tools/openspec-viz/taskSync.d.ts.map +1 -0
- package/dist/tools/openspec-viz/taskSync.js +144 -0
- package/dist/tools/openspec-viz/taskSync.js.map +1 -0
- package/dist/tools/openspec-viz/taskSync.test.d.ts +2 -0
- package/dist/tools/openspec-viz/taskSync.test.d.ts.map +1 -0
- package/dist/tools/openspec-viz/taskSync.test.js +198 -0
- package/dist/tools/openspec-viz/taskSync.test.js.map +1 -0
- package/dist/tools/pushedItemsSafety.test.d.ts +12 -0
- package/dist/tools/pushedItemsSafety.test.d.ts.map +1 -0
- package/dist/tools/pushedItemsSafety.test.js +179 -0
- package/dist/tools/pushedItemsSafety.test.js.map +1 -0
- package/dist/tools/tools.test.js +17 -5
- package/dist/tools/tools.test.js.map +1 -1
- package/dist/tools/wrapperCost.test.d.ts +13 -0
- package/dist/tools/wrapperCost.test.d.ts.map +1 -0
- package/dist/tools/wrapperCost.test.js +149 -0
- package/dist/tools/wrapperCost.test.js.map +1 -0
- package/dist/websocket.d.ts +30 -1
- package/dist/websocket.d.ts.map +1 -1
- package/dist/websocket.js +40 -3
- package/dist/websocket.js.map +1 -1
- package/dist/websocketQueue.test.d.ts +10 -0
- package/dist/websocketQueue.test.d.ts.map +1 -0
- package/dist/websocketQueue.test.js +78 -0
- package/dist/websocketQueue.test.js.map +1 -0
- package/package.json +4 -4
- package/skills/catalog.json +23 -10
- package/skills/commands/close-session.md +144 -144
- package/skills/commands/start-session.md +25 -6
- package/skills/manifest.json +8 -1
- package/skills/skills/code-brain-hook/SKILL.md +61 -61
- package/skills/skills/file-bug/SKILL.md +75 -75
- package/skills/skills/inbox/SKILL.md +99 -0
- 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`.
|