agenthub-multiagent-mcp 1.15.1 → 1.15.2
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/package.json
CHANGED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: close-session
|
|
3
|
+
description: Deterministic checklist to wrap up an agent session cleanly across all AgentHub persistence layers (org brain, local `.mv2`, auto-memory, session snapshot). The heavy prose + MCP work is delegated to a Sonnet subagent to preserve the Opus budget.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Close Session
|
|
7
|
+
|
|
8
|
+
Run this at the end of any work session in the Agenthub repo.
|
|
9
|
+
|
|
10
|
+
The main session does two cheap steps itself, then delegates the expensive prose-generation + MCP-write work to a Sonnet subagent via the `Agent` tool. Sonnet has a separate usage cap from Opus, so this keeps the Opus budget free for real work.
|
|
11
|
+
|
|
12
|
+
## Step 1 (main session) — Verify local brain capture
|
|
13
|
+
|
|
14
|
+
Run this from the main Opus session (it needs the live environment context):
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
ls -la ~/.claude/brains/ | grep $(whoami)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Confirm `<agent-id>.mv2` was modified in the last ~2 minutes. If the mtime is stale, the brainCapture hook didn't fire cleanly — note this and continue, but flag it in the handoff.
|
|
21
|
+
|
|
22
|
+
## Step 2 (main session) — Compile a brief for the subagent
|
|
23
|
+
|
|
24
|
+
Produce a *compact* bullet brief (target ~500–1000 output tokens, not 3000+) that the Sonnet subagent will expand into full prose. Collect:
|
|
25
|
+
|
|
26
|
+
- **Session topic** — one line.
|
|
27
|
+
- **Commits pushed this session** — run `rtk git log --oneline origin/main~10..HEAD` or equivalent to get hashes + subjects.
|
|
28
|
+
- **Uncommitted state** — `rtk git status` output, trimmed.
|
|
29
|
+
- **Key facts worth sharing to org brain** — 3–10 bullets, each with an implicit category (decision / convention / architecture / blocker / alert / insight). Do NOT write them as final prose — one-line hints are enough; the subagent will polish.
|
|
30
|
+
- **Open threads / blockers** — one line each.
|
|
31
|
+
- **Next session plan** — 1–3 lines.
|
|
32
|
+
|
|
33
|
+
Keep it tight. The subagent will expand; you are not writing the final artifact.
|
|
34
|
+
|
|
35
|
+
## Step 3 (main session) — Delegate everything else to a Sonnet subagent
|
|
36
|
+
|
|
37
|
+
Invoke the `Agent` tool:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
Agent(
|
|
41
|
+
description: "Close session handoff",
|
|
42
|
+
subagent_type: "general-purpose",
|
|
43
|
+
model: "sonnet",
|
|
44
|
+
prompt: <<<subagent prompt below, with the brief appended>>>
|
|
45
|
+
)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Subagent prompt (paste the body, append your compact brief from Step 2 after):**
|
|
49
|
+
|
|
50
|
+
> You are closing out a work session for the user. You must complete every step below in order. Each step has a concrete side effect — no skipping. Return a short confirmation at the end, not full prose.
|
|
51
|
+
>
|
|
52
|
+
> Use the **BRIEF** below (provided after this prompt) as your source material. Expand it into the artifacts described.
|
|
53
|
+
>
|
|
54
|
+
> ### A. Write shareable knowledge to org brain
|
|
55
|
+
>
|
|
56
|
+
> For each key fact in the BRIEF, call `mcp__agenthub__brain_write_knowledge` with:
|
|
57
|
+
> - `category` — one of `decision`, `convention`, `architecture`, `blocker`, `alert`, `insight`.
|
|
58
|
+
> - `fact` — one short sentence. Dedup is exact-match normalized on this field; rewordings of something already saved are no-ops.
|
|
59
|
+
> - `detail` — the rationale, context, or reference link.
|
|
60
|
+
> - `project` — `agenthub`.
|
|
61
|
+
>
|
|
62
|
+
> If the BRIEF lists no shareable facts, skip — don't fabricate.
|
|
63
|
+
>
|
|
64
|
+
> ### B. Write a human-readable snapshot
|
|
65
|
+
>
|
|
66
|
+
> Use the `Write` tool to create `~/.claude/sessions/<YYYY-MM-DD>-<short-topic>.md` with these sections:
|
|
67
|
+
>
|
|
68
|
+
> - **What shipped** (commits with hashes, features, tests)
|
|
69
|
+
> - **What's paused / blocked** and why
|
|
70
|
+
> - **Outstanding state** (uncommitted changes, unpushed commits)
|
|
71
|
+
> - **Decisions worth remembering** (mirrors the org-brain entries from step A)
|
|
72
|
+
> - **Next session prompt** (paste-ready)
|
|
73
|
+
>
|
|
74
|
+
> Snapshot is for humans. Agents use org brain + local brain + the server report from step C.
|
|
75
|
+
>
|
|
76
|
+
> ### C. Upload the session report to AgentHub (MANDATORY)
|
|
77
|
+
>
|
|
78
|
+
> Call `mcp__agenthub__session_close_report` with:
|
|
79
|
+
> - `summary` — markdown covering what shipped + outstanding state. Paste-safe; will be passed through verbatim to the next session's `/start-session`.
|
|
80
|
+
> - `next_plan` — markdown covering what the next session should pick up.
|
|
81
|
+
> - `commits` — array of `{hash, subject}` for commits pushed this session (from the BRIEF).
|
|
82
|
+
> - `open_threads` — array of `{topic, blocker}` for unresolved items (from the BRIEF).
|
|
83
|
+
>
|
|
84
|
+
> This is what `/start-session` reads next, on ANY machine. Without it, cross-machine resume breaks. Server upserts on `(agent_id, session_id)` — idempotent.
|
|
85
|
+
>
|
|
86
|
+
> ### D. Clear the inbox
|
|
87
|
+
>
|
|
88
|
+
> Call `mcp__agenthub__check_inbox` with `unread_only: true`. For each message:
|
|
89
|
+
> - Addressed to this agent → reply via `mcp__agenthub__reply` or note the required action.
|
|
90
|
+
> - Not applicable → note and skip.
|
|
91
|
+
>
|
|
92
|
+
> Then call `mcp__agenthub__mark_read` to clear the unread flag. Do not mark read without processing — that hides coordination failures.
|
|
93
|
+
>
|
|
94
|
+
> ### E. Return a compact confirmation
|
|
95
|
+
>
|
|
96
|
+
> Return this structure (plain text, ~10 lines max):
|
|
97
|
+
>
|
|
98
|
+
> ```
|
|
99
|
+
> close-session complete.
|
|
100
|
+
> - Commits pushed: <N> (<hash short list>)
|
|
101
|
+
> - Knowledge entries written: <N> (<categories>)
|
|
102
|
+
> - Snapshot: ~/.claude/sessions/<filename>
|
|
103
|
+
> - Server report: uploaded (<session_id if available>)
|
|
104
|
+
> - Inbox: <N> processed, <M> unread (<brief reason>)
|
|
105
|
+
> - Follow-ups: <one line, or "none">
|
|
106
|
+
> ```
|
|
107
|
+
>
|
|
108
|
+
> Do NOT echo the full summary or next_plan back — the main session doesn't need them in context.
|
|
109
|
+
>
|
|
110
|
+
> ---
|
|
111
|
+
>
|
|
112
|
+
> **BRIEF:**
|
|
113
|
+
> <<<paste the compact brief from Step 2 here>>>
|
|
114
|
+
|
|
115
|
+
## Step 4 (main session) — Report out
|
|
116
|
+
|
|
117
|
+
When the subagent returns, relay its compact confirmation to the user. That's the handoff message. Do not re-generate the summary or next_plan — they are already persisted to AgentHub and the snapshot file.
|
|
118
|
+
|
|
119
|
+
## Why this is structured this way
|
|
120
|
+
|
|
121
|
+
- **Determinism** — every step has a concrete side effect (brain entries, snapshot file, server row, inbox state). Missing steps are visible as absent side effects, not as a model "forgetting."
|
|
122
|
+
- **Budget** — prose generation (summary, next_plan, snapshot) is the token-heavy part of closing a session. Sonnet generates at equivalent quality for this task and draws from a separate quota, so the Opus budget stays available for actual work.
|
|
123
|
+
- **Cross-machine resume** — the server report (Step C) is what `/start-session` reads on the next run, including runs on other machines or instances. Skipping it breaks cross-machine handoff.
|
|
124
|
+
|
|
125
|
+
## Red flags (still apply)
|
|
126
|
+
|
|
127
|
+
- "I'll skip the subagent and do it inline since the session was small" — WRONG. The point is to preserve the Opus budget; running inline defeats that regardless of session size.
|
|
128
|
+
- "I'll skip the brain writes since nothing felt important" — WRONG. Enumerate all shareable facts in the BRIEF; the subagent dedups via exact-match normalization. Overlap is free.
|
|
129
|
+
- "I'll skip the server report since the snapshot is local" — WRONG. Cross-machine resume depends on the server report.
|
|
130
|
+
- "I'll trim the BRIEF to save tokens" — WRONG in the other direction. Trim the final artifacts (handled by subagent), not the source facts. Missing facts = missing knowledge.
|
|
131
|
+
- "I have 5 minutes — I'll run a partial" — WRONG. A partial close creates worse handoff artifacts than no close. If you truly don't have time, tell the user so they can dispatch a cleanup agent, or run the full checklist when you return.
|
|
132
|
+
|
|
133
|
+
## Time budget
|
|
134
|
+
|
|
135
|
+
Main session: ~1–2 minutes (verify + compile brief). Subagent: runs in background while you do other things, typically 2–4 minutes wall-clock. No trimming.
|
|
@@ -9,44 +9,67 @@ tags: [session, handoff, agenthub]
|
|
|
9
9
|
|
|
10
10
|
Load the previous session's close report so the current session has context.
|
|
11
11
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
12
|
+
## How to run
|
|
13
|
+
|
|
14
|
+
Delegate the fetch + format work to a Sonnet subagent via the `Agent` tool. This keeps the main Opus session's budget free; Sonnet has a separate usage cap.
|
|
15
|
+
|
|
16
|
+
**Invoke exactly this:**
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Agent(
|
|
20
|
+
description: "Load previous session handoff",
|
|
21
|
+
subagent_type: "general-purpose",
|
|
22
|
+
model: "sonnet",
|
|
23
|
+
prompt: <<<the prompt below>>>
|
|
24
|
+
)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Subagent prompt (paste verbatim, do not rewrite):**
|
|
28
|
+
|
|
29
|
+
> You are loading the previous session's close report for the user.
|
|
30
|
+
>
|
|
31
|
+
> 1. Call `mcp__agenthub__session_last_report` with no arguments (defaults to the calling agent).
|
|
32
|
+
> 2. Inspect the response. It returns `{ "report": null | SessionReport }`.
|
|
33
|
+
> 3. **If `report` is null** — return this exact text and stop:
|
|
34
|
+
> ```
|
|
35
|
+
> No previous session report for this agent. Starting fresh.
|
|
36
|
+
> ```
|
|
37
|
+
> 4. **If `report` is non-null** — return the following markdown, filling in field values from the report. Pass `summary` and `next_plan` through VERBATIM — do not summarize, rewrite, or truncate them. The previous session wrote that prose for the next session; editorializing loses signal.
|
|
38
|
+
>
|
|
39
|
+
> ```markdown
|
|
40
|
+
> ## Previous session (closed {{created_at}})
|
|
41
|
+
>
|
|
42
|
+
> **Summary**
|
|
43
|
+
> {{summary}}
|
|
44
|
+
>
|
|
45
|
+
> **Planned next steps**
|
|
46
|
+
> {{next_plan}}
|
|
47
|
+
>
|
|
48
|
+
> **Commits** (omit heading and section if commits array is empty)
|
|
49
|
+
> - {{commits[i].hash}} {{commits[i].subject}}
|
|
50
|
+
>
|
|
51
|
+
> **Open threads** (omit heading and section if open_threads array is empty)
|
|
52
|
+
> - {{open_threads[i].topic}} — {{open_threads[i].blocker}}
|
|
53
|
+
> ```
|
|
54
|
+
>
|
|
55
|
+
> 5. If the MCP call fails (network, auth, server error), return a one-line error message — do not retry.
|
|
56
|
+
>
|
|
57
|
+
> Return ONLY the formatted markdown (or the null/error message). Do not add commentary, headers, or preamble.
|
|
58
|
+
|
|
59
|
+
## After the subagent returns
|
|
60
|
+
|
|
61
|
+
Echo the subagent's output to the user verbatim, then append a single line:
|
|
62
|
+
|
|
63
|
+
> **Pick up where we left off, or take a different direction?**
|
|
43
64
|
|
|
44
65
|
## Rules
|
|
45
66
|
|
|
46
67
|
- Do NOT auto-execute the "next plan" — context may have changed. Render and wait.
|
|
47
|
-
- Do NOT summarize or rewrite the report body — pass through
|
|
48
|
-
-
|
|
68
|
+
- Do NOT summarize or rewrite the report body — pass through as-is.
|
|
69
|
+
- The main session must not perform the MCP call or format the report itself. That work belongs to the Sonnet subagent so the Opus budget stays reserved for actual work.
|
|
49
70
|
|
|
50
71
|
## Why this exists
|
|
51
72
|
|
|
52
|
-
Sessions close by writing a report to AgentHub via `mcp__agenthub__session_close_report` (enforced by the
|
|
73
|
+
Sessions close by writing a report to AgentHub via `mcp__agenthub__session_close_report` (enforced by the `/close-session` command). Any new session on any machine can retrieve that report here, giving cross-machine and cross-instance continuity that the local-filesystem snapshots alone don't provide.
|
|
74
|
+
|
|
75
|
+
Delegation to Sonnet saves the Opus usage cap: the report render is a mechanical formatting task that Sonnet handles at equivalent quality and draws from a separate quota bucket.
|
package/skills/manifest.json
CHANGED
|
@@ -1,105 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: close-session
|
|
3
|
-
description: Deterministic checklist to wrap up an agent session cleanly across all four AgentHub persistence layers (org brain, local `.mv2`, auto-memory, session snapshot). Run every step. Not an LLM judgment call.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Close Session
|
|
7
|
-
|
|
8
|
-
Run this at the end of any work session in the Agenthub repo. Every step has a concrete action — no skipping.
|
|
9
|
-
|
|
10
|
-
**TodoWrite every step below as a todo before starting.** Checklists without TodoWrite get items dropped.
|
|
11
|
-
|
|
12
|
-
## 1. Write shareable knowledge to org brain
|
|
13
|
-
|
|
14
|
-
List every fact, decision, convention, architectural insight, alert, or blocker you identified this session that other agents would benefit from.
|
|
15
|
-
|
|
16
|
-
For each, call `mcp__agenthub__brain_write_knowledge` with:
|
|
17
|
-
- `category` — one of `decision`, `convention`, `architecture`, `blocker`, `alert`, `insight`.
|
|
18
|
-
- `fact` — one short sentence. Dedup is exact-match normalized on this field, so rewordings of something already saved are no-ops. That's fine — idempotent.
|
|
19
|
-
- `detail` — the rationale, context, or reference link.
|
|
20
|
-
- `project` — usually `agenthub`.
|
|
21
|
-
|
|
22
|
-
**Skip if:** nothing new — don't fabricate entries. An empty session is fine.
|
|
23
|
-
|
|
24
|
-
## 2. Verify the local brain capture hook fired
|
|
25
|
-
|
|
26
|
-
Check that `~/.claude/brains/<your-agent-id>.mv2` was modified in the last 2 minutes.
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
ls -la ~/.claude/brains/ | grep agenthub-agent
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
If the mtime is stale, the brainCapture hook didn't run — investigate before closing. Usually means the MCP session didn't end cleanly.
|
|
33
|
-
|
|
34
|
-
## 3. Append a session snapshot
|
|
35
|
-
|
|
36
|
-
Write a human-readable resume doc at `~/.claude/sessions/<YYYY-MM-DD>-<short-topic>.md`. It should cover:
|
|
37
|
-
|
|
38
|
-
- **What shipped** (commits with hashes, features, tests).
|
|
39
|
-
- **What's paused / blocked** and why.
|
|
40
|
-
- **Outstanding state** (uncommitted changes, unpushed commits).
|
|
41
|
-
- **Decisions worth remembering** (short bullets — these mirror what you wrote to org brain).
|
|
42
|
-
- **Next session prompt** — a paste-ready prompt to resume.
|
|
43
|
-
|
|
44
|
-
The snapshot is for *humans*, not agents. Agents use org brain + local brain + the session report uploaded in Step 3.5.
|
|
45
|
-
|
|
46
|
-
## 3.5. Upload the session report to AgentHub (MANDATORY)
|
|
47
|
-
|
|
48
|
-
Call `mcp__agenthub__session_close_report` with:
|
|
49
|
-
|
|
50
|
-
- `summary` — markdown covering what shipped this session. Same shape as Step 3's "What shipped" + "Outstanding state" combined. Paste-safe; passed through verbatim to the next session.
|
|
51
|
-
- `next_plan` — markdown covering what the next session should pick up. Same shape as Step 3's "Next session prompt".
|
|
52
|
-
- `commits` (optional) — array of `{hash, subject}` for commits pushed this session.
|
|
53
|
-
- `open_threads` (optional) — array of `{topic, blocker}` for unresolved items.
|
|
54
|
-
|
|
55
|
-
This is what `/start-session` reads in the next session — on ANY machine, ANY Claude instance. Without it, cross-machine resume is broken and the successor starts cold.
|
|
56
|
-
|
|
57
|
-
The server upserts on `(agent_id, session_id)` — calling twice is idempotent, not duplicative. If a detail was wrong, fix it and call again.
|
|
58
|
-
|
|
59
|
-
## 4. Clear your inbox
|
|
60
|
-
|
|
61
|
-
Run `mcp__agenthub__check_inbox` with `unread_only: true`. For each message:
|
|
62
|
-
|
|
63
|
-
- If addressed → reply via `mcp__agenthub__reply` or act on it.
|
|
64
|
-
- If not for you → forward or ignore.
|
|
65
|
-
|
|
66
|
-
Then `mcp__agenthub__mark_read` to clear the unread flag. Do **not** mark read without processing — that hides coordination failures.
|
|
67
|
-
|
|
68
|
-
## 5. Report out
|
|
69
|
-
|
|
70
|
-
Produce a compact summary — suitable for pasting into a handoff message:
|
|
71
|
-
|
|
72
|
-
- **Commits pushed:** `<hash> <subject>` list.
|
|
73
|
-
- **Knowledge entries created:** category + fact for each.
|
|
74
|
-
- **Inbox:** N processed, M unread (with reason).
|
|
75
|
-
- **Follow-ups:** anything the next agent / human should pick up.
|
|
76
|
-
|
|
77
|
-
Don't over-explain. This is a status report, not a narrative.
|
|
78
|
-
|
|
79
|
-
## Why this is a skill, not a prompt
|
|
80
|
-
|
|
81
|
-
Determinism means this is composable with automation — `loop` can run it every 2h for autonomous agents, and missing steps are visible as absent side-effects (no brain entries, no snapshot file) rather than a model forgetting.
|
|
82
|
-
|
|
83
|
-
## Red flags
|
|
84
|
-
|
|
85
|
-
- "I'll skip step 2 since the session wasn't productive" — WRONG. The hook fires regardless; verifying it fired is how you know persistence worked.
|
|
86
|
-
- "The hook runs automatically, verifying is belt-and-suspenders I don't have budget for" — WRONG. Hooks fail silently. The 5-second check is not ceremony, it's how silent data loss is caught.
|
|
87
|
-
- "Step 1 feels like overkill for this small change" — WRONG. If there's nothing to share, step 1 is a no-op. Don't decide in advance.
|
|
88
|
-
- "I already wrote one entry mid-session, that's enough — skip the rest unless something surprised me" — WRONG. Enumerate *all* shareable facts. Dedup is idempotent; overlap is free. Deciding in advance that more aren't worth it is the violation.
|
|
89
|
-
- "I'll just summarize in chat instead of writing a snapshot" — WRONG. Chat isn't searchable by future agents. Write the snapshot.
|
|
90
|
-
- "I wrote the local snapshot, that's enough — skip Step 3.5" — WRONG. The local snapshot is machine-local. The server upload is what `/start-session` reads on the next run, including runs on other machines or other Claude instances. Skipping it means cross-machine resume breaks.
|
|
91
|
-
- "A snapshot is only worth writing if there's an unfinished thread to pick up" — WRONG. The snapshot is not a TODO list; it is the human-readable record that *this work happened*. Write it every time, thread or no thread.
|
|
92
|
-
- "I have 15 minutes and realistically this is a 20-minute job — I'll do a trimmed version" — WRONG. See "Time budget" below. Trimmed versions defeat the point.
|
|
93
|
-
|
|
94
|
-
## Time budget
|
|
95
|
-
|
|
96
|
-
Full checklist is 5–8 minutes for a typical session, not 10+. If you think it's 10+, you're probably narrating instead of acting — tools run in parallel, `brain_write_knowledge` calls are independent.
|
|
97
|
-
|
|
98
|
-
**If you genuinely don't have ~8 minutes right now:** do NOT run a trimmed checklist. A partial close creates worse handoff artifacts than no close — the next agent sees a snapshot that looks complete but missed brain writes, or inbox marked read without replies.
|
|
99
|
-
|
|
100
|
-
Instead:
|
|
101
|
-
1. Post one message to yourself (or your user) saying "session not closed — will finish at <specific time>."
|
|
102
|
-
2. Do the full checklist when you return.
|
|
103
|
-
3. If that's not possible, tell your user — they can dispatch a cleanup agent.
|
|
104
|
-
|
|
105
|
-
"Trimmed C" is the failure mode this skill exists to prevent.
|