# Subagent Workflow: Gitea as Communication Hub

## Concept

Subagents work autonomously on issues. They research, build, and post progress/findings as Gitea comments. The user supervises asynchronously via issue threads and PR reviews. This creates a permanent, auditable record of all agent work.

## Workflow Types

### Research Task (e.g., Issue #1)
1. Subagent explores repo, runs opencode research
2. Subagent writes findings to `/tmp/findings-{issue}.md`
3. Subagent posts findings as issue comment via curl
4. User replies with feedback/questions on Gitea
5. Subagent (or Hermes) reads reply, continues research
6. Repeat until scope is complete

### Code Task (e.g., Issue #3)
1. Subagent explores repo, understands requirements
2. Subagent creates tool/script, commits to new branch
3. Subagent pushes branch, creates PR via API
4. Subagent posts PR link + summary as issue comment
5. User reviews PR, leaves comments
6. Subagent addresses feedback, pushes to same PR

## API Endpoints

### Post Issue Comment
```bash
curl -X POST "https://git.fbrns.co/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments" \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"body": "Markdown content here"}'
```

### Post PR Comment  
```bash
curl -X POST "https://git.fbrns.co/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/comments" \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"body": "Markdown content here"}'
```

### Create Pull Request
```bash
curl -X POST "https://git.fbrns.co/api/v1/repos/{owner}/{repo}/pulls" \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PR Title",
    "body": "PR Description",
    "head": "branch-name",
    "base": "main"
  }'
```

## Constants

- Gitea Instance: `git.fbrns.co`
- Owner: `shoko`
- Repository: `kugetsu`
- Token: stored as `GITEA_TOKEN` in delegation context
- Repo Path: `~/repositories/kugetsu`

## Subagent Delegation Template

```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 to display\n5. Post as issue comment via:\n   curl -X POST 'https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/{N}/comments' \\\n     -H 'Authorization: token ${GITEA_TOKEN}' \\\n     -H 'Content-Type: application/json' \\\n     -d @/tmp/findings-{N}.md\n6. Ask 2-3 clarifying questions at end for user\n\nToken: 4c85c4c92637b33230a1f550287e63a0d1cef7a0\nRepo: ~/repositories/kugetsu",
  "context": "{additional context}",
  "toolsets": ["terminal"]
}
```

## Important Notes

- Always use `terminal()` for curl commands — API tools may not be available
- Always verify curl response with `&& echo SUCCESS` 
- If curl fails, still output findings so Hermes can post manually
- Write findings to file first, then curl with `@filename` to avoid JSON escaping issues

## Issue State Machine

```
OPEN → IN_PROGRESS (subagent claims it)
  → AWAITING_FEEDBACK (subagent posted, waiting for user)
  → IN_PROGRESS (user replied, subagent continues)
  → COMPLETED (user confirmed done, subagent closes)
```

## Branch Naming

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