hivemind: Instructions file for Claude Code

CLAUDE.md — Hivemind Project Guide

What is this project?

Hivemind is a multi-agent software engineering orchestrator. It takes a user prompt, decomposes it into a DAG of tasks, assigns specialist agents, executes them with dependency awareness, and delivers tested/reviewed code.

Architecture Overview

User message
  → Triage (_triage_is_simple)         # Simple? Skip PM+Architect
  → Architect Agent (architect_agent)  # Codebase review → ArchitectureBrief
  → PM Agent (pm_agent)                # Decompose → TaskGraph (DAG)
  → LangGraph DAG Executor             # select_batch → execute_batch → post_batch → loop
  → Review (read-only critique)        # ACC-Collab pattern + lint/format + test safety net
  → Memory Agent                       # Update project memory with lessons learned

Key Design Decisions

• One DAG per project, always. New messages inject tasks into the live DAG (add or cancel). Never spawn parallel DAGs on the same project. Deferred messages are buffered during PM/Architect phase and drained when the graph is ready.
• Read-only reviewer. The reviewer critiques code but never modifies it. Automated lint/format runs separately. If lint/format breaks tests, changes are reverted to pre-review HEAD.
• Adaptive triage. Simple tasks (short prompt, no complex keywords) skip PM + Architect and go straight to a single fullstack agent. Complex tasks get the full pipeline.
• Writer/Reader separation. Writer agents (modify files) run sequentially under asyncio.Lock. Reader agents (analysis, research) run in parallel.
• Typed contracts. TaskInput → TaskOutput with structured artifacts, not free-form text.

Key Files

File	Purpose
orchestrator.py	Central coordinator — session lifecycle, triage, DAG dispatch, message injection, event emission
dag_executor_langgraph.py	LangGraph StateGraph: select_batch → execute_batch → post_batch → review_code. SQLite checkpointing. Self-healing.
pm_agent.py	PM Agent — decomposes user requests into TaskGraph DAGs. Task count scales with complexity (no forced minimums).
architect_agent.py	Architect Agent — pre-planning codebase review, produces ArchitectureBrief
contracts.py	TaskInput, TaskOutput, TaskGraph, TaskStatus — typed contracts for all agent communication
config.py	All configuration constants (DAG_MAX_CONCURRENT_NODES, agent registry, timeouts, budgets)
src/workers/task_queue.py	ProjectTaskQueue with per-project asyncio.Lock for writer serialization
memory_agent.py	Post-execution memory updates + lessons-learned injection
blackboard.py	Shared state for complexity classification, inter-agent notes
debate_engine.py	Structured debate for critical tasks (currently proactive, planned: reactive on failure)
reflexion.py	Self-reflection on failed tasks before retry
orch_watchdog.py	Agent silence detection (5 stuck signals) + active escalation