docs: update kugetsu-debug skill with delegation coordination findings

docs/SUBAGENT_WORKFLOW.md

@@ -8,7 +8,7 @@ Subagents work autonomously on issues. They research, build, and post progress/f
 
 ### Research Task (e.g., Issue #1)
 1. Subagent explores repo, runs opencode research
-2. Subagent writes findings to `/tmp/findings-{issue}.md`
+2. Subagent writes findings to `${KUGETSU_TEMP_DIR:-/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
@@ -65,7 +65,7 @@ curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/pulls" \
 
 ```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 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",
+  "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:-/tmp}/findings-{N}.md\n4. cat ${KUGETSU_TEMP_DIR:-/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 @${KUGETSU_TEMP_DIR:-/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"]
 }

docs/hermes-communication-patterns.md

@@ -150,8 +150,8 @@ result = delegate_task(
 Steps:
 1. Read existing docs in ~/repositories/kugetsu/docs/
 2. Identify message passing mechanisms used
-3. Write findings to /tmp/findings-4.md
+3. Write findings to ${KUGETSU_TEMP_DIR:-/tmp}/findings-4.md
-4. cat /tmp/findings-4.md
+4. cat ${KUGETSU_TEMP_DIR:-/tmp}/findings-4.md
 5. Post findings as Gitea issue comment
 
 Gitea: git.example.com
@@ -179,7 +179,7 @@ terminal(
 
 ```bash
 # Write findings to temp file first
-cat > /tmp/findings-4.md << 'EOF'
+cat > ${KUGETSU_TEMP_DIR:-/tmp}/findings-4.md << 'EOF'
 # Research Findings for Issue #4
 
 ## Message Passing Mechanisms Identified
@@ -197,7 +197,7 @@ curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/4/comments" \
   -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
   -H "Content-Type: application/json" \
   -H "User-Agent: Kugetsu-Subagent/1.0" \
-  -d @/tmp/findings-4.md \
+  -d @${KUGETSU_TEMP_DIR:-/tmp}/findings-4.md \
   --max-time 30 \
   --retry 3 \
   --retry-delay 5
@@ -211,7 +211,7 @@ curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/3/comments" \
   -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
   -H "Content-Type: application/json" \
   -d '{
-    "body": "## Task Assignment\n\nAgent: coding-agent-1\n\n1. Explore ~/repositories/kugetsu/tools/parallel-capacity-test/\n2. Run the capacity test tool\n3. Document findings in /tmp/findings-3.md\n4. Post findings here\n\nDeadline: Before next PM review cycle"
+    "body": "## Task Assignment\n\nAgent: coding-agent-1\n\n1. Explore ~/repositories/kugetsu/tools/parallel-capacity-test/\n2. Run the capacity test tool\n3. Document findings in ${KUGETSU_TEMP_DIR:-/tmp}/findings-3.md\n4. Post findings here\n\nDeadline: Before next PM review cycle"
   }'
 ```
 
@@ -232,7 +232,7 @@ curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/pulls" \
   -H "Content-Type: application/json" \
   -d '{
     "title": "fix #3: Add parallel capacity test tool",
-    "body": "## Summary\n\nImplements parallel capacity testing for Hermes/OpenCode.\n\n## Testing\n\n- [ ] Tool runs without errors\n- [ ] Output logged to /tmp/capacity-test.log",
+    "body": "## Summary\n\nImplements parallel capacity testing for Hermes/OpenCode.\n\n## Testing\n\n- [ ] Tool runs without errors\n- [ ] Output logged to ${KUGETSU_TEMP_DIR:-/tmp}/capacity-test.log",
     "head": "fix/issue-3-capacity-test",
     "base": "main"
   }'

docs/hermes-setup.md

@@ -319,7 +319,7 @@ git push --force-with-lease origin my-branch
    opencode run "Research/fix issue #{N}"
 
 4. Agent Posts to Gitea
-   curl -X POST .../issues/{N}/comments -d @/tmp/findings-{N}.md
+   curl -X POST .../issues/{N}/comments -d @${KUGETSU_TEMP_DIR:-/tmp}/findings-{N}.md
 
 5. User Reviews on Gitea
    Comments on issues/PRs

docs/kugetsu-setup.md

@@ -261,7 +261,7 @@ For long-running tasks, SSH and spawn:
 
 ```bash
 ssh -p 2222 <username>@<host-ip> \
-  "kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee /tmp/task.log"
+  "kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee ${KUGETSU_TEMP_DIR:-/tmp}/task.log"
 ```
 
 ### Port Forwarding for Web UI

skills/kugetsu/pm/SKILL.md

@@ -83,8 +83,10 @@ When a request comes in:
 **User:** "Update the README with installation instructions"
 **You:** `kugetsu start <domain>/<user>/<repo>#126 Update README with installation instructions`
 
-**User:** "Create a file at /tmp/test.txt"
+**User:** "Create a file at ${KUGETSU_TEMP_DIR:-/tmp}/test.txt"
-**You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at /tmp/test.txt`
+**You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at ${KUGETSU_TEMP_DIR:-/tmp}/test.txt`
+
+NOTE: Always use `${KUGETSU_TEMP_DIR:-/tmp}` for temporary files in task instructions. The PM should instruct dev agents to use this path. By default, use `/home/shoko/.local/share/opencode/tool-output/` which is pre-allowed in opencode permissions.
 
 Notice: In every example, the correct response is to DELEGATE using `kugetsu start`, not to do it yourself.