kugetsu/docs/SUBAGENT_WORKFLOW.md

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

curl -X POST "https://git.example.com/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

curl -X POST "https://git.example.com/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

curl -X POST "https://git.example.com/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.example.com
• Owner: shoko
• Repository: kugetsu
• Token: stored as GITEA_TOKEN in delegation context
• Repo Path: ~/repositories/kugetsu

Subagent Delegation Template

{
  "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.example.com/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: abcdefg012345\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}

Branch Hygiene

When branches are created incorrectly (e.g., from HEAD instead of main), they become contaminated with unwanted commits. This section provides a standard workflow for detecting and fixing this.

How Contamination Happens

• Running git checkout -b new-branch (without explicit base) creates a branch from the current HEAD
• If HEAD is not aligned with main (e.g., detached HEAD, or a different branch), the new branch inherits that history
• The branch then contains commits that don't belong to the intended base

Detection

Symptom: git log shows commits from a different/wrong branch at the start of the history.

Command to identify contamination:

# Find commits that exist in wrong-branch but not in main
git log main..wrong-branch --oneline

# Check if a specific commit is contained in main
git branch --contains <commit-id>
# If empty output, the commit is NOT in main (contamination)

# Or compare the first commit of your branch to main's tip
git merge-base main your-branch
# If this doesn't match the first commit on your branch, there's contamination

Prevention

Always use explicit base when creating branches:

# Correct - branch from main explicitly
git checkout -b new-branch main

# Incorrect - branch from current HEAD (may not be main)
git checkout -b new-branch  # DANGEROUS if HEAD isn't main

Fix Procedure

If contamination is detected, use git rebase --onto to move the branch to the correct base:

# Syntax: git rebase --onto <new-base> <old-base> <branch-to-move>
git rebase --onto main wrong-branch new-branch

# Example:
# - main is the correct base
# - wrong-branch is the contaminated branch (the old base that was used incorrectly)
# - new-branch is your current branch that has wrong commits

# After rebase, verify with:
git log --oneline main..
git branch --contains <original-first-commit-id>  # Should be empty

Force Push with Lease

After rebasing, a force push is required. Use --force-with-lease for safety:

git push --force-with-lease origin new-branch

--force-with-lease is safer than --force because it will fail if someone else has pushed to the branch since you last fetched, preventing accidental overwrites.

Quick Reference

Scenario	Command
Create clean branch	git checkout -b new-branch main
Detect contamination	git log main..my-branch (if non-empty, contaminated)
Check commit presence	git branch --contains <commit-id>
Fix contaminated branch	git rebase --onto main wrong-base my-branch
Safe force push	git push --force-with-lease origin my-branch