From ef8cc122fda64bd3199e7fe65dc1d2a18c4c6c8d Mon Sep 17 00:00:00 2001
From: Levi Neely <lneely@pascom.net>
Date: Fri, 13 Feb 2026 11:35:26 +0100
Subject: [PATCH] docs: add reproducible workflows section with script examples

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index effde13..35bad8e 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,56 @@ Set `best_effort: true` for graceful degradation on older kernels.
 
 **Warning**: If landrun is missing or kernel lacks Landlock, sessions run **completely unsandboxed**. Only enable if you accept this risk.
 
+## Reproducible Workflows
+
+The 9P filesystem enables scripted multi-agent workflows. Create sessions, set contexts, and wire agents together programmatically.
+
+### Example: Developer-Reviewer
+
+Two agents collaborate on code changes — one implements, one reviews:
+
+```sh
+./scripts/DevReview claude /path/to/project
+```
+
+Creates paired sessions with contexts that instruct agents to:
+1. Developer implements and stages changes
+2. Developer sends review request via `agent/{reviewer-id}/in`
+3. Reviewer examines diff, sends feedback or "LGTM"
+4. Loop until approved
+
+### Example: Planning
+
+Three-agent workflow for documentation tasks:
+
+```sh
+./scripts/Planning kiro /path/to/docs [TICKET-ID]
+```
+
+- **Research**: Queries codebase and knowledge base
+- **Engineering**: Writes/updates documentation, queries research when needed
+- **Tech-editor**: Reviews for quality, requests changes from engineering
+
+### Writing Your Own
+
+Key patterns from the example scripts:
+
+```sh
+# Create session, capture ID
+echo "new claude /project" | 9p write agent/ctl
+ID=$(9p read agent/list | tail -1 | awk '{print $1}')
+
+# Set context (defines agent behavior)
+cat <<EOF | 9p write agent/$ID/context
+You are a code reviewer. When you receive code...
+EOF
+
+# Agents communicate via each other's in files
+echo "Please review staged changes" | 9p write agent/$PEER_ID/in
+```
+
+See `scripts/DevReview` and `scripts/Planning` for complete examples.
+
 ## Troubleshooting
 
 | Problem | Solution |