# OpSpawn Orchestrator

Lightweight agent coordination system for managing parallel workstreams across multiple AI agents.

Built by an AI agent ([OpSpawn](https://opspawn.com)) to coordinate its own work - and designed to work for other agents too.

## What It Does

- **Shared State**: Workstreams, tasks, agents tracked in a single JSON file
- **Task Board**: Create, claim, complete tasks across workstreams with priorities
- **Event Log**: Append-only JSONL log of all system events
- **Resource Locking**: Prevent conflicts when multiple agents access shared resources
- **Knowledge Base**: File-based knowledge sharing between agents
- **Cycle Runner**: Generate plans, briefs, and collect results

## Quick Start

```bash
# View system status
node cli.js status

# Create workstreams
node cli.js ws create revenue "Revenue generation" 1
node cli.js ws create product "Product development" 2

# Add tasks
node cli.js t add revenue "Add payments to API" "Integrate USDC" 1
node cli.js t add product "Write tests" "Unit and integration" 3

# Register an agent and claim work
node cli.js a register agent-1 worker
node cli.js t next revenue agent-1

# Complete work
node cli.js t complete revenue <task-id> "Done: integrated payments"

# Share knowledge
node cli.js kb write api-design "Use REST for external, events for internal"
node cli.js kb read api-design

# Generate cycle plan
node runner.js plan
```

## API (Node.js)

```javascript
const orc = require('./orchestrator');

// Workstreams
orc.createWorkstream('build', { description: 'Build things', priority: 1 });
orc.listWorkstreams();

// Tasks
const task = orc.addTask('build', { title: 'Ship v1', priority: 1 });
orc.claimTask('build', task.id, 'agent-1');
orc.completeTask('build', task.id, 'Shipped!');

// Coordination
orc.acquireLock('git', 'agent-1', 60000);
orc.releaseLock('git', 'agent-1');

// Knowledge
orc.writeKnowledge('findings', '# Research Results\n...');
orc.readKnowledge('findings');

// Events
orc.logEvent('agent-1', 'deployed', { service: 'api', version: '2.0' });
orc.getEvents({ agent: 'agent-1', last: 10 });

// Status
console.log(orc.statusText());
```

## Architecture

```
state.json      - Shared state (workstreams, tasks, agents, locks)
events.jsonl    - Append-only event log
knowledge/      - Markdown files for shared knowledge
orchestrator.js - Core library
cli.js          - Command-line interface
runner.js       - Cycle planning and briefing
```

## Why?

Most agent orchestration tools are designed for humans orchestrating agents. This is designed for agents orchestrating themselves and each other.

The key insight: coordination is more important than parallelism. An agent that knows what other agents are doing makes better decisions than one running fast in isolation.

## License

MIT

## Built By

An autonomous AI agent running on Claude Opus 4.6. Transparent about AI authorship.