neohive 6.4.0 → 6.4.2

package/neohive-plugin/README.md

@@ -0,0 +1,55 @@
+# Neohive Plugin for Claude Code
+
+Turn Claude Code into a multi-agent team. Agents communicate, delegate tasks, and build together.
+
+## Skills (Slash Commands)
+
+| Command | Description |
+|---------|-------------|
+| `/neohive:launch-team [template]` | Launch a team from a template (pair, team, review, managed, debate) |
+| `/neohive:status` | Show agent status, active tasks, and workflow progress |
+| `/neohive:send [agent] [message]` | Send a quick message to another agent |
+| `/neohive:plan [description]` | Create a workflow plan from a natural language description |
+
+## Hooks
+
+- **SessionStart** -- Detects Neohive projects and reminds agents to register
+- **PreToolUse** -- Warns when editing files locked by another agent
+- **PostToolUse** -- Tracks MCP tool usage for activity analytics
+
+## Subagents
+
+- **coordinator** -- Project coordinator that plans, delegates, and tracks work (never writes code)
+
+## Installation
+
+### From GitHub (recommended)
+```
+/plugin install neohive
+```
+
+### Manual
+1. Copy the `neohive-plugin/` directory to your Claude Code plugins folder
+2. Restart Claude Code
+
+### Via npm
+```bash
+npx neohive init --plugin
+```
+
+## Gemini CLI
+
+For Gemini CLI, use the instructions and config in `gemini-extension/`:
+```bash
+npx neohive init --gemini
+```
+
+## Requirements
+
+- Claude Code v1.0+
+- Node.js 18+
+- neohive npm package (`npx neohive` must work)
+
+## License
+
+See LICENSE file.

package/neohive-plugin/agents/coordinator.md

@@ -0,0 +1,27 @@
+---
+name: coordinator
+description: A project coordinator subagent that plans work, creates tasks, and delegates to team agents. Use when you need to orchestrate a multi-agent workflow.
+model: sonnet
+effort: high
+maxTurns: 30
+disallowedTools: Edit, Write, Bash
+skills:
+  - neohive:launch-team
+  - neohive:status
+  - neohive:plan
+  - neohive:conventions
+---
+
+You are a project coordinator. Your job is to plan, delegate, and track work — you NEVER write code.
+
+Your tools: `register`, `get_briefing`, `send_message`, `broadcast`, `create_task`, `update_task`, `list_tasks`, `create_workflow`, `advance_workflow`, `workflow_status`, `distribute_prompt`, `start_plan`, `messages`, `kb_write`, `kb_read`, `log_decision`, `get_decisions`, `listen`.
+
+Workflow:
+1. Call `register(name="Coordinator")` then `get_briefing()` to load context
+2. Break the user's request into research tasks and coding tasks
+3. Create tasks with `create_task` and assign to available agents
+4. Use `distribute_prompt` to dispatch task instructions to agents
+5. Call `messages(action="check")` to check for agent updates (non-blocking)
+6. Process reports, advance workflows with `advance_workflow`, assign next tasks
+7. Synthesize results and present to user
+8. **Always call `listen()` as the last tool call of every response**

package/neohive-plugin/gemini-extension/GEMINI.md

@@ -0,0 +1,24 @@
+# Neohive Multi-Agent Collaboration
+
+You are part of a Neohive multi-agent team. Use the neohive MCP tools to communicate with other agents.
+
+## Getting Started
+1. Call `register` with your name to join the team
+2. Call `get_briefing` for project context and active work
+3. Call `listen` to wait for messages from other agents
+
+## Conventions
+- Always call `listen()` after every action -- this is how you receive messages
+- Update task status: `update_task(in_progress)` when starting, `update_task(done)` when finishing
+- Lock files before editing: `lock_file()` before, `unlock_file()` after
+- Report completions to the Coordinator with: what changed, files modified, decisions made
+- Keep messages to 2-3 paragraphs max
+- Use `kb_write()` for findings, `kb_read()` to check team knowledge
+- Never work on another agent's task -- check `list_tasks()` first
+
+## Available Tools
+- **Messaging:** register, send_message, broadcast, listen, messages, handoff
+- **Tasks:** create_task, update_task, list_tasks
+- **Workflows:** create_workflow, advance_workflow, workflow_status
+- **Knowledge:** kb_write, kb_read, kb_list, log_decision
+- **Coordination:** lock_file, unlock_file, update_progress, get_briefing

