hive-mind-agent 1.0.0

package/.cursor/mcp.json.example

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "hive-mind": {
+      "command": "node",
+      "args": ["/path/to/hive-mind-agent/mcp-server/index.mjs"],
+      "env": {
+        "HIVE_ROOT": "/path/to/your-hive"
+      }
+    }
+  }
+}

package/.cursor/rules/hive-mind-central-brain.mdc

@@ -0,0 +1,68 @@
+---
+description: Orchestrates multi-agent hive workflows. Project-agnostic; targets from hive.config.json.
+globs: "**/*"
+alwaysApply: false
+---
+
+# Hive-Mind Central Brain
+
+You are the central brain of a hive-mind. You set strategy, assign tasks to workers (subagents), ingest outcomes, and update shared context. Works with any project—targets and paths come from config.
+
+## Config
+
+If `hive.config.json` exists in the hive root, use it:
+- `contextPath` (default `context.md`) — shared state file
+- `outcomesPath` (default `outcomes`) — worker output directory
+- `targetProducts` — products/projects to operate on; include in task context
+- `maxParallelTasks` (default 3) — max parallel subagents per cycle
+
+If no config exists, use `context.md` and `outcomes/` in the hive root.
+
+## Loop
+
+1. **Read** context (from config or `context.md`) — goals, strategy, pending tasks, recent outcomes, learnings
+2. **Decide** 2–3 independent tasks that advance current goals
+3. **Launch** 2–3 `mcp_task` subagents in parallel with clear task descriptions
+4. **Collect** results when subagents complete
+5. **Update** context — add outcome digest to Recent Outcomes, update Learnings, clear completed Pending Tasks
+6. **Decide** next steps: more tasks, done, or human input
+
+## Task Assignment
+
+When invoking `mcp_task`, provide:
+
+- **description** — 3–5 word summary (e.g. "Explore codebase for auth patterns")
+- **prompt** — Full instructions including:
+  - What to do (concrete steps)
+  - Relevant context from context.md (goals, prior outcomes)
+  - Expected outcome (what to return or write)
+- **subagent_type** — One of:
+  - **Base:** `explore` (codebase search), `shell` (commands), `generalPurpose` (research, complex tasks)
+  - **Builder:** `architect`, `implementer`, `reviewer`, `integrator`, `softwareSpecialist`, `firmwareSpecialist`, `hardwareSpecialist` — design, code, review, integrate, web/API/dashboard, embedded/BMS/IoT, PCB/electronics/enclosures
+  - **Operator:** `deployer`, `monitor`, `remediator`, `compliance` — release, observe, fix, assure controls
+  - **Grower:** `researcher`, `optimizer`, `experimenter`, `evangelist`, `launchSpecialist`, `fundraisingSpecialist`, `disruptorSpecialist`, `siteSelectionSpecialist`, `commissioningSpecialist`, `procurementSpecialist`, `permittingSpecialist` — research, optimize, experiment, adoption, GTM/launch, fundraising narrative, category creation, site due diligence, commissioning, procurement, permitting
+
+  Use `generalPurpose` + role in prompt for `launchSpecialist`, `fundraisingSpecialist`, `disruptorSpecialist` (MCP mcp_task has fixed enum).
+
+See `docs/enterprise-agent-taxonomy.md` for full taxonomy and responsibilities.
+
+Launch multiple subagents in one turn when tasks are independent.
+
+## Outcome Ingestion
+
+When subagents complete, read their responses and any files they wrote to `outcomes/`. Update `context.md`:
+
+- Add row to Recent Outcomes (Date, Task, Status, Result)
+- Add learnings to Learnings section if applicable
+- Remove completed tasks from Pending Tasks
+
+## Shared State
+
+- **Context** (path from config or `context.md`) — You read and write this. Single source of truth.
+- **Outcomes** (path from config or `outcomes/`) — Workers write here. You read to ingest.
+
+Workers do not write to context. You aggregate their outcomes and update context.
+
+## Taxonomy
+
+See `docs/enterprise-agent-taxonomy.md` or custom `taxonomyPath` in config. MCP `mcp_task` has fixed enum; use `generalPurpose` + role in prompt for enterprise types.

package/.cursor/settings.json

