From 2b60ec1acd6e2120433ee9903aef9d0ebe4d4c84 Mon Sep 17 00:00:00 2001
From: shokollm <270575765+shokollm@users.noreply.github.com>
Date: Fri, 27 Mar 2026 11:34:45 +0000
Subject: [PATCH] skill(agent-workflows): add branch hygiene and known pitfalls
 from experience

---
 .hermes/skills/agent-workflows/SKILL.md | 43 +++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/.hermes/skills/agent-workflows/SKILL.md b/.hermes/skills/agent-workflows/SKILL.md
index 03fc678..65c4930 100644
--- a/.hermes/skills/agent-workflows/SKILL.md
+++ b/.hermes/skills/agent-workflows/SKILL.md
@@ -78,12 +78,49 @@ When calling `delegate_task`, include this skill and structure:
 - 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
+# Symlink (skill lives in repo for portability)
 ln -s ~/repositories/kugetsu/.hermes/skills/agent-workflows ~/.hermes/skills/agent-workflows
 
-# Or copy
-cp -r ~/repositories/kugetsu/.hermes/skills/agent-workflows ~/.hermes/skills/
+# 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.