shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

cleanup: remove unused .hermes/skills/agent-workflows

Browse Source
This commit is contained in:
shokollm
2026-03-31 03:31:07 +00:00
parent cd16ce19c6
commit 1092f73255
1 changed files with 0 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
.hermes/skills/agent-workflows/SKILL.md
View File

@@ -1,265 +0,0 @@
# Improved Subagent Workflow - Error Reduction Guide
## Common Failure Modes & Solutions
### 1. curl API Calls Failing
**Problem:** Security scans block curl requests, tokens get flagged, large payloads timeout.
**Solutions:**
#### a) Use `--max-time` to prevent hangs
```bash
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/issues/{N}/comments" \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
-d @/tmp/findings-{N}.md \
--max-time 30 \
--retry 3 \
--retry-delay 5
```
#### b) Verify response before assuming success
```bash
RESPONSE=$(curl -s -w "%{http_code}" -X POST ... -d @/tmp/findings-{N}.md --max-time 30)
HTTP_CODE="${RESPONSE: -3}"
BODY="${RESPONSE:0:${#RESPONSE}-3}"
if [ "$HTTP_CODE" = "201" ]; then
echo "SUCCESS: Comment posted"
else
echo "FAILED: HTTP $HTTP_CODE"
echo "Response: $BODY"
fi
```
#### c) Avoid security scan triggers
- Don't use `--data-binary` with raw file - it can trigger WAF
- Use `-d @file` with `Content-Type: application/json` properly set
- Keep tokens in headers, not URLs
- Add `User-Agent` to look like a normal request:
```bash
-H "User-Agent: Kugetsu-Subagent/1.0"
```
### 2. File Write Failures
**Problem:** write_file tool fails in subagent context, permissions issues, path confusion.
**Solutions:**
#### a) Always use /tmp for transient findings
```bash
# Use atomic writes with temp file + mv
TEMP_FILE=$(mktemp /tmp/findings-XXXXXX.json)
cat > "$TEMP_FILE" << 'EOF'
{"body": "# Findings\n\ncontent here"}
EOF
mv "$TEMP_FILE" /tmp/findings-{N}.md
```
#### b) Verify file exists and is readable before curl
```bash
if [ -f /tmp/findings-{N}.md ] && [ -r /tmp/findings-{N}.md ]; then
echo "File ready: $(wc -c < /tmp/findings-{N}.md) bytes"
else
echo "ERROR: File not ready"
exit 1
fi
```
#### c) Simple JSON construction
```bash
cat > /tmp/findings-{N}.md << 'EOF'
# Research Findings for Issue #{N}
## Summary
...
EOF
```
### 3. Branch Creation from Wrong Base
**Problem:** `git checkout -b branch` uses current HEAD instead of main, contaminating branch.
**Prevention - Always Explicit:**
```bash
# WRONG - depends on current HEAD
git checkout -b fix/issue-{N}-title
# CORRECT - always from main explicitly
git checkout -b fix/issue-{N}-title main
# SAFER - verify we're on main first
git branch --show-current | grep -q "^main$" || git checkout main
git checkout -b fix/issue-{N}-title main
```
**Detection Script:**
```bash
# Run after branch creation to verify
COMMIT_COUNT=$(git log main..HEAD --oneline | wc -l)
if [ "$COMMIT_COUNT" -gt 0 ]; then
echo "Branch has $COMMIT_COUNT commits beyond main"
echo "First commit: $(git log --oneline -1 HEAD~0)"
echo "Verify with: git log main..HEAD --oneline"
else
echo "Branch is clean (no commits beyond main)"
fi
```
### 4. opencode Command Failures
**Problem:** opencode hangs, times out, or fails silently.
**Solutions:**
#### a) Set explicit timeout and capture output
```bash
timeout 180 opencode run "your research query" 2>&1 | tee /tmp/opencode-output.txt
EXIT_CODE=${PIPESTATUS[0]}
if [ $EXIT_CODE -eq 124 ]; then
echo "TIMEOUT: opencode ran for more than 180 seconds"
elif [ $EXIT_CODE -ne 0 ]; then
echo "ERROR: opencode exited with code $EXIT_CODE"
fi
```
#### b) Use session continuation for complex tasks
```bash
# Start session with title
opencode run "research task" --title "issue-{N}-research"
# Continue in subsequent calls
opencode run "continue analyzing" --continue --session <session-id>
```
#### c) Fallback: Direct terminal commands
If opencode fails repeatedly, use terminal commands for research:
```bash
grep -r "pattern" ~/repositories/kugetsu --include="*.py"
find ~/repositories/kugetsu -name "*.md" -exec grep -l "topic" {} \;
```
### 5. Security Scan Blocks
**Problem:** Gitea instance has security scanning that blocks automated API calls.
**Avoidance Patterns:**
#### a) Add realistic headers
```bash
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/issues/{N}/comments" \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
-H "User-Agent: Kugetsu-Subagent/1.0" \
-H "Accept: application/json" \
-d @/tmp/findings-{N}.md \
--max-time 30
```
#### b) Rate limiting - add delays between calls
```bash
# Sleep before API call to avoid rate limit
sleep 2
curl -X POST ...
```
#### c) Check for CAPTCHA/challenge response
```bash
RESPONSE=$(curl -s --max-time 30 -X POST ...)
if echo "$RESPONSE" | grep -qi "captcha\|challenge\|security"; then
echo "BLOCKED: Security challenge detected"
exit 1
fi
```
## Complete Error-Resistant Workflow
```bash
#!/bin/bash
set -euo pipefail
ISSUE={N}
TOKEN="${GITEA_TOKEN}"
REPO_DIR="~/repositories/kugetsu"
FINDINGS_FILE="/tmp/findings-${ISSUE}.md"
cd "$REPO_DIR"
# 1. Verify clean state
git status --porcelain
# 2. Ensure on main
git checkout main
git pull origin main
# 3. Create branch explicitly from main
git checkout -b "docs/issue-${ISSUE}-research" main
# 4. Run research with timeout
if timeout 180 opencode run "research query" 2>&1; then
echo "Research completed"
else
echo "Research failed or timed out"
exit 1
fi
# 5. Write findings with verification
cat > "$FINDINGS_FILE" << 'EOF'
# Findings for Issue #{N}
Content here
EOF
# Verify file
[ -f "$FINDINGS_FILE" ] && [ -s "$FINDINGS_FILE" ] || { echo "File write failed"; exit 1; }
# 6. Post to Gitea with retry and verification
for i in 1 2 3; do
RESPONSE=$(curl -s -w "\n%{http_code}" \
--max-time 30 \
-X POST "https://git.example.com/api/v1/repos/shoko/kugetsu/issues/${ISSUE}/comments" \
-H "Authorization: token ${TOKEN}" \
-H "Content-Type: application/json" \
-H "User-Agent: Kugetsu-Subagent/1.0" \
-d @"$FINDINGS_FILE")
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')
if [ "$HTTP_CODE" = "201" ]; then
echo "SUCCESS: Posted comment"
break
else
echo "Attempt $i failed: HTTP $HTTP_CODE"
[ $i -lt 3 ] && sleep 5 || { echo "All retries failed"; echo "$BODY"; exit 1; }
fi
done
# 7. Commit and push
git add -A
git commit -m "docs: add findings for issue ${ISSUE}"
git push -u origin "docs/issue-${ISSUE}-research" --force-with-lease
```
## Key Improvements Summary
| Issue | Old Pattern | Improved Pattern |
|-------|-------------|-------------------|
| curl timeout | No timeout | `--max-time 30` |
| curl no retry | Single attempt | `--retry 3 --retry-delay 5` |
| Branch contamination | `git checkout -b branch` | `git checkout -b branch main` |
| File not verified | Assume write worked | `[ -f "$F" ] && [ -s "$F" ]` |
| opencode hang | No timeout | `timeout 180` |
| Security block | Minimal headers | Full headers + User-Agent |
| API failure silent | No error check | HTTP code + body check |
## Proposed Changes to agent-workflows Skill
1. **Add timeout flags to all curl examples** with `--max-time 30 --retry 3`
2. **Add verification steps** after file writes
3. **Add User-Agent header** to avoid security scans
4. **Add response checking pattern** with HTTP code extraction
5. **Add explicit timeout wrapper** for opencode commands
6. **Add branch verification** after creation
7. **Add complete working script** as reference implementation