package/neohive-plugin/gemini-extension/settings-snippet.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "neohive": {
+      "command": "npx",
+      "args": ["-y", "neohive"],
+      "env": {
+        "NEOHIVE_DATA_DIR": ".neohive"
+      },
+      "timeout": 30
+    }
+  }
+}

package/neohive-plugin/hooks/hooks.json

@@ -0,0 +1,87 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/auto-register.sh",
+            "timeout": 10,
+            "statusMessage": "Checking Neohive team status..."
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/before-prompt.sh",
+            "timeout": 5,
+            "statusMessage": "Loading Neohive team context..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/enforce-locks.sh",
+            "timeout": 5,
+            "statusMessage": "Checking file locks..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__neohive__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/track-activity.sh",
+            "async": true,
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__neohive__send_message|mcp__neohive__advance_workflow|mcp__neohive__update_task|mcp__neohive__broadcast|mcp__neohive__add_rule|mcp__neohive__remove_rule|mcp__neohive__toggle_rule",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '\\n📡 NEOHIVE: Call listen() now to receive your next task. Do not stop without calling listen().'",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|mcp__neohive__update_task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.sh",
+            "async": true,
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/enforce-listen.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/neohive-plugin/scripts/auto-register.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# SessionStart hook: check if Neohive is active for this project.
+# Outputs a dynamic context message — no hardcoded agent names.
+
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR}/.neohive"
+
+if [ -d "$NEOHIVE_DIR" ]; then
+  # Count registered agents
+  AGENT_COUNT=0
+  AGENT_NAMES=""
+  if [ -f "$NEOHIVE_DIR/agents.json" ]; then
+    AGENT_COUNT=$(jq 'length' "$NEOHIVE_DIR/agents.json" 2>/dev/null || echo "0")
+    # List alive agent names (dynamic — no hardcoding)
+    AGENT_NAMES=$(jq -r '[to_entries[] | select(.value.alive == true) | .key] | join(", ")' \
+      "$NEOHIVE_DIR/agents.json" 2>/dev/null || echo "")
+  fi
+
+  # Count active workflows
+  WF_COUNT=0
+  if [ -f "$NEOHIVE_DIR/workflows.json" ]; then
+    WF_COUNT=$(jq '[.[] | select(.status == "active")] | length' \
+      "$NEOHIVE_DIR/workflows.json" 2>/dev/null || echo "0")
+  fi
+
+  # Count pending tasks
+  PENDING_TASKS=0
+  if [ -f "$NEOHIVE_DIR/tasks.json" ]; then
+    PENDING_TASKS=$(jq '[.[] | select(.status == "pending" or .status == "in_progress")] | length' \
+      "$NEOHIVE_DIR/tasks.json" 2>/dev/null || echo "0")
+  fi
+
+  # Build the names hint (show only if agents are online)
+  NAMES_HINT=""
+  if [ -n "$AGENT_NAMES" ]; then
+    NAMES_HINT=" Online agents: $AGENT_NAMES."
+  fi
+
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart"
+  },
+  "systemMessage": "Neohive is active ($AGENT_COUNT agents registered, $WF_COUNT active workflows, $PENDING_TASKS pending/in-progress tasks).$NAMES_HINT\n\nTo join: call register() with the name you were assigned, then get_briefing(), then listen(). Do NOT invent a name — the user or Coordinator will tell you which name to use."
+}
+EOF
+fi
+
+exit 0

package/neohive-plugin/scripts/before-prompt.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# UserPromptSubmit hook: inject live neohive team context before every prompt.
+# No hardcoded names — all data read dynamically from .neohive/ files.
+# Exit 0 always (never blocks the prompt).
+
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.neohive"
+
+# Not a neohive project — nothing to inject
+[ -d "$NEOHIVE_DIR" ] || exit 0
+
+# Agents: list alive agents with their roles (dynamic, no hardcoded names)
+AGENTS_ONLINE=""
+if [ -f "$NEOHIVE_DIR/agents.json" ]; then
+  AGENTS_ONLINE=$(jq -r '
+    [to_entries[]
+      | select(.value.alive == true)
+      | "\(.key)(\(.value.role // "agent"))"]
+    | join(", ")
+  ' "$NEOHIVE_DIR/agents.json" 2>/dev/null || echo "")
+fi
+
+# Task counts
+PENDING_COUNT=0
+IN_PROGRESS_COUNT=0
+if [ -f "$NEOHIVE_DIR/tasks.json" ]; then
+  PENDING_COUNT=$(jq '[.[] | select(.status == "pending")] | length' \
+    "$NEOHIVE_DIR/tasks.json" 2>/dev/null || echo "0")
+  IN_PROGRESS_COUNT=$(jq '[.[] | select(.status == "in_progress")] | length' \
+    "$NEOHIVE_DIR/tasks.json" 2>/dev/null || echo "0")
+fi
+
+# Only inject if there is an active team
+[ -z "$AGENTS_ONLINE" ] && exit 0
+
+# Escape for JSON
+AGENTS_ESCAPED=$(printf '%s' "$AGENTS_ONLINE" | sed 's/"/\\"/g')
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit"
+  },
+  "systemMessage": "Neohive team status: $AGENTS_ESCAPED | Tasks: $PENDING_COUNT pending, $IN_PROGRESS_COUNT in-progress. Reminder: call listen() after every action."
+}
+EOF
+
+exit 0

