| name | neohive-developer-agent |
| description | Implements Neohive-assigned work as a Coder, Frontend, or specialist agent using MCP tools correctly—register, listen, lock_file, tasks, Node/Volta-safe MCP configs, and dashboard API headers. Use when working in a Neohive-enabled repo, when the user asks to register/listen, or when integrating with .neohive/ and the collaboration server. |
Neohive — Developer / implementer playbook
Session startup
- register with your role name (1–20 chars: letters, digits,
_, -) and skills hints (e.g. frontend, testing) for routing.
- get_briefing() when joining the project or returning after a break.
- Prefer listen() (or listen_group) to receive assignments—do not spin on check_messages() in a loop.
Cursor hooks (Composer)
If the repo has .cursor/hooks.json (install via npx neohive hooks), Cursor injects listen reminders after mutating MCP tools and may block stop until listen() or inbox is clear. This narrows the gap vs Claude Code. followup_message drives the extra turn; loop_limit on the stop hook caps enforced retries. See docs/reference/cursor-neohive-hooks.md for the QA checklist.
While implementing
- Before editing shared files another agent might touch: lock_file with
file_path set to the repo-relative path (e.g. agent-bridge/dashboard.js). unlock_file with the same file_path when finished.
- Tasks are the record: when you start work on an assignment, update_task to in_progress; when finished, update_task to done with notes listing changed paths and how you verified (e.g.
node --check, manual dashboard load).
- If the Coordinator only messaged you but no task exists, ask them to create_task—avoid “silent” work that never hits tasks.json.
MCP and Node binary pitfalls
npx neohive init writes MCP server command as the absolute Node binary that ran init (process.execPath), so Volta/nvm/shimmed installs still work when the IDE MCP subprocess has a minimal PATH.- If MCP fails to start with
node: not found, re-run npx neohive init (or your CLI flag: --claude, --cursor, --codex, --gemini, --all) from the project so configs refresh; for Codex, re-init updates an existing [mcp_servers.neohive] block (does not skip).
- Data directory: defaults to
<project>/.neohive/; overridable with NEOHIVE_DATA_DIR / NEOHIVE_DATA (dashboard and server honor these—see docs/documentation.md).
Dashboard / REST from automation
- Default dashboard
http://localhost:3000; port from NEOHIVE_PORT.
- Every
POST/PUT/DELETE needs X-LTT-Request: 1. LAN access needs .neohive/.lan-token as X-LTT-Token or ?token=.
Quality bar (project norms)
- No emojis in product UI—prefer SVG or text.
- Prefer structured logging over raw
console.log in server code paths that already use the project logger.
- After changes, run the smallest meaningful verification and state results in task notes or send_message to the Coordinator.
Coordinator-facing handoff
When done, message the Coordinator with: task id, summary, paths changed, verification, and screenshots only if UI-related.
Code & Commit Rules
When committing changes, you MUST ALWAYS follow the Conventional Commits format:
<type>(<optional scope>): <description>
Types: feat, fix, refactor, docs, chore, test
Available Neohive MCP Tools
1. Agent Lifecycle & Messaging
register, list_agents, send_message, broadcast, wait_for_reply, listen, listen_group, check_messages, consume_messages, get_notifications, get_history, share_file
2. Autonomy & Workflows (Proactive Engine)
start_plan, get_work, verify_and_advance, retry_with_improvement, create_workflow, advance_workflow, workflow_status
3. Task Management
create_task, update_task, list_tasks
4. Profiles & Workspaces
update_profile, workspace_write, workspace_read, workspace_list
5. Chat Branching & Managed Modes
fork_conversation, switch_branch, list_branches, set_conversation_mode, claim_manager, yield_floor, set_phase
6. Sub-channels
join_channel, leave_channel, list_channels
7. File Safety & Auditing
lock_file, unlock_file, log_violation
8. Shared Knowledge & Decision Tracking
kb_write, kb_read, kb_list, log_decision, get_decisions, get_compressed_history, get_briefing
9. Team Governance (Voting, Reviews, Feedback)
request_review, submit_review, call_vote, cast_vote, vote_status, request_push_approval, ack_push
10. Dependencies & Progress
declare_dependency, check_dependencies, update_progress, get_progress, get_reputation
Related skill
Leads assigning work and driving process should use neohive-coordinator in this same .cursor/skills/ folder.
