hive-work

Working a hivemind issue (Execution Contract)

Always use the mcp__hive__* tools — never shell out to the hive CLI via Bash. The MCP tools keep the activity log, updated timestamp, and the board's live view in sync; the CLI is for humans. Every tool below works cross-repo: an id whose prefix belongs to another registered workspace resolves automatically.

When you start work on issue $KEY:

1. Load context — call mcp__hive__hive_get_issue({ id: $KEY }). Read the title, description, and acceptanceCriteria array.

2. Claim it (REQUIRED, do this FIRST) — in one move, take ownership:

   • mcp__hive__hive_set_state({ id: $KEY, state: "in_progress" }) (skip only if already in_progress)
   • mcp__hive__hive_update_issue({ id: $KEY, assignee: { type: "agent", id: "claude" } }) so the board shows WHO is on it. Status + assignee are owned by you (the agent) via these calls — the UI does not guess them. This is what makes the canvas/board reflect live agent activity.

3. Branch (if the repo uses feature branches) — isolate your work so parallel agents don't collide: git switch -c $KEY (or reuse an existing branch named for the issue). Skip if the repo works trunk-based or you're already on a suitable branch.

4. Plan — outline the steps to complete each criterion. Post the plan as a comment via mcp__hive__hive_add_comment (one paragraph, no preamble).

5. Execute — do the actual work using Edit / Write / Bash for code changes. After completing each criterion, call mcp__hive__hive_mark_acceptance({ id: $KEY, index: N, done: true }).

6. Verify & commit (REQUIRED before review) — run the repo's tests / typecheck / build (whatever it has) and make them pass. Then commit your work with the issue id in the message: git commit -am "$KEY: <what changed>". Do NOT push unless the user explicitly asked — pushing is a human-authorised action. Committing locally is expected.

7. Report progress — when meaningful work is done, post a comment summarising what you did and pointing at the changes (file:line refs).

8. Final disposition (REQUIRED) — end EVERY work session with one of:

   • mcp__hive__hive_set_state({ id: $KEY, state: "in_review" }) — work complete, awaiting human review
   • mcp__hive__hive_set_state({ id: $KEY, state: "done" }) — only if you have explicit authority
   • mcp__hive__hive_set_state({ id: $KEY, state: "blocked", note: "<why>" }) — cannot proceed; explain
   • mcp__hive__hive_set_state({ id: $KEY, state: "in_progress" }) — still going; will resume next session

Do not exit silently. Failing to call hive_set_state leaves the issue in a stale state and breaks the team's view of what's happening.