agent-orchestration 0.5.0

package/.cursor/rules/orchestrator-auto.mdc

@@ -0,0 +1,107 @@
+---
+description: Auto-registration and coordination for any agent using Agent Orchestration
+alwaysApply: true
+---
+
+# CRITICAL: MULTI-AGENT COORDINATION ACTIVE
+
+This project uses **Agent Orchestration**. You MUST follow these rules.
+
+---
+
+## ⚠️ MANDATORY FIRST ACTION ⚠️
+
+**BEFORE doing ANYTHING else, you MUST run this tool:**
+
+```
+bootstrap
+```
+
+This registers you with the orchestrator and shows you:
+- Current project focus
+- Tasks assigned to you
+- Recent decisions
+
+**DO NOT skip this step. DO NOT start coding before running `bootstrap`.**
+
+---
+
+## If You Were Spawned With a Todo/Task
+
+If you were given a specific task or todo when you started (e.g., via "Build in New Agent"):
+
+**Run this IMMEDIATELY:**
+
+```
+claim_todo:
+  title: "<the todo/task title you were given>"
+```
+
+This will:
+1. Register you as an agent
+2. Create or find the matching task
+3. Claim it so other agents know you're working on it
+
+**Example:** If you were spawned with "Create .env.example for environment variables", run:
+
+```
+claim_todo:
+  title: "Create .env.example for environment variables"
+```
+
+---
+
+## Before Any File Edit
+
+1. Check if the file is locked:
+   ```
+   lock_check:
+     resource: "<file_path>"
+   ```
+
+2. If not locked, acquire a lock:
+   ```
+   lock_acquire:
+     resource: "<file_path>"
+     reason: "<what you're doing>"
+   ```
+
+3. Release when done.
+
+---
+
+## Check Before Major Work
+
+```
+is_my_turn
+```
+
+If "No" - wait or check what tasks are available:
+```
+task_list:
+  status: "pending"
+```
+
+---
+
+## Reference activeContext.md
+
+Check `activeContext.md` for current project state - it's auto-updated.
+
+---
+
+## When Done With Your Task
+
+```
+task_complete:
+  task_id: "<your_task_id>"
+  output: "<summary of what you did>"
+```
+
+---
+
+## On Session End
+
+```
+agent_unregister
+```

package/.cursor/rules/orchestrator-main.mdc

@@ -0,0 +1,86 @@
+---
+description: Rules for the main orchestrator agent in multi-agent workflows
+globs:
+alwaysApply: false
+---
+
+# Main Orchestrator Agent Rules
+
+You are the **main orchestrator agent** in a multi-agent coordination system. Follow these rules to ensure smooth collaboration with sub-agents.
+
+## Automatic Registration
+
+**IMMEDIATELY** when starting any task, register yourself:
+
+```
+agent_register:
+  name: "main-orchestrator"
+  role: "main"
+  capabilities: ["planning", "coordination", "review"]
+```
+
+## Your Responsibilities
+
+1. **Set the Focus** - Always set the current focus so other agents know what we're working on:
+   ```
+   memory_set:
+     key: "current_focus"
+     value: "<description of current goal>"
+     namespace: "context"
+   ```
+
+2. **Create Tasks** - Break down work into discrete tasks for sub-agents:
+   ```
+   task_create:
+     title: "<clear task title>"
+     description: "<detailed requirements>"
+     priority: "normal" | "high" | "urgent"
+     assigned_to: "<agent_id>" (optional)
+   ```
+
+3. **Store Decisions** - Document architectural decisions:
+   ```
+   memory_set:
+     key: "<decision_topic>"
+     value: "<decision and rationale>"
+     namespace: "decisions"
+   ```
+
+4. **Monitor Progress** - Check coordination status regularly:
+   ```
+   coordination_status
+   task_list
+   ```
+
+## Workflow
+
+1. Register yourself first
+2. Check `coordination_status` to see current state
+3. Set `context:current_focus` with the goal
+4. Create tasks for work that needs to be done
+5. Monitor task completion with `task_list`
+6. Store important decisions in `decisions` namespace
+7. Send `agent_heartbeat` periodically with status "busy" or "idle"
+
+## Before Making Decisions
+
+Always check shared memory first:
+```
+memory_list:
+  namespace: "decisions"
+```
+
+This prevents contradicting decisions made by other agents.
+
+## When Delegating
+
+1. Create a clear task with `task_create`
+2. Optionally assign to a specific sub-agent
+3. Wait for task completion before creating dependent tasks
+4. Use task dependencies when order matters
+
+## Communication Pattern
+
+- Use `memory_set` in namespace `context` for current state
+- Use `memory_set` in namespace `blockers` for issues
+- Check `agent_list` to see who's available

