docs(mcp): nudge handoff toward reusing existing items

[getappz]

Summary

• handoff tool description + item_id param description now spell out that omitting item_id always mints a new item, and to pass it when the work already has a home item
• Nudges toward comment (action=create) + item (action=update, assignee_agent=...) as the lighter alternative when a handoff is just a plain-text status update with no versioned artifact to attach
• Same guidance added to the /handoff slash-command prompt grammar

Prompted by a duplicate item (#216) created via handoff for a status update that already had a home on #212.

Test plan

• cargo build --workspace --all-features
• cargo fmt --all -- --check
• cargo test --bin agentflare handoff / mcp_prompts (32/32 pass)

Summary by CodeRabbit

• Documentation
  • Clarified how the handoff action behaves when related work already exists on another existing item, including when to provide an item ID.
  • Added guidance for plain-text status updates: prefer using a status comment plus an item update rather than creating new handoff items.
  • Clarified that omitting an item ID will result in a new item being created.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d9e0e377-ee44-4503-8072-47856f46da9d

📥 Commits

Reviewing files that changed from the base of the PR and between 51f7bd9 and 1a91b30.

📒 Files selected for processing (2)

• src/mcp_prompts.rs
• src/mcp_server.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• src/mcp_server.rs
• src/mcp_prompts.rs

---

📝 Walkthrough

Walkthrough

The MCP /handoff prompt, tool metadata, and HandoffRequest.item_id schema now clarify reuse of existing items and recommend comment plus item for plain-text status updates without versioned artifacts.

Changes

Handoff guidance

Layer / File(s)	Summary
Handoff contract and guidance src/mcp_server/types.rs, src/mcp_server.rs, src/mcp_prompts.rs	Descriptions explain existing-item targeting through item_id, clarify that omission creates a new item, and direct plain-text updates to comment plus item.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• getappz/agentflare#253: Updates the same handoff tool metadata and request schema surfaces.
• getappz/agentflare#172: Reworks handoff item assignment, optional item_id, and versioned asset attachment behavior.
• getappz/agentflare#169: Reworks the handoff item and versioned-asset workflow referenced by these clarifications.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: updating handoff docs to prefer reusing existing items.
Description check	✅ Passed	The description includes a clear summary and test plan, with only the reviewers' notes section omitted.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/handoff-prefer-existing-item

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp_prompts.rs`:
- Around line 217-223: Update the status-update guidance so every item update
includes the required target ID: in src/mcp_prompts.rs lines 217-223, document
item(action=update, id=<id>, assignee_agent=<recipient>), and apply the same id
requirement in the tool description at src/mcp_server.rs lines 412-413.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a81ab6ad-7975-41aa-888c-95d5da44f13b

📥 Commits

Reviewing files that changed from the base of the PR and between d9cdcdd and 51f7bd9.

📒 Files selected for processing (3)

• src/mcp_prompts.rs
• src/mcp_server.rs
• src/mcp_server/types.rs

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Include the required item ID in the status-update guidance.

item(action=update) requires id, not only assignee_agent. Following either description literally leaves the update target missing and fails validation. Document id=<item_id> in both locations.

• src/mcp_prompts.rs#L217-L223: use item(action=update, id=<id>, assignee_agent=<recipient>).
• src/mcp_server.rs#L412-L413: include the same id requirement in the tool description.

📍 Affects 2 files

• src/mcp_prompts.rs#L217-L223 (this comment)
• src/mcp_server.rs#L412-L413

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mcp_prompts.rs` around lines 217 - 223, Update the status-update guidance
so every item update includes the required target ID: in src/mcp_prompts.rs
lines 217-223, document item(action=update, id=<id>,
assignee_agent=<recipient>), and apply the same id requirement in the tool
description at src/mcp_server.rs lines 412-413.