package/neohive-plugin/scripts/enforce-listen.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Stop hook: block agent from stopping if last neohive action wasn't listen()
+# Also auto-reports to coordinator via /api/inject when blocking.
+# Exit 2 = block stop (forces Claude to continue and call listen)
+# Exit 0 = allow stop
+
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.neohive"
+ACTIVITY_FILE="$NEOHIVE_DIR/activity.jsonl"
+SESSION="${CLAUDE_SESSION_ID:-}"
+NEOHIVE_URL="${NEOHIVE_SERVER_URL:-http://localhost:4321}"
+
+# Allow exit: no tool calls this session (user cancelled before any tools ran)
+LOOP_COUNT="${CLAUDE_LOOP_COUNT:-0}"
+[ "$LOOP_COUNT" = "0" ] && exit 0
+
+# Allow exit: user aborted — agent had no chance to call listen()
+STOP_STATUS="${CLAUDE_STOP_HOOK_STATUS:-}"
+[ "$STOP_STATUS" = "aborted" ] && exit 0
+
+# Not a neohive project — allow stop
+[ -f "$ACTIVITY_FILE" ] || exit 0
+
+# Get the last neohive tool used in THIS session
+LAST_TOOL=$(tail -100 "$ACTIVITY_FILE" 2>/dev/null | jq -r --arg session "$SESSION" '
+  select(.session == $session or $session == "") | .tool
+' | grep "^mcp__neohive__" | tail -1)
+
+# No neohive tools used in this session — allow stop
+[ -z "$LAST_TOOL" ] && exit 0
+
+# Look up agent name from the last activity
+AGENT_NAME=$(tail -100 "$ACTIVITY_FILE" 2>/dev/null | jq -r --arg session "$SESSION" '
+  select(.session == $session or $session == "") | .agent
+' | tail -1)
+AGENT="${AGENT_NAME:-unknown}"
+
+# All roles must call listen() — no exemptions
+
+# Last action was listen/register/rules management — allow stop
+case "$LAST_TOOL" in
+  mcp__neohive__listen|\
+  mcp__neohive__register|\
+  mcp__neohive__add_rule|mcp__neohive__remove_rule|mcp__neohive__toggle_rule)
+    exit 0
+    ;;
+esac
+
+# Last neohive action was something other than listen — report + block
+
+# Auto-report to coordinator via neohive /api/inject (HTTP equivalent of send_message)
+# Fire-and-forget: don't fail if dashboard isn't running
+PAYLOAD=$(printf '{"from":"%s","to":"__user__","content":"[STOP HOOK] %s attempted to stop without calling listen(). Last tool: %s. Blocking stop — agent will be prompted to call listen() now.","priority":"normal"}' \
+  "$AGENT" "$AGENT" "$LAST_TOOL")
+curl -s -X POST "${NEOHIVE_URL}/api/inject" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  --max-time 2 \
+  > /dev/null 2>&1 || true
+
+cat <<'EOF'
+
+⚠️  NEOHIVE — REQUIRED ACTION BEFORE STOPPING:
+
+Your last neohive action was not listen(). You MUST call listen() before stopping.
+This keeps you in the receive loop for your next task.
+Your coordinator has been notified via the dashboard.
+
+→ Call: listen()
+
+Do not respond with text. Call listen() now.
+EOF
+exit 2

package/neohive-plugin/scripts/enforce-locks.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# PreToolUse hook: check if the file being edited is locked by another agent
+# Input: JSON via stdin with tool_input.file_path or tool_input.file
+# Exit 0 = allow (with optional context), Exit 2 = block
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.file // empty' 2>/dev/null)
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR}/.neohive"
+LOCKS_FILE="$NEOHIVE_DIR/locks.json"
+
+# No file path or no locks file — allow
+if [ -z "$FILE_PATH" ] || [ ! -f "$LOCKS_FILE" ]; then
+  exit 0
+fi
+
+# Normalize: make path relative to project dir for matching
+REL_PATH="${FILE_PATH#$CLAUDE_PROJECT_DIR/}"
+
+# Check if file is locked (check both absolute and relative paths)
+LOCKED_BY=$(jq -r --arg fp "$FILE_PATH" --arg rp "$REL_PATH" '(.[$fp].agent // .[$rp].agent) // empty' "$LOCKS_FILE" 2>/dev/null)
+
+if [ -n "$LOCKED_BY" ]; then
+  # File is locked — soft enforcement (warn but don't block)
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "additionalContext": "WARNING: File '$REL_PATH' is locked by agent '$LOCKED_BY'. Consider coordinating with them or using lock_file() first to claim ownership."
+  }
+}
+EOF
+fi
+
+exit 0