package/.cursor/rules/orchestrator-sub.mdc

@@ -0,0 +1,114 @@
+---
+description: Rules for sub-agents spawned to work on specific tasks
+alwaysApply: false
+---
+
+# Sub-Agent Rules
+
+You are a **sub-agent** spawned to work on a specific task. Follow these rules.
+
+---
+
+## ⚠️ CRITICAL FIRST STEP ⚠️
+
+You were spawned to work on a specific task. **IMMEDIATELY** claim it:
+
+```
+claim_todo:
+  title: "<the task you were given>"
+  description: "<details if any>"
+```
+
+**DO NOT start coding until you have claimed your task.**
+
+This:
+1. Registers you with the orchestrator
+2. Creates the task if it doesn't exist
+3. Claims it so no other agent works on it
+4. Returns your agent ID and task ID
+
+---
+
+## After Claiming
+
+1. **Check context** to understand the project:
+   ```
+   memory_get:
+     key: "current_focus"
+     namespace: "context"
+   ```
+
+2. **Check decisions** to avoid contradicting them:
+   ```
+   memory_list:
+     namespace: "decisions"
+   ```
+
+3. **Lock files** before editing:
+   ```
+   lock_acquire:
+     resource: "<file_path>"
+     reason: "<what you're doing>"
+   ```
+
+---
+
+## While Working
+
+Update progress periodically:
+```
+task_update:
+  task_id: "<your_task_id>"
+  progress: 50
+```
+
+Store important findings:
+```
+memory_set:
+  key: "<finding>"
+  value: "<details>"
+  namespace: "findings"
+```
+
+---
+
+## When Done
+
+1. Complete the task:
+   ```
+   task_complete:
+     task_id: "<your_task_id>"
+     output: "<summary of what you did>"
+   ```
+
+2. Release any locks:
+   ```
+   lock_release:
+     resource: "<file_path>"
+   ```
+
+3. Unregister:
+   ```
+   agent_unregister
+   ```
+
+---
+
+## If Blocked
+
+Store the blocker so others know:
+```
+memory_set:
+  key: "blocker_<issue>"
+  value: "<what's blocking you>"
+  namespace: "blockers"
+```
+
+---
+
+## Important Rules
+
+1. **ALWAYS claim your task first** with `claim_todo`
+2. **ALWAYS lock files** before editing shared resources
+3. **ALWAYS complete your task** when done
+4. **Check shared memory** before making decisions that affect others

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aris Setiawan (madebyaris.com)
+
+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/README.md

