---
name: agent-workflows
description: Subagent delegation patterns using Gitea as communication hub — research tasks post findings as issue comments, code tasks push and create PRs.
version: 1.0.0
category: workflows
---

# Agent Workflows with Gitea Communication Hub

## Overview

Subagents work autonomously but communicate through Gitea issues and PRs. This creates an auditable thread of work that the user supervises asynchronously.

## Communication Protocol

- **Research tasks** → findings posted as issue comments
- **Code tasks** → tool pushed, PR created, summary posted as issue comment
- **User feedback** → replies on Gitea trigger next phase of work

## Workflow Types

### Research Task
1. Explore ~/repositories/kugetsu
2. Run `opencode run` for deep research
3. Write findings to `/tmp/findings-{issue}.md`
4. Display with `cat /tmp/findings-{issue}.md`
5. Post as issue comment via curl
6. Ask follow-up questions for user

### Code Task
1. Explore ~/repositories/kugetsu
2. Create tool/script, commit to new branch
3. Push branch, create PR via API
4. Post PR link + summary as issue comment

## Gitea API Reference

Token: `YOUR_GITEA_TOKEN` (replace with your actual token)

### Post Issue Comment
```bash
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/issues/{N}/comments" \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @/tmp/findings-{N}.md
```

### Create Pull Request
```bash
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/pulls" \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"...","body":"...","head":"branch","base":"main"}'
```

## Critical Rules

1. **Use terminal() for curl** — API tools may not be available in subagent context
2. **Write to file first** — then `curl ... -d @/tmp/findings-{N}.md`
3. **Always verify** — `curl ... && echo SUCCESS || echo FAILED`
4. **If curl fails** — output findings so Hermes can post manually
5. **Replace placeholders** — `git.example.com`, `YOUR_GITEA_TOKEN`, `{owner}`, `{repo}`

## Delegation Template

When calling `delegate_task`, include this skill and structure:

```json
{
  "goal": "Work on Issue #{N}: {title}\n\nSteps:\n1. Explore ~/repositories/kugetsu\n2. Run opencode research on {specific question}\n3. Write findings to /tmp/findings-{N}.md\n4. cat /tmp/findings-{N}.md\n5. Post as issue comment via curl\n6. Ask 2-3 follow-up questions\n\nReplace: git.example.com, YOUR_GITEA_TOKEN, {owner}, {repo}, {N}",
  "skills": ["agent-workflows"],
  "toolsets": ["terminal"]
}
```

## Branch Naming

- Research/docs: `docs/issue-{N}-{short-title}`
- Fixes/tools: `fix/issue-{N}-{short-title}`

## Branch Hygiene

**Prevention (critical):** Always create branches from `main` explicitly:
```bash
git checkout -b fix/issue-N-title main   # CORRECT
git checkout -b fix/issue-N-title         # WRONG — uses current HEAD
```

**Detection:** If a branch has unwanted commits from another branch:
```bash
# See commits not in main
git log main..HEAD

# Check which branch a specific commit belongs to
git branch --contains COMMIT_SHA
```

**Fix:** Rebase onto correct base:
```bash
git rebase --onto main wrong-base-branch branch-to-fix
git push --force-with-lease origin branch-to-fix
```

## Known Pitfalls

1. **Subagent API tools unreliable** — curl from `terminal()` is the only reliable method
2. **Large curl bodies blocked** — write to `/tmp/findings-{N}.md` first, then `curl -d @file`
3. **JSON in curl body** — use `python3 -c "import sys,json; print(json.dumps({...}))"` or write to file
4. **Branch contamination** — always specify `main` as base, never rely on current HEAD
5. **git worktree** — use for true isolation per issue (optional):
   ```bash
   git worktree add ../issue-N-workspace main
   ```

## Install

```bash
# Symlink (skill lives in repo for portability)
ln -s ~/repositories/kugetsu/.hermes/skills/agent-workflows ~/.hermes/skills/agent-workflows

# Others: clone repo, then symlink
git clone https://git.example.com/user/repo.git
ln -s repo/.hermes/skills/agent-workflows ~/.hermes/skills/
```

**Note:** This skill is stored in the repo, NOT in `~/.hermes/skills/` directly. This ensures portability — anyone cloning the repo gets the skill automatically.