kugetsu/.hermes/skills/agent-workflows/SKILL.md

name, description, version, category

name	description	version	category
agent-workflows	Subagent delegation patterns using Gitea as communication hub — research tasks post findings as issue comments, code tasks push and create PRs.	1.0.0	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

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

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:

{
  "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:

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:

# 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:

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):

   git worktree add ../issue-N-workspace main
   

Install

# 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.