From c841f46e258575ad82e6951b4b7ebdf5527efc6c Mon Sep 17 00:00:00 2001 From: Darren Cheng Date: Tue, 28 Apr 2026 01:11:10 -0700 Subject: [PATCH 1/2] handoff: write to Argus KB by default, fall back to clipboard Save handoffs as markdown files under memory/handoff/ in the Argus KB so the receiving agent can pull them with kb_read or kb_search across thread boundaries. Only fall back to pbcopy when the KB tool is unavailable. --- agents/skills/handoff/SKILL.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/agents/skills/handoff/SKILL.md b/agents/skills/handoff/SKILL.md index 7d106e81..c1ac3e97 100644 --- a/agents/skills/handoff/SKILL.md +++ b/agents/skills/handoff/SKILL.md @@ -61,12 +61,17 @@ Keep it concise but complete enough that the receiving agent can continue withou ### Output procedure -1. Write the handoff text (raw markdown, no wrapping code fence) to `/tmp/handoff.md` using the Write tool. -2. Display the file contents to the user inside a fenced code block. -3. Copy to clipboard: `cat /tmp/handoff.md | pbcopy` -4. Confirm: "Copied to clipboard." +The Argus knowledge base is the primary destination for handoffs — they persist across threads and the receiving agent can pull them with `kb_read` or `kb_search`. Clipboard is only a fallback when the KB is unavailable. -Writing to a file first guarantees the clipboard content preserves all newlines and formatting exactly as displayed. +1. Generate a short slug for the handoff: lowercase, hyphenated, derived from the title (e.g. `ci-fix`, `migrate-auth`). +2. Compute a path: `memory/handoff/-.md`. Get the timestamp with `date +%Y-%m-%d-%H%M`. +3. Write the handoff text (raw markdown, no wrapping code fence) to `/tmp/handoff.md` using the Write tool. +4. Display the file contents to the user inside a fenced code block. +5. Save to Argus KB: call `mcp__argus__kb_ingest` (or `mcp__argus-kb__kb_ingest` — whichever tool is registered) with the computed path and the handoff content. + - On success, confirm: `Saved to KB at \`\`. Next agent: \`kb_read("")\` or \`kb_search("")\`.` +6. If neither KB ingest tool is available, or the call fails, fall back to clipboard: run `cat /tmp/handoff.md | pbcopy` and confirm: `KB unavailable — copied to clipboard instead.` + +Writing to a file first guarantees the content preserves all newlines and formatting exactly as displayed, regardless of whether it ends up in the KB or the clipboard. --- From eed6f111e7a783247d543746629d7058af7024c9 Mon Sep 17 00:00:00 2001 From: Darren Cheng Date: Tue, 28 Apr 2026 01:16:00 -0700 Subject: [PATCH 2/2] handoff: address review findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Require YAML frontmatter (title, tags) — Argus KB schema mandates it. - Sanitize the slug to lowercase kebab-case so a hostile title can't traverse out of memory/handoff/. - Switch to seconds in the timestamp so two same-minute invocations don't collide on the same path. - Use a timestamped temp file (/tmp/handoff-.md) instead of a fixed name so concurrent invocations don't overwrite each other. - Specify a primary tool name (mcp__argus__kb_ingest) and document the alternate (mcp__argus-kb__kb_ingest) instead of asking Claude to introspect which is registered — it can't. - Replace the escaped-backtick confirmation template with prose so it survives layered markdown quoting. - Add a date-failure fallback (random hex suffix). - Document the receiving-agent UX: kb_list("memory/handoff/") sorts by timestamp prefix so the latest is highest-sorted. --- agents/skills/handoff/SKILL.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/agents/skills/handoff/SKILL.md b/agents/skills/handoff/SKILL.md index c1ac3e97..2ffb0309 100644 --- a/agents/skills/handoff/SKILL.md +++ b/agents/skills/handoff/SKILL.md @@ -61,17 +61,28 @@ Keep it concise but complete enough that the receiving agent can continue withou ### Output procedure -The Argus knowledge base is the primary destination for handoffs — they persist across threads and the receiving agent can pull them with `kb_read` or `kb_search`. Clipboard is only a fallback when the KB is unavailable. +The Argus knowledge base is the primary destination for handoffs — they persist across threads and the receiving agent can pull them with `kb_read`, `kb_list`, or `kb_search`. Clipboard is only a fallback when the KB is unavailable. -1. Generate a short slug for the handoff: lowercase, hyphenated, derived from the title (e.g. `ci-fix`, `migrate-auth`). -2. Compute a path: `memory/handoff/-.md`. Get the timestamp with `date +%Y-%m-%d-%H%M`. -3. Write the handoff text (raw markdown, no wrapping code fence) to `/tmp/handoff.md` using the Write tool. -4. Display the file contents to the user inside a fenced code block. -5. Save to Argus KB: call `mcp__argus__kb_ingest` (or `mcp__argus-kb__kb_ingest` — whichever tool is registered) with the computed path and the handoff content. - - On success, confirm: `Saved to KB at \`\`. Next agent: \`kb_read("")\` or \`kb_search("")\`.` -6. If neither KB ingest tool is available, or the call fails, fall back to clipboard: run `cat /tmp/handoff.md | pbcopy` and confirm: `KB unavailable — copied to clipboard instead.` +1. **Slug.** Derive a slug from the handoff title: lowercase kebab-case. Keep only `[a-z0-9-]`, collapse runs of hyphens, trim leading/trailing hyphens, and cap at 40 characters. If empty after sanitization, use `handoff`. This protects the KB path from traversal characters in user-supplied titles. +2. **Timestamp.** Run `date +%Y-%m-%d-%H%M%S`. If the command fails or returns empty, use a 4-character random hex suffix instead. Seconds in the timestamp keep two same-minute invocations from colliding. +3. **Paths.** KB path: `memory/handoff/-.md`. Temp file: `/tmp/handoff-.md` (timestamped so concurrent invocations don't overwrite each other). +4. **Document.** Build the full document with YAML frontmatter at the top — Argus KB requires `title` and `tags`: -Writing to a file first guarantees the content preserves all newlines and formatting exactly as displayed, regardless of whether it ends up in the KB or the clipboard. + ``` + --- + title: "" + tags: [handoff, ] + --- + + + ``` + +5. Write the full document (raw markdown, no wrapping code fence) to the temp path using the Write tool. +6. Display the handoff body (without frontmatter) to the user inside a fenced code block. +7. **Save to KB.** Call `mcp__argus__kb_ingest` with the KB path and the full document. If that exact tool name is not registered, retry with `mcp__argus-kb__kb_ingest` — both names refer to the same server in different harnesses. On success, tell the user: handoff saved to the KB path, and the receiving agent can find it with `kb_list("memory/handoff/")` (latest is highest-sorted by timestamp) or `kb_search("")`. Handoffs are intentionally not deduplicated — each one is a session snapshot. +8. **Clipboard fallback.** If the Argus KB MCP server is not running (both tool names return tool-not-found, or the ingest call returns a server error), run `cat | pbcopy` and report: KB unavailable — copied to clipboard instead. + +Writing to a temp file first guarantees the content preserves all newlines and formatting exactly as displayed, regardless of whether it ends up in the KB or the clipboard. ---