From 9608d4cb4fae2bff51aeb30b5fbdd48b0fcd011b Mon Sep 17 00:00:00 2001
From: Dr Alexander Mikhalev <alex@metacortex.engineer>
Date: Sat, 21 Feb 2026 19:35:08 +0000
Subject: [PATCH] Add agent coordination documentation for Gitea workflow

---
 docs/agent-coordination.md | 122 +++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/agent-coordination.md

diff --git a/docs/agent-coordination.md b/docs/agent-coordination.md
new file mode 100644
index 0000000..c33804c
--- /dev/null
+++ b/docs/agent-coordination.md
@@ -0,0 +1,122 @@
+# Agent Coordination via Gitea
+
+## Overview
+
+This document describes how AI agents coordinate work using Gitea for repository hosting and Beads for task planning.
+
+## Architecture
+
+| System | Purpose |
+|--------|---------|
+| **Beads** | Task planning, dependencies, priorities |
+| **Gitea** | Git hosting + Agent coordination |
+| **GitHub** | Archived/backup |
+
+## Quick Start
+
+### 1. Install Tea CLI
+
+```bash
+brew install tea
+```
+
+### 2. Authenticate
+
+```bash
+tea login add --name terraphim --url https://git.terraphim.cloud --token YOUR_TOKEN
+```
+
+Get token from: https://git.terraphim.cloud/user/settings/applications
+
+### 3. Clone Repositories
+
+```bash
+# terraphim-ai
+git clone https://git.terraphim.cloud/root/terraphim-ai.git
+
+# terraphim-skills  
+git clone https://git.terraphim.cloud/root/terraphim-skills.git
+```
+
+## Agent Workflow
+
+### Task Selection (Beads)
+
+```bash
+# Find ready work
+br ready
+
+# Get issue details
+br show br-123
+```
+
+### Create Gitea Issue
+
+```bash
+# Create tracking issue for the task
+tea issues create \
+  --title "[br-123] Task Title" \
+  --body "Working on br-123\n\nReservations: None (coordinate via comments)" \
+  --assignee @self \
+  --label "in-progress"
+```
+
+### During Work
+
+- Comment on Gitea issue for progress/blockers
+- Reference in commits: `git commit -m "feat: add feature [br-123]"`
+
+### Complete Task
+
+```bash
+# Close beads task
+br close br-123 --reason="Completed"
+
+# Close Gitea issue
+tea issues close <issue-id>
+```
+
+### Find Your Work
+
+```bash
+# Your assigned issues
+tea issues list --assignee @self --state open
+
+# All in-progress
+tea issues list --label in-progress
+```
+
+## Tea CLI Reference
+
+| Action | Command |
+|--------|---------|
+| List issues | `tea issues list` |
+| Create issue | `tea issues create --title "..." --body "..."` |
+| Close issue | `tea issues close <id>` |
+| List PRs | `tea pulls list --state open` |
+| Create PR | `tea pulls create --title "..." --description "..." --base main --head branch` |
+| Merge PR | `tea pulls merge --style squash <id>` |
+| Open in browser | `tea open` |
+
+## Beads Reference (Unchanged)
+
+| Action | Command |
+|--------|---------|
+| Ready work | `br ready` |
+| Show issue | `br show br-123` |
+| Update status | `br update br-123 --status in_progress` |
+| Close | `br close br-123 --reason "..."` |
+| Sync | `br sync --flush-only` |
+
+## Repositories
+
+| Repository | Gitea URL |
+|------------|-----------|
+| terraphim-ai | https://git.terraphim.cloud/root/terraphim-ai |
+| terraphim-skills | https://git.terraphim.cloud/root/terraphim-skills |
+
+## Notes
+
+- **No file reservations**: Agents coordinate via issue comments instead of automated file locking
+- **Offline support**: Beads works offline; Gitea operations require connectivity
+- **Human visibility**: All agent work visible in Gitea Issues for humans to review