@@ -0,0 +1,13 @@
+{
+  "plugins": {
+    "vercel": {
+      "enabled": true
+    },
+    "stripe": {
+      "enabled": true
+    },
+    "parallel": {
+      "enabled": true
+    }
+  }
+}

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to Hive-Mind Agent
+
+Thank you for your interest in contributing. This project is open source and welcomes contributions from everyone.
+
+## How to Contribute
+
+### Reporting Issues
+
+- Use GitHub Issues for bugs, feature requests, or questions
+- Search existing issues first to avoid duplicates
+- Include steps to reproduce for bugs
+
+### Pull Requests
+
+1. Fork the repository and create a branch (`git checkout -b feature/your-feature`)
+2. Make your changes
+3. Ensure the project runs: `npm install && node cli.mjs init` (in a temp dir)
+4. Submit a PR with a clear description
+
+### Areas We Need Help
+
+- **Adapters:** Postgres/Redis context store, SQS task queue
+- **LLM providers:** Additional providers (Gemini, Groq, etc.)
+- **Documentation:** Examples, tutorials, non-English docs
+- **Testing:** Unit tests, integration tests
+
+### Code Style
+
+- Use ES modules (`.mjs` or `"type": "module"`)
+- No build step required—keep it runnable with plain Node
+- Prefer minimal dependencies
+
+### License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hive-Mind Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,62 @@
+# Publishing Hive-Mind Agent
+
+Steps to publish as open source.
+
+## 1. Create GitHub Repository
+
+1. Go to [github.com/new](https://github.com/new)
+2. Repository name: `hive-mind-agent`
+3. Description: "Model-agnostic, project-agnostic multi-agent hive orchestration"
+4. Public, add README (or skip if this repo has one)
+5. Create repository
+
+## 2. Push to GitHub
+
+```bash
+cd /path/to/hive-mind-agent
+git add .
+git commit -m "Initial release: hive-mind orchestration for Cursor, CLI, MCP, API"
+git branch -M main
+git remote add origin https://github.com/log-wade/hive-mind-agent.git
+git push -u origin main
+```
+
+Update `package.json` `repository`, `bugs`, and `homepage` URLs if you use a different org.
+
+## 3. Publish to npm
+
+```bash
+# Log in (one-time)
+npm login
+
+# Dry run to verify package contents
+npm pack --dry-run
+
+# Publish
+npm publish
+```
+
+After publish, anyone can run:
+```bash
+npx hive-mind-agent init
+```
+
+## 4. Install Skill (for users)
+
+Users who clone or install the package can install the Cursor skill:
+
+```bash
+cd hive-mind-agent
+npm run skill:install
+```
+
+This copies the skill to `~/.cursor/skills/hive-mind-orchestrator/`.
+
+## 5. Release Tags
+
+For versioned releases:
+```bash
+npm version patch   # or minor, major
+git push && git push --tags
+npm publish
+```

package/README.md

@@ -0,0 +1,98 @@
+# Hive-Mind Agent
+
+**Model-agnostic, project-agnostic, platform-agnostic** multi-agent orchestration. A central brain + subagent hive that works in Cursor, CLI, MCP, or API. Open source (MIT).
+
+## How It Works
+
+- **Central brain** — Sets strategy, assigns tasks, ingests outcomes, updates shared context
+- **Workers** — Subagents (via `mcp_task` in Cursor, or local/HTTP adapters) execute tasks
+- **Shared state** — `context.md` + `outcomes/` (paths configurable via `hive.config.json`)
+
+## Quick Start
+
+### Install
+
+```bash
+# Run without installing (npx)
+npx hive-mind-agent init
+
+# Or clone and use locally
+git clone https://github.com/hive-mind-agent/hive-mind-agent.git
+cd hive-mind-agent && npm install
+```
+
+### Bootstrap a New Hive
+
+```bash
+cd your-project
+npx hive-mind-agent init
+# Edit hive.config.json and context.md
+```
+
+### Cursor
+
+1. Open your project (with `hive.config.json` or `context.md`)
+2. Add the **hive-mind-central-brain** rule (copy from this repo) or **hive-mind-orchestrator** Skill
+3. Say: "Advance the hive" or "Unleash the hive"
+
+### CLI
+
+```bash
+hive init      # Bootstrap (or: npx hive-mind-agent init)
+hive advance   # Inspect context
+```
+
+### MCP Server
+
+Add to Cursor MCP config (see [docs/mcp-server.md](docs/mcp-server.md)):
+
+```json
+{
+  "mcpServers": {
+    "hive-mind": {
+      "command": "node",
+      "args": ["/path/to/hive-mind-agent/mcp-server/index.mjs"],
+      "env": { "HIVE_ROOT": "/path/to/your-hive" }
+    }
+  }
+}
+```
+
+### API Server
+
+```bash
+HIVE_ROOT=/path/to/hive node api-server.mjs
+# Or: npm run api
+# Endpoints: GET/PUT /api/hive/context, GET /api/hive/config, POST /api/hive/cycle
+```
+
+## Structure
+
+```
+hive-mind-agent/
+├── hive.config.json       # Config (targets, adapters, paths)
+├── context.md             # Shared state
+├── outcomes/              # Worker outputs
+├── core/                  # Adapters (context, outcome, LLM)
+├── cli.mjs                # CLI
+├── mcp-server/            # MCP tools
+├── api-server.mjs         # HTTP API
+├── docs/
+└── .cursor/rules/         # Central brain rule
+```
+
+## Docs
+
+- [Config](docs/config.md) — hive.config.json, adapters
+- [MCP Server](docs/mcp-server.md) — Cursor MCP setup
+- [API Server](docs/api-server.md) — HTTP API
+- [Worker Contract](docs/worker-contract.md) — Task/outcome format
+- [Graduation Path](docs/graduation-path.md) — Standalone scaling
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/api-server.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Hive API server. Exposes context and cycle endpoints.
+ * Run: HIVE_ROOT=/path/to/hive node api-server.mjs
+ * Endpoints:
+ *   GET  /api/hive/context  - Read context
+ *   PUT  /api/hive/context  - Update context (body: raw markdown)
+ *   GET  /api/hive/config   - Get config
+ *   GET  /api/hive/outcomes - List outcomes
+ *   POST /api/hive/cycle    - Run one cycle (requires LLM; in Cursor mode returns instructions)
+ */
+
+import { createServer } from 'http';
+import { loadConfig, readContext, writeContext, listOutcomes, createLLMProvider } from './core/index.mjs';
+import { resolve } from 'path';
+
+const HIVE_ROOT = process.env.HIVE_ROOT || process.cwd();
+const PORT = parseInt(process.env.PORT || '3742', 10);
+
+async function getContextPath() {
+  const config = await loadConfig(HIVE_ROOT);
+  return config?.contextPath ?? 'context.md';
+}
+
+async function getOutcomesPath() {
+  const config = await loadConfig(HIVE_ROOT);
+  return config?.outcomesPath ?? 'outcomes';
+}
+
+async function readRawContext() {
+  const { readFile } = await import('fs/promises');
+  const { join } = await import('path');
+  const contextPath = await getContextPath();
+  const path = join(HIVE_ROOT, contextPath);
+  return readFile(path, 'utf-8');
+}
+
+async function writeRawContext(content) {
+  const { writeFile } = await import('fs/promises');
+  const { join } = await import('path');
+  const contextPath = await getContextPath();
+  const path = join(HIVE_ROOT, contextPath);
+  await writeFile(path, content);
+}
+
+async function handleGetContext(res) {
+  try {
+    const content = await readRawContext();
+    res.writeHead(200, { 'Content-Type': 'text/markdown' });
+    res.end(content);
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+async function handlePutContext(req, res) {
+  let body = '';
+  for await (const chunk of req) body += chunk;
+  try {
+    await writeRawContext(body);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+async function handleGetConfig(res) {
+  try {
+    const config = await loadConfig(HIVE_ROOT);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(config || {}));
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+async function handleGetOutcomes(res) {
+  try {
+    const outcomesPath = await getOutcomesPath();
+    const outcomes = await listOutcomes(HIVE_ROOT, outcomesPath);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(outcomes));
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+async function handlePostCycle(res) {
+  const config = await loadConfig(HIVE_ROOT);
+  const llmConfig = config?.adapters?.llm;
+  const llm = createLLMProvider(llmConfig);
+
+  if (llmConfig?.type === 'cursor' || !llmConfig?.type) {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        message:
+          'Cursor mode: run cycle in Cursor. Say "Advance the hive" or "Unleash the hive" to orchestrate.',
+        hint: 'Set adapters.llm.type to anthropic, openai, or ollama for headless cycles.',
+      })
+    );
+    return;
+  }
+
+  try {
+    const contextPath = await getContextPath();
+    const parsed = await readContext(HIVE_ROOT, contextPath);
+    const systemPrompt = `You are the central brain of a hive-mind. Given the context, decide 2-3 independent tasks.
+Return JSON: { "tasks": [ { "description": "...", "prompt": "...", "subagentType": "explore|shell|generalPurpose" } ] }
+Only return valid JSON, no markdown.`;
+    const prompt = `Context:\nGoals: ${JSON.stringify(parsed.goals)}\nStrategy: ${parsed.strategy}\nPending: ${parsed.pendingTasks}\n\nDecide tasks.`;
+    const out = await llm.complete({ prompt, systemPrompt });
+    const json = JSON.parse(out.replace(/```json?\n?|\n?```/g, '').trim());
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        ok: true,
+        tasks: json.tasks || [],
+        message: 'Tasks decided. Worker execution not implemented in API; use Cursor or MCP.',
+      })
+    );
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url || '/', `http://${req.headers.host}`);
+  const path = url.pathname;
+  const method = req.method;
+
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  if (method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (path === '/api/hive/context' && method === 'GET') return handleGetContext(res);
+  if (path === '/api/hive/context' && method === 'PUT') return handlePutContext(req, res);
+  if (path === '/api/hive/config' && method === 'GET') return handleGetConfig(res);
+  if (path === '/api/hive/outcomes' && method === 'GET') return handleGetOutcomes(res);
+  if (path === '/api/hive/cycle' && method === 'POST') return handlePostCycle(res);
+
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Not found' }));
+});
+
+server.listen(PORT, () => {
+  console.log(`Hive API server on http://localhost:${PORT}`);
+  console.log(`HIVE_ROOT: ${HIVE_ROOT}`);
+  console.log('Endpoints: GET/PUT /api/hive/context, GET /api/hive/config, GET /api/hive/outcomes, POST /api/hive/cycle');
+});

package/cli.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Hive CLI. Bootstrap and run hive cycles.
+ * Usage: node cli.mjs init | advance [--cycles N]
+ */
+
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadConfig, readContext, writeContext, listOutcomes } from './core/index.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const CONTEXT_TEMPLATE = `# Hive Context
+
+## Goals
+
+- **Primary:** [Describe the main objective]
+- **Target product:** [Product name and path]
+
+## Strategy
+
+[Current approach]
+
+## Pending Tasks
+
+| ID | Description | Assigned | Status |
+|----|-------------|----------|--------|
+| 1  | [Task]      | -        | pending |
+
+## Recent Outcomes (last 10)
+
+| Date | Task | Status | Result |
+|------|------|--------|--------|
+|      |      |        |        |
+
+## Learnings
+
+-
+`;
+
+const CONFIG_TEMPLATE = {
+  version: 1,
+  targetProducts: [],
+  workspaceRoots: [],
+  adapters: {
+    context: { type: 'file', options: {} },
+    outcome: { type: 'file', options: {} },
+    worker: { type: 'cursor', options: {} },
+    llm: { type: 'cursor', options: {} },
+  },
+  maxParallelTasks: 3,
+  contextPath: 'context.md',
+  outcomesPath: 'outcomes',
+};
+
+async function init(cwd = process.cwd()) {
+  const configPath = join(cwd, 'hive.config.json');
+  const contextPath = join(cwd, 'context.md');
+  const outcomesDir = join(cwd, 'outcomes');
+
+  try {
+    await readFile(configPath);
+    console.log('hive.config.json already exists');
+  } catch {
+    await writeFile(configPath, JSON.stringify(CONFIG_TEMPLATE, null, 2));
+    console.log('Created hive.config.json');
+  }
+
+  try {
+    await readFile(contextPath);
+    console.log('context.md already exists');
+  } catch {
+    await writeFile(contextPath, CONTEXT_TEMPLATE);
+    console.log('Created context.md');
+  }
+
+  await mkdir(outcomesDir, { recursive: true });
+  console.log('Ensured outcomes/ directory');
+
+  console.log('\nHive initialized. Edit hive.config.json and context.md, then run: hive advance');
+}
+
+async function advance(cwd = process.cwd(), cycles = 1) {
+  const config = await loadConfig(cwd);
+  const contextPath = config?.contextPath ?? 'context.md';
+  const outcomesPath = config?.outcomesPath ?? 'outcomes';
+
+  console.log('Hive advance (Cursor mode)');
+  console.log('---');
+  console.log('When running via CLI, the central brain logic runs in Cursor.');
+  console.log('This CLI is for bootstrapping and file inspection.\n');
+
+  const parsed = await readContext(cwd, contextPath);
+  console.log('Context summary:');
+  console.log('  Goals:', parsed.goals?.length ?? 0);
+  console.log('  Strategy:', parsed.strategy ? parsed.strategy.slice(0, 80) + '...' : '(empty)');
+  console.log('  Pending tasks: see context.md');
+
+  const outcomes = await listOutcomes(cwd, outcomesPath);
+  console.log('  Recent outcomes:', outcomes.length);
+
+  console.log('\nTo run a cycle: open this project in Cursor, enable the hive-mind-central-brain rule, and say "Advance the hive" or "Unleash the hive".');
+}
+
+const cmd = process.argv[2] ?? 'help';
+const cycles = parseInt(process.argv.find((a) => a.startsWith('--cycles='))?.split('=')[1] ?? '1', 10);
+const cwd = process.cwd();
+
+if (cmd === 'init') {
+  init(cwd).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+} else if (cmd === 'advance') {
+  advance(cwd, cycles).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+} else {
+  console.log(`
+Hive CLI — Multi-agent orchestration
+
+Usage:
+  node cli.mjs init           Bootstrap hive in current directory
+  node cli.mjs advance        Inspect context (full cycle runs in Cursor)
+
+Or: npm run hive:init | hive:advance
+`);
+}

package/core/adapters/file-context-store.mjs

@@ -0,0 +1,71 @@
+/**
+ * File-based context store. Reads/writes context.md.
+ * @module hive-core/adapters/file-context-store
+ */
+
+import { readFile, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Parse context.md into structured object (simplified; full parse is markdown).
+ * @param {string} content
+ * @returns {{ goals: string[], strategy: string, pendingTasks: string[], recentOutcomes: string[], learnings: string[] }}
+ */
+function parseContext(content) {
+  const sections = {};
+  let current = null;
+  let buffer = [];
+
+  for (const line of content.split('\n')) {
+    if (line.startsWith('## ')) {
+      if (current) sections[current] = buffer.join('\n').trim();
+      current = line.slice(3).trim();
+      buffer = [];
+    } else {
+      buffer.push(line);
+    }
+  }
+  if (current) sections[current] = buffer.join('\n').trim();
+
+  return {
+    raw: content,
+    goals: parseList(sections['Goals'] || sections[' goals'] || ''),
+    strategy: sections['Strategy'] || sections[' strategy'] || '',
+    pendingTasks: sections['Pending Tasks'] || sections[' pending tasks'] || '',
+    recentOutcomes: sections['Recent Outcomes (last 10)'] || sections['Recent Outcomes'] || '',
+    learnings: parseList(sections['Learnings'] || sections[' learnings'] || ''),
+  };
+}
+
+function parseList(text) {
+  return text
+    .split('\n')
+    .map((s) => s.replace(/^[-*]\s*/, '').trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string} rootDir
+ * @param {string} [contextPath='context.md']
+ * @returns {Promise<{ raw: string, goals: string[], strategy: string, pendingTasks: string, recentOutcomes: string, learnings: string[] }>}
+ */
+export async function readContext(rootDir, contextPath = 'context.md') {
+  const path = join(rootDir, contextPath);
+  const content = await readFile(path, 'utf-8');
+  return parseContext(content);
+}
+
+/**
+ * @param {string} rootDir
+ * @param {string} content
+ * @param {string} [contextPath='context.md']
+ */
+export async function writeContext(rootDir, content, contextPath = 'context.md') {
+  const path = join(rootDir, contextPath);
+  await writeFile(path, content);
+}
+
+export { parseContext };