Merge pull request #5 from lneely/conductor

Add automation documentation

EVENTS.md

@@ -0,0 +1,55 @@
+# Events System
+
+The events system provides a real-time text stream of all AnviLLM activity.
+
+## Reading Events
+
+```sh
+9p read agent/events
+```
+
+This blocks and streams JSON events as they occur, one per line.
+
+## Event Format
+
+Each line is a JSON object:
+
+```json
+{"id":"uuid","ts":1708598520,"agent":"a1b2c3d4","type":"StateChange","data":{"state":"running"}}
+{"id":"uuid","ts":1708598525,"agent":"a1b2c3d4","type":"UserRecv","data":{"from":"user","subject":"Review request"}}
+```
+
+## Event Types
+
+- `StateChange` - Session state transitions (starting, idle, running, stopped, error, exited)
+- `UserRecv` - Message received by user
+- `UserSend` - Message sent by user
+- `BotRecv` - Message received by bot
+- `BotSend` - Message sent by bot
+
+## Consuming Events
+
+Pipe to any tool:
+
+```sh
+# Log to file
+9p read agent/events >> anvillm.log
+
+# Filter specific events
+9p read agent/events | grep StateChange
+
+# Parse with jq
+9p read agent/events | jq 'select(.type == "UserRecv")'
+
+# Custom notification script
+9p read agent/events | while read event; do
+  echo "$event" | jq -r '"\(.type): \(.agent)"'
+done
+
+# Desktop notifications on state changes
+9p read agent/events | jq -r 'select(.type == "StateChange") | "\(.agent): \(.data.state)"' | \
+  while read msg; do notify-send "AnviLLM" "$msg"; done
+```
+
+It's just a text stream — wire it however you want.
+

README.md

@@ -260,6 +260,41 @@ echo 'new "Task"' | 9p write agent/beads/ctl
 
 See `bot-templates/`, `kiro-cli/SKILLS_PROMPT.md`
 
+## Automating Development
+
+Automate development workflows with Taskmaster and Conductor bots. Input a project plan → Taskmaster creates tasks with dependencies → Conductor orchestrates parallel execution.
+
+### Usage
+
+Examples below use raw 9P calls. These actions can also be performed from any front-end (Assist, TUI, Emacs, Web).
+
+**1. Taskmaster: Create tasks from project plan**
+
+```sh
+./bot-templates/Taskmaster kiro /path/to/project
+TASKMASTER_ID=$(9p read agent/list | head -1 | awk '{print $1}')
+
+# Send project plan
+echo '{"to":"'$TASKMASTER_ID'","type":"PROMPT_REQUEST","subject":"Create tasks","body":"<your project plan>"}' | 9p write user/mail
+
+# Get top-level bead ID
+BEAD_ID=$(9p read agent/beads/list | jq -r '.[0].id')
+```
+
+**2. Conductor: Execute work**
+
+```sh
+./bot-templates/Conductor kiro /path/to/project
+CONDUCTOR_ID=$(9p read agent/list | head -1 | awk '{print $1}')
+
+# Send work request
+echo '{"to":"'$CONDUCTOR_ID'","type":"WORK_REQUEST","subject":"Execute","body":"Complete bead '$BEAD_ID'"}' | 9p write user/mail
+```
+
+Conductor analyzes dependencies, spawns specialized bots (DevReview, Research, Docs), and delegates work in parallel.
+
+**Monitoring:** Use any front-end (Assist, TUI, Emacs, Web). For custom integrations, see `EVENTS.md`.
+
 ## MCP Integration
 
 `anvilmcp` exposes AnviLLM via Model Context Protocol for Claude Desktop, Cline, etc