127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
---
|
|
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.
|