---
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}`

## Install

```bash
# Symlink
ln -s ~/repositories/kugetsu/.hermes/skills/agent-workflows ~/.hermes/skills/agent-workflows

# Or copy
cp -r ~/repositories/kugetsu/.hermes/skills/agent-workflows ~/.hermes/skills/
```