@@ -0,0 +1,329 @@
+# Agent Orchestration
+
+[![npm version](https://badge.fury.io/js/agent-orchestration.svg)](https://www.npmjs.com/package/agent-orchestration)
+[![GitHub](https://img.shields.io/github/license/madebyaris/agent-orchestration)](https://github.com/madebyaris/agent-orchestration/blob/main/LICENSE)
+
+A Model Context Protocol (MCP) server that enables multiple AI agents to share memory, coordinate tasks, and collaborate effectively across IDEs and CLI tools.
+
+## The Problem
+
+When running multiple AI agents, they face critical coordination challenges:
+
+1. **No Turn Awareness** - Agents don't know if it's their turn to act, leading to race conditions
+2. **File-Based Prediction** - Agents predict state from files, not shared memory, causing stale reads
+3. **Context Drift** - Parallel agents develop inconsistent understanding of the codebase
+4. **No Agent Discovery** - Agents are unaware of other agents working on the same project
+5. **Duplicate Work** - Multiple agents may attempt the same task simultaneously
+6. **Conflicting Edits** - Without coordination, agents overwrite each other's changes
+
+## Solution
+
+This MCP server provides:
+
+- **Shared Memory** - Agents can store and retrieve context, decisions, and findings
+- **Task Queue** - Turn-based task execution with dependencies
+- **Agent Discovery** - Agents can see who else is working on the project
+- **Resource Locking** - Prevent concurrent access to files or resources
+- **Coordination Status** - Real-time visibility into the orchestration state
+- **Auto Context Sync** - Automatically updates `activeContext.md` for easy reference
+
+## Compatibility
+
+Works with any AI coding agent that supports MCP or [AGENTS.md](https://agents.md/):
+
+- **OpenAI Codex**
+- **Google Jules**
+- **Cursor**
+- **Aider**
+- **Windsurf**
+- **VS Code Copilot**
+- **GitHub Copilot Coding Agent**
+- **Devin**
+- And many more!
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm
+
+### Install
+
+```bash
+# Clone or navigate to the project
+cd agent-orchestration
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Quick Start
+
+### For Any IDE/CLI (AGENTS.md)
+
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Initialize with AGENTS.md
+npx agent-orchestration init
+```
+
+This creates `AGENTS.md` with full orchestration instructions that work with any AI coding agent.
+
+### For Cursor IDE
+
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Initialize for Cursor (copies .cursor/rules/)
+npx agent-orchestration init-cursor
+```
+
+This copies `.cursor/rules/` with Cursor-specific rules.
+
+## CLI Commands
+
+```bash
+npx agent-orchestration init           # Create AGENTS.md (works with any AI agent)
+npx agent-orchestration init-cursor    # Setup for Cursor IDE (.cursor/rules/)
+npx agent-orchestration serve          # Run the MCP server
+npx agent-orchestration help           # Show help
+```
+
+## Manual Setup
+
+### 1. Configure Your IDE
+
+Add to your MCP configuration (e.g., `~/.cursor/mcp.json` for Cursor):
+
+```json
+{
+  "mcpServers": {
+    "agent-orchestration": {
+      "command": "npx",
+      "args": ["-y", "agent-orchestration", "serve"],
+      "env": {
+        "MCP_ORCH_SYNC_CONTEXT": "true"
+      }
+    }
+  }
+}
+```
+
+The server automatically uses the current working directory as the project root.
+
+### 2. Start Your Session
+
+Use the `bootstrap` tool to start:
+
+```
+bootstrap
+```
+
+This registers you, shows current focus, pending tasks, and recent decisions.
+
+## Available Tools
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `bootstrap` | **Start here!** Initialize session: register, get focus, tasks, decisions |
+| `claim_todo` | **For sub-agents**: Register + create/claim a task in one call |
+| `agent_whoami` | Get your current agent info (ID, name, role, status) |
+
+### Agent Management
+
+| Tool | Description |
+|------|-------------|
+| `agent_register` | Register this agent with the orchestration system |
+| `agent_heartbeat` | Send a heartbeat to indicate agent is active |
+| `agent_list` | List all registered agents |
+| `agent_unregister` | Unregister this agent (releases all locks) |
+
+### Shared Memory
+
+| Tool | Description |
+|------|-------------|
+| `memory_set` | Store a value in shared memory |
+| `memory_get` | Retrieve a value from shared memory |
+| `memory_list` | List all keys in a namespace |
+| `memory_delete` | Delete a value from shared memory |
+
+### Task Management
+
+| Tool | Description |
+|------|-------------|
+| `task_create` | Create a new task in the queue |
+| `task_claim` | Claim a task to work on |
+| `task_update` | Update task status or progress |
+| `task_complete` | Mark a task as completed |
+| `task_list` | List tasks with filters |
+| `is_my_turn` | Check if work is available for you |
+
+### Coordination
+
+| Tool | Description |
+|------|-------------|
+| `lock_acquire` | Acquire a lock on a resource |
+| `lock_release` | Release a held lock |
+| `lock_check` | Check if a resource is locked |
+| `coordination_status` | Get overall system status |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     IDE / CLI Tool                           │
+├─────────────┬─────────────┬─────────────┬─────────────┬─────┤
+│ Main Agent  │ Sub-Agent 1 │ Sub-Agent 2 │ Sub-Agent 3 │ ... │
+└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴─────┘
+       │             │             │             │
+       └─────────────┴──────┬──────┴─────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │  MCP Server   │
+                    │  (TypeScript) │
+                    └───────┬───────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │             │             │
+      ┌───────▼───┐ ┌───────▼───┐ ┌───────▼───┐
+      │  Agents   │ │   Tasks   │ │  Memory   │
+      │  Registry │ │   Queue   │ │   Store   │
+      └───────────┘ └───────────┘ └───────────┘
+              │             │             │
+              └─────────────┼─────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │    SQLite     │
+                    │  (per-project)│
+                    └───────────────┘
+```
+
+## Recommended Workflow
+
+### Main Orchestrator Agent
+
+```
+1. bootstrap                          # Start session
+2. memory_set current_focus "..."     # Set project focus
+3. task_create "Feature X"            # Create tasks
+4. task_create "Feature Y"
+5. coordination_status                # Monitor progress
+```
+
+### Sub-Agents (Spawned for Specific Work)
+
+```
+1. claim_todo "Feature X"             # Register + claim in one call
+2. lock_acquire "src/feature.ts"      # Lock files before editing
+3. [do the work]
+4. task_complete <task_id> "Done"     # Complete the task
+5. agent_unregister                   # Clean up
+```
+
+## Memory Namespaces
+
+Use these namespaces for organization:
+
+| Namespace | Purpose | Example Keys |
+|-----------|---------|--------------|
+| `context` | Current state and focus | `current_focus`, `current_branch` |
+| `decisions` | Architectural decisions | `auth_strategy`, `db_choice` |
+| `findings` | Analysis results | `perf_issues`, `security_audit` |
+| `blockers` | Issues blocking progress | `api_down`, `missing_deps` |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_ORCH_DB_PATH` | Path to SQLite database | `.agent-orchestration/orchestrator.db` |
+| `MCP_ORCH_SYNC_CONTEXT` | Auto-sync activeContext.md | `false` |
+| `MCP_ORCH_AGENT_NAME` | Default agent name | Auto-generated |
+| `MCP_ORCH_AGENT_ROLE` | Default agent role | `sub` |
+| `MCP_ORCH_CAPABILITIES` | Comma-separated capabilities | `code` |
+
+## AGENTS.md
+
+This project follows the [AGENTS.md](https://agents.md/) format - a simple, open format for guiding AI coding agents used by over 60k open-source projects.
+
+When you run `agent-orchestration init`, it creates an `AGENTS.md` file that works with:
+- OpenAI Codex
+- Google Jules
+- Cursor
+- Aider
+- Windsurf
+- VS Code Copilot
+- And many more!
+
+## Troubleshooting
+
+### Server won't start
+
+1. Make sure Node.js 18+ is installed: `node --version`
+2. Rebuild the project: `npm run build`
+3. Check the path in your MCP config is correct
+
+### Database errors
+
+The SQLite database is created automatically in `.agent-orchestration/`. If corrupted:
+
+```bash
+rm -rf .agent-orchestration/
+```
+
+It will be recreated on next server start.
+
+### Agents not seeing each other
+
+- Ensure all agents are using the same `cwd` in the MCP config
+- Check `agent_list` to see registered agents
+- Stale agents are auto-cleaned after 5 minutes of no heartbeat
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode (rebuild on changes)
+npm run dev
+
+# Clean build
+npm run clean && npm run build
+```
+
+## Roadmap
+
+We're actively developing new features. Here's what's coming:
+
+- [ ] **External Memory Integration** - Integration with external memory providers like [Mem0](https://mem0.ai/), [Byteover](https://www.byterover.dev/), and our own memory solution
+- [ ] **Enhanced Sub-Agent Knowledge** - Fix limitations in knowledge sharing between main agent and sub-agents
+- [ ] **Research-First Workflow** - When building from scratch, agents should research first and prepare all requirements before coding
+- [ ] **Graceful Error Handling** - Better error handling and recovery across all operations
+- [ ] **Auto Documentation** - Automatically generate documentation from and for each sub-agent + main agent interactions
+
+Have a feature request? [Open an issue](https://github.com/madebyaris/agent-orchestration/issues)!
+
+## Author
+
+**Aris Setiawan** - [madebyaris.com](https://madebyaris.com)
+
+- GitHub: [@madebyaris](https://github.com/madebyaris)
+- Repository: [agent-orchestration](https://github.com/madebyaris/agent-orchestration)
+
+## License
+
+MIT

package/activeContext.md

@@ -0,0 +1,37 @@
+# Active Context
+
+_Last updated: Renamed to Agent Orchestration_
+
+## Current Focus
+
+Agent Orchestration - MCP server for multi-agent coordination across IDEs and CLI tools.
+
+## Active Agents
+
+_No active agents. Start the MCP server and register agents to see them here._
+
+## In Progress
+
+_No tasks in progress._
+
+## Pending Tasks
+
+_No pending tasks. Create tasks using the `task_create` tool._
+
+## Recent Decisions
+
+- **name**: Renamed from mcp-orchestrator to agent-orchestration
+- **compatibility**: Added AGENTS.md support for cross-IDE compatibility
+- **runtime**: TypeScript/Node.js for easier installation
+- **database**: better-sqlite3 for synchronous, high-performance SQLite
+
+## Context Notes
+
+- **turn_based_execution**: Agents check `is_my_turn` before starting work
+- **sub_agent_workflow**: Sub-agents use `claim_todo` to register + claim in one call
+- **shared_memory_namespaces**: context, decisions, findings, blockers
+
+---
+
+_This file is auto-generated by the Agent Orchestration server._
+_Edit shared memory to update this context._

package/dist/bin/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI for Agent Orchestration
+ *
+ * Commands:
+ *   init         - Creates AGENTS.md for cross-IDE/CLI compatibility
+ *   init-cursor  - Copies .cursor/rules/ for Cursor IDE
+ *   serve        - Run the MCP server (used by IDEs via npx)
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}