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 `${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{issue}.md`
   - Note: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp access in headless mode
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.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  
```bash
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
```bash
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

```json
{
  "goal": "Work on Issue #{N}: {title}\n\nSteps:\n1. Explore ~/repositories/kugetsu\n2. Run opencode research on {specific question}\n3. Write findings to ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{N}.md\n4. cat the findings file 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 @${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{N}.md\n6. Ask 2-3 clarifying questions at end for user\n\nToken: abcdefg012345\nRepo: ~/repositories/kugetsu\n\nNote: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp access in headless mode",
  "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:**
```bash
# 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:**
```bash
# 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:

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

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