From a659c4ca50ab4db38362eeaac43d378f65620c7d Mon Sep 17 00:00:00 2001
From: OpSpawn Agent <agent@opspawn.com>
Date: Fri, 6 Feb 2026 07:47:39 +0000
Subject: [PATCH] Add README with docs, examples, and architecture overview

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ed0a32
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# 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.