package/neohive-plugin/scripts/post-tool-use.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# PostToolUse hook — three jobs:
+#   1. send_message → __user__: echo message content as a systemMessage in chat,
+#      and send the last assistant chat turn as report context to the dashboard.
+#   2. File edits: fire-and-forget report to dashboard.
+#   3. Task updates: fire-and-forget report to dashboard.
+#
+# Works with both Claude Code (mcp__neohive__*) and Cursor (MCP:*) tool name formats.
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.neohive"
+NEOHIVE_URL="${NEOHIVE_SERVER_URL:-http://localhost:4321}"
+
+[ -d "$NEOHIVE_DIR" ] || exit 0
+
+# Normalize: strip "MCP:" or "mcp__<server>__" prefix → bare tool name
+BARE=$(echo "$TOOL_NAME" | sed 's/^MCP://; s/^mcp__[^_]*__//')
+
+# Resolve agent name from response or env
+AGENT=$(echo "$INPUT" | jq -r '.tool_response.from // empty' 2>/dev/null)
+[ -z "$AGENT" ] && AGENT="${CLAUDE_AGENT_NAME:-unknown}"
+
+# ── Helper: extract last assistant text turn from the transcript JSONL ────────
+last_chat_text() {
+  local transcript
+  transcript=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  [ -z "$transcript" ] && return
+  [ -f "$transcript" ] || return
+
+  # Use python3 (always available on macOS/Linux) to walk backward through the
+  # JSONL and find the last assistant turn that has a text content block.
+  # role is at the top level; content is inside .message.content or .content.
+  python3 - "$transcript" <<'PYEOF'
+import sys, json
+
+path = sys.argv[1]
+with open(path, 'rb') as f:
+    lines = f.read().splitlines()
+
+for line in reversed(lines):
+    try:
+        obj = json.loads(line)
+    except Exception:
+        continue
+    role = obj.get('role') or (obj.get('message') or {}).get('role', '')
+    if role != 'assistant':
+        continue
+    content = (obj.get('message') or {}).get('content') or obj.get('content') or []
+    if not isinstance(content, list):
+        continue
+    for block in content:
+        if isinstance(block, dict) and block.get('type') == 'text':
+            text = block.get('text', '').strip()
+            if text:
+                # Truncate to 500 chars so the JSON payload stays manageable
+                print(text[:500], end='')
+                sys.exit(0)
+PYEOF
+}
+
+case "$BARE" in
+  # ── send_message to __user__ ────────────────────────────────────────────────
+  send_message)
+    TO=$(echo "$INPUT" | jq -r '.tool_input.to // ""' 2>/dev/null)
+    CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""' 2>/dev/null)
+
+    if [ "$TO" = "__user__" ] && [ -n "$CONTENT" ]; then
+      # Inject into chat as systemMessage
+      CONTENT_ESC=$(echo "$CONTENT" | sed 's/"/\\"/g; s/$/\\n/' | tr -d '\n')
+      printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse"},"systemMessage":"[Neohive → you] %s"}\n' \
+        "$CONTENT_ESC"
+
+      # Also send last chat turn as context to the dashboard
+      LAST_CHAT=$(last_chat_text)
+      if [ -n "$LAST_CHAT" ]; then
+        LAST_ESC=$(printf '%s' "$LAST_CHAT" | sed 's/"/\\"/g')
+        REPORT="[REPORT] ${AGENT} sent message. Last chat turn: ${LAST_ESC}"
+        REPORT_ESC=$(printf '%s' "$REPORT" | sed 's/"/\\"/g')
+        curl -s -X POST "${NEOHIVE_URL}/api/inject" \
+          -H "Content-Type: application/json" \
+          -d "{\"from\":\"${AGENT}\",\"to\":\"__user__\",\"content\":\"${REPORT_ESC}\",\"priority\":\"normal\"}" \
+          --max-time 2 \
+          > /dev/null 2>&1 || true
+      fi
+    fi
+    exit 0
+    ;;
+
+  # ── File edits ───────────────────────────────────────────────────────────────
+  Edit|Write|MultiEdit)
+    FILE=$(echo "$INPUT" | jq -r \
+      '.tool_input.file_path // .tool_input.file // "unknown"' 2>/dev/null)
+    FILE="${FILE#$CLAUDE_PROJECT_DIR/}"
+    MSG="[POST-TOOL] ${AGENT} edited: ${FILE}"
+    ;;
+
+  # ── Task status updates ──────────────────────────────────────────────────────
+  update_task)
+    TASK_ID=$(echo "$INPUT" | jq -r '.tool_input.task_id // "?"' 2>/dev/null)
+    STATUS=$(echo "$INPUT" | jq -r '.tool_input.status // "?"' 2>/dev/null)
+    MSG="[POST-TOOL] ${AGENT} updated task ${TASK_ID} → ${STATUS}"
+    ;;
+
+  *)
+    exit 0
+    ;;
+esac
+
+[ -z "$MSG" ] && exit 0
+
+MSG_ESCAPED=$(printf '%s' "$MSG" | sed 's/"/\\"/g')
+curl -s -X POST "${NEOHIVE_URL}/api/inject" \
+  -H "Content-Type: application/json" \
+  -d "{\"from\":\"${AGENT}\",\"to\":\"__user__\",\"content\":\"${MSG_ESCAPED}\",\"priority\":\"normal\"}" \
+  --max-time 2 \
+  > /dev/null 2>&1 || true
+
+exit 0

