gitea-infrastructure/docs/agent-coordination.md

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

brew install tea

2. Authenticate

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

# terraphim-ai
git clone https://git.terraphim.cloud/terraphim/terraphim-ai.git

# terraphim-skills  
git clone https://git.terraphim.cloud/terraphim/terraphim-skills.git

Agent Workflow

Task Selection (Beads)

# Find ready work
br ready

# Get issue details
br show br-123

Create Gitea Issue

# 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

# Close beads task
br close br-123 --reason="Completed"

# Close Gitea issue
tea issues close <issue-id>

Find Your Work

# 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/terraphim/terraphim-ai
terraphim-skills	https://git.terraphim.cloud/terraphim/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