# 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/terraphim/terraphim-ai.git

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