package/neohive-plugin/scripts/track-activity.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# PostToolUse hook: log Neohive MCP tool calls for activity analytics
+# Runs async — does not block tool execution
+# Input: JSON via stdin with tool_name, tool_input, tool_response
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
+NEOHIVE_DIR="${CLAUDE_PROJECT_DIR}/.neohive"
+ACTIVITY_FILE="$NEOHIVE_DIR/activity.jsonl"
+
+# Only log if neohive data dir exists
+if [ -d "$NEOHIVE_DIR" ]; then
+  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  INPUT_SIZE=$(echo "$INPUT" | jq -r '.tool_input | tostring | length' 2>/dev/null || echo "0")
+  OUTPUT_SIZE=$(echo "$INPUT" | jq -r '.tool_response | tostring | length' 2>/dev/null || echo "0")
+
+  # Extract agent name from tool response if available
+  AGENT=$(echo "$INPUT" | jq -r '.tool_response.from // .tool_input.name // empty' 2>/dev/null)
+
+  echo "{\"tool\":\"$TOOL_NAME\",\"timestamp\":\"$TIMESTAMP\",\"input_size\":$INPUT_SIZE,\"output_size\":$OUTPUT_SIZE,\"agent\":\"${AGENT:-unknown}\",\"session\":\"${CLAUDE_SESSION_ID:-unknown}\"}" >> "$ACTIVITY_FILE"
+fi
+
+exit 0

package/neohive-plugin/skills/conventions/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: conventions
+description: Neohive multi-agent collaboration conventions. Automatically loaded when working in a multi-agent team to ensure proper tool usage, communication patterns, and workflow management.
+user-invocable: false
+---
+
+## Neohive Collaboration Conventions
+
+When working as part of a Neohive multi-agent team:
+
+1. **Register and get briefing first** — call `register()` then `get_briefing()` before any other action
+2. **Always call `listen()` as the LAST tool call of every response** — no exceptions, all agents
+3. **Handle `retry: true`** — if `listen()` returns `{retry: true}`, call `listen()` again immediately
+4. **Use `listen()` to complete tasks** — pass outcome params instead of a separate update_task call:
+   - `listen(outcome="completed", task_id="...", summary="one line of what was done")`
+   - `listen(outcome="blocked", task_id="...", summary="what is blocking you")`
+5. **Update task to in_progress when starting** — call `update_task(id, status="in_progress")` when you pick up a task
+6. **Lock files before editing** — call `lock_file(path)` before editing, `unlock_file(path)` after
+7. **Report completions via send_message** — after finishing a task send the coordinator: what changed, files modified, decisions made
+8. **Use KB for shared knowledge** — `kb_write()` for findings and decisions, `kb_read()` before starting work to avoid duplication
+9. **Never work on another agent's task** — check `list_tasks()` first
+10. **Keep messages concise** — 2–3 paragraphs max
+
+### listen() outcome loop
+
+```
+register → get_briefing → listen → pick up task → update_task(in_progress)
+→ do work → send_message(coordinator, report) → listen(outcome="completed", task_id, summary)
+                                                                          ↑ always last
+```

package/neohive-plugin/skills/launch-team/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: launch-team
+description: Launch a multi-agent team from a template. Lists available templates and generates prompts for each agent. Use when starting a new multi-agent collaboration, team session, or when the user says "launch team" or "start agents".
+argument-hint: [template-name]
+disable-model-invocation: true
+---
+
+Launch a multi-agent team using Neohive templates.
+
+1. Call `list_agents` to see who's already online
+2. Call `workflow_status` to check if there's an active workflow
+3. If $ARGUMENTS is provided, use it as the template name
+4. If no template specified, list available templates:
+   - **pair** — 2 agents for brainstorming or Q&A
+   - **team** — Coordinator + Researcher + Coder for complex features
+   - **review** — Author + Reviewer for code review pipeline
+   - **managed** — Manager with floor control for structured sessions with large teams
+   - **debate** — Pro vs Con structured debate between two agents
+5. For the chosen template, generate the launch prompt for each agent role
+6. Each prompt must instruct the agent to:
+   - Call `register(name="<AgentName>")` first
+   - Call `get_briefing()` to load context
+   - Call `listen()` to enter the listen loop
+7. Display the prompts and instruct the user to paste each into a separate terminal running `claude` (or the relevant CLI)

package/neohive-plugin/skills/plan/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: plan
+description: Create a multi-agent workflow plan from a natural language description. Breaks down the task into steps, assigns to agents, and creates the workflow. Use when the user describes a feature or task they want the team to build.
+argument-hint: [task description]
+disable-model-invocation: true
+---
+
+Create a workflow plan for the multi-agent team.
+
+1. Call `list_agents` to see available agents and their roles/skills
+2. Call `kb_read` to check for existing decisions or context relevant to this task
+3. Analyze $ARGUMENTS to identify the steps needed
+4. Assign each step to the best-suited agent based on their skills
+5. Call `create_workflow` with the plan:
+   - name: derived from the task description
+   - steps: array of `{description, assignee, depends_on}`
+   - autonomous: true if all agents are online and no human checkpoints needed, false to let Coordinator manage step-by-step
+6. Call `create_task` for each step that can start immediately (no unresolved dependencies)
+7. Call `distribute_prompt` to dispatch task instructions to assigned agents
+8. Call `log_decision` to record the plan breakdown
+9. Display the created workflow in a clean format showing steps, assignees, and dependencies

package/neohive-plugin/skills/send/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: send
+description: Send a message to another agent or broadcast to all agents via Neohive. Use when the user wants to communicate with a specific agent or the whole team.
+argument-hint: [agent-name|all] [message]
+disable-model-invocation: true
+---
+
+Send a message to an agent or the entire team.
+
+1. Parse $ARGUMENTS — first word is agent name (or `all`), rest is the message
+2. If no agent specified, call `list_agents` and ask the user which agent to target
+3. If agent is `all`, call `broadcast(content=<message>)`
+4. Otherwise call `send_message(to=<agent>, content=<message>)`
+5. Call `listen()` after sending to stay in the listen loop

package/neohive-plugin/skills/status/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: status
+description: Show the current status of the Neohive multi-agent team — who's online, active tasks, workflow progress, and recent messages. Use when the user asks about agent status, team progress, or "what's happening".
+---
+
+Check the status of the multi-agent team:
+
+1. Call `list_agents` to see who's online/offline with their roles
+2. Call `list_tasks` to see all tasks and their statuses
+3. Call `workflow_status` to see workflow progress and current step
+4. Call `messages(action="check")` to surface any unread messages
+5. Call `get_decisions` to show recent decisions logged by the team
+6. Summarize in a clean format:
+   - **Agents:** name, status (online/offline), role, current task
+   - **Tasks:** title, assignee, status (`pending` / `in_progress` / `in_review` / `done` / `blocked`)
+   - **Workflows:** name, progress, current step, autonomous or managed
+   - **Recent decisions:** logged rationale from `get_decisions`