winter-super-cli 2026.6.26 → 2026.6.28

package/resources/local/hermes-agent-core/skills/github/github-pr-workflow/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: github-pr-workflow
+description: "GitHub PR lifecycle: branch, commit, open, CI, merge."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Pull-Requests, CI/CD, Git, Automation, Merge]
+    related_skills: [github-auth, github-code-review]
+---
+
+# GitHub Pull Request Workflow
+
+Complete guide for managing the PR lifecycle. Each section shows the `gh` way first, then the `git` + `curl` fallback for machines without `gh`.
+
+## Prerequisites
+
+- Authenticated with GitHub (see `github-auth` skill)
+- Inside a git repository with a GitHub remote
+
+### Quick Auth Detection
+
+```bash
+# Determine which method to use throughout this workflow
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  # Ensure we have a token for API calls
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+echo "Using: $AUTH"
+```
+
+### Extracting Owner/Repo from the Git Remote
+
+Many `curl` commands need `owner/repo`. Extract it from the git remote:
+
+```bash
+# Works for both HTTPS and SSH remote URLs
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+echo "Owner: $OWNER, Repo: $REPO"
+```
+
+---
+
+## 1. Branch Creation
+
+This part is pure `git` — identical either way:
+
+```bash
+# Make sure you're up to date
+git fetch origin
+git checkout main && git pull origin main
+
+# Create and switch to a new branch
+git checkout -b feat/add-user-authentication
+```
+
+Branch naming conventions:
+- `feat/description` — new features
+- `fix/description` — bug fixes
+- `refactor/description` — code restructuring
+- `docs/description` — documentation
+- `ci/description` — CI/CD changes
+
+## 2. Making Commits
+
+Use the agent's file tools (`write_file`, `patch`) to make changes, then commit:
+
+```bash
+# Stage specific files
+git add src/auth.py src/models/user.py tests/test_auth.py
+
+# Commit with a conventional commit message
+git commit -m "feat: add JWT-based user authentication
+
+- Add login/register endpoints
+- Add User model with password hashing
+- Add auth middleware for protected routes
+- Add unit tests for auth flow"
+```
+
+Commit message format (Conventional Commits):
+```
+type(scope): short description
+
+Longer explanation if needed. Wrap at 72 characters.
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`, `perf`
+
+## 3. Pushing and Creating a PR
+
+### Push the Branch (same either way)
+
+```bash
+git push -u origin HEAD
+```
+
+### Create the PR
+
+**With gh:**
+
+```bash
+gh pr create \
+  --title "feat: add JWT-based user authentication" \
+  --body "## Summary
+- Adds login and register API endpoints
+- JWT token generation and validation
+
+## Test Plan
+- [ ] Unit tests pass
+
+Closes #42"
+```
+
+Options: `--draft`, `--reviewer user1,user2`, `--label "enhancement"`, `--base develop`
+
+**With git + curl:**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.v3+json" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls \
+  -d "{
+    \"title\": \"feat: add JWT-based user authentication\",
+    \"body\": \"## Summary\nAdds login and register API endpoints.\n\nCloses #42\",
+    \"head\": \"$BRANCH\",
+    \"base\": \"main\"
+  }"
+```
+
+The response JSON includes the PR `number` — save it for later commands.
+
+To create as a draft, add `"draft": true` to the JSON body.
+
+## 4. Monitoring CI Status
+
+### Check CI Status
+
+**With gh:**
+
+```bash
+# One-shot check
+gh pr checks
+
+# Watch until all checks finish (polls every 10s)
+gh pr checks --watch
+```
+
+**With git + curl:**
+
+```bash
+# Get the latest commit SHA on the current branch
+SHA=$(git rev-parse HEAD)
+
+# Query the combined status
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(f\"Overall: {data['state']}\")
+for s in data.get('statuses', []):
+    print(f\"  {s['context']}: {s['state']} - {s.get('description', '')}\")"
+
+# Also check GitHub Actions check runs (separate endpoint)
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/check-runs \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for cr in data.get('check_runs', []):
+    print(f\"  {cr['name']}: {cr['status']} / {cr['conclusion'] or 'pending'}\")"
+```
+
+### Poll Until Complete (git + curl)
+
+```bash
+# Simple polling loop — check every 30 seconds, up to 10 minutes
+SHA=$(git rev-parse HEAD)
+for i in $(seq 1 20); do
+  STATUS=$(curl -s \
+    -H "Authorization: token $GITHUB_TOKEN" \
+    https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+    | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])")
+  echo "Check $i: $STATUS"
+  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failure" ] || [ "$STATUS" = "error" ]; then
+    break
+  fi
+  sleep 30
+done
+```
+
+## 5. Auto-Fixing CI Failures
+
+When CI fails, diagnose and fix. This loop works with either auth method.
+
+### Step 1: Get Failure Details
+
+**With gh:**
+
+```bash
+# List recent workflow runs on this branch
+gh run list --branch $(git branch --show-current) --limit 5
+
+# View failed logs
+gh run view <RUN_ID> --log-failed
+```
+
+**With git + curl:**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+# List workflow runs on this branch
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?branch=$BRANCH&per_page=5" \
+  | python3 -c "
+import sys, json
+runs = json.load(sys.stdin)['workflow_runs']
+for r in runs:
+    print(f\"Run {r['id']}: {r['name']} - {r['conclusion'] or r['status']}\")"
+
+# Get failed job logs (download as zip, extract, read)
+RUN_ID=<run_id>
+curl -s -L \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
+  -o /tmp/ci-logs.zip
+cd /tmp && unzip -o ci-logs.zip -d ci-logs && cat ci-logs/*.txt
+```
+
+### Step 2: Fix and Push
+
+After identifying the issue, use file tools (`patch`, `write_file`) to fix it:
+
+```bash
+git add <fixed_files>
+git commit -m "fix: resolve CI failure in <check_name>"
+git push
+```
+
+### Step 3: Verify
+
+Re-check CI status using the commands from Section 4 above.
+
+### Auto-Fix Loop Pattern
+
+When asked to auto-fix CI, follow this loop:
+
+1. Check CI status → identify failures
+2. Read failure logs → understand the error
+3. Use `read_file` + `patch`/`write_file` → fix the code
+4. `git add . && git commit -m "fix: ..." && git push`
+5. Wait for CI → re-check status
+6. Repeat if still failing (up to 3 attempts, then ask the user)
+
+## 6. Merging
+
+**With gh:**
+
+```bash
+# Squash merge + delete branch (cleanest for feature branches)
+gh pr merge --squash --delete-branch
+
+# Enable auto-merge (merges when all checks pass)
+gh pr merge --auto --squash --delete-branch
+```
+
+**With git + curl:**
+
+```bash
+PR_NUMBER=<number>
+
+# Merge the PR via API (squash)
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge \
+  -d "{
+    \"merge_method\": \"squash\",
+    \"commit_title\": \"feat: add user authentication (#$PR_NUMBER)\"
+  }"
+
+# Delete the remote branch after merge
+BRANCH=$(git branch --show-current)
+git push origin --delete $BRANCH
+
+# Switch back to main locally
+git checkout main && git pull origin main
+git branch -d $BRANCH
+```
+
+Merge methods: `"merge"` (merge commit), `"squash"`, `"rebase"`
+
+### Enable Auto-Merge (curl)
+
+```bash
+# Auto-merge requires the repo to have it enabled in settings.
+# This uses the GraphQL API since REST doesn't support auto-merge.
+PR_NODE_ID=$(curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['node_id'])")
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/graphql \
+  -d "{\"query\": \"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \\\"$PR_NODE_ID\\\", mergeMethod: SQUASH}) { clientMutationId } }\"}"
+```
+
+## 7. Complete Workflow Example
+
+```bash
+# 1. Start from clean main
+git checkout main && git pull origin main
+
+# 2. Branch
+git checkout -b fix/login-redirect-bug
+
+# 3. (Agent makes code changes with file tools)
+
+# 4. Commit
+git add src/auth/login.py tests/test_login.py
+git commit -m "fix: correct redirect URL after login
+
+Preserves the ?next= parameter instead of always redirecting to /dashboard."
+
+# 5. Push
+git push -u origin HEAD
+
+# 6. Create PR (picks gh or curl based on what's available)
+# ... (see Section 3)
+
+# 7. Monitor CI (see Section 4)
+
+# 8. Merge when green (see Section 6)
+```
+
+## Useful PR Commands Reference
+
+| Action | gh | git + curl |
+|--------|-----|-----------|
+| List my PRs | `gh pr list --author @me` | `curl -s -H "Authorization: token $GITHUB_TOKEN" "https://api.github.com/repos/$OWNER/$REPO/pulls?state=open"` |
+| View PR diff | `gh pr diff` | `git diff main...HEAD` (local) or `curl -H "Accept: application/vnd.github.diff" ...` |
+| Add comment | `gh pr comment N --body "..."` | `curl -X POST .../issues/N/comments -d '{"body":"..."}'` |
+| Request review | `gh pr edit N --add-reviewer user` | `curl -X POST .../pulls/N/requested_reviewers -d '{"reviewers":["user"]}'` |
+| Close PR | `gh pr close N` | `curl -X PATCH .../pulls/N -d '{"state":"closed"}'` |
+| Check out someone's PR | `gh pr checkout N` | `git fetch origin pull/N/head:pr-N && git checkout pr-N` |

package/resources/local/hermes-agent-core/skills/github/github-pr-workflow/references/ci-troubleshooting.md

@@ -0,0 +1,183 @@
+# CI Troubleshooting Quick Reference
+
+Common CI failure patterns and how to diagnose them from the logs.
+
+## Reading CI Logs
+
+```bash
+# With gh
+gh run view <RUN_ID> --log-failed
+
+# With curl — download and extract
+curl -sL -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/actions/runs/<RUN_ID>/logs \
+  -o /tmp/ci-logs.zip && unzip -o /tmp/ci-logs.zip -d /tmp/ci-logs
+```
+
+## Common Failure Patterns
+
+### Test Failures
+
+**Signatures in logs:**
+```
+FAILED tests/test_foo.py::test_bar - AssertionError
+E       assert 42 == 43
+ERROR tests/test_foo.py - ModuleNotFoundError
+```
+
+**Diagnosis:**
+1. Find the test file and line number from the traceback
+2. Use `read_file` to read the failing test
+3. Check if it's a logic error in the code or a stale test assertion
+4. Look for `ModuleNotFoundError` — usually a missing dependency in CI
+
+**Common fixes:**
+- Update assertion to match new expected behavior
+- Add missing dependency to requirements.txt / pyproject.toml
+- Fix flaky test (add retry, mock external service, fix race condition)
+
+---
+
+### Lint / Formatting Failures
+
+**Signatures in logs:**
+```
+src/auth.py:45:1: E302 expected 2 blank lines, got 1
+src/models.py:12:80: E501 line too long (95 > 88 characters)
+error: would reformat src/utils.py
+```
+
+**Diagnosis:**
+1. Read the specific file:line numbers mentioned
+2. Check which linter is complaining (flake8, ruff, black, isort, mypy)
+
+**Common fixes:**
+- Run the formatter locally: `black .`, `isort .`, `ruff check --fix .`
+- Fix the specific style violation by editing the file
+- If using `patch`, make sure to match existing indentation style
+
+---
+
+### Type Check Failures (mypy / pyright)
+
+**Signatures in logs:**
+```
+src/api.py:23: error: Argument 1 to "process" has incompatible type "str"; expected "int"
+src/models.py:45: error: Missing return statement
+```
+
+**Diagnosis:**
+1. Read the file at the mentioned line
+2. Check the function signature and what's being passed
+
+**Common fixes:**
+- Add type cast or conversion
+- Fix the function signature
+- Add `# type: ignore` comment as last resort (with explanation)
+
+---
+
+### Build / Compilation Failures
+
+**Signatures in logs:**
+```
+ModuleNotFoundError: No module named 'some_package'
+ERROR: Could not find a version that satisfies the requirement foo==1.2.3
+npm ERR! Could not resolve dependency
+```
+
+**Diagnosis:**
+1. Check requirements.txt / package.json for the missing or incompatible dependency
+2. Compare local vs CI Python/Node version
+
+**Common fixes:**
+- Add missing dependency to requirements file
+- Pin compatible version
+- Update lockfile (`pip freeze`, `npm install`)
+
+---
+
+### Permission / Auth Failures
+
+**Signatures in logs:**
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+Error: Resource not accessible by integration
+403 Forbidden
+```
+
+**Diagnosis:**
+1. Check if the workflow needs special permissions (token scopes)
+2. Check if secrets are configured (missing `GITHUB_TOKEN` or custom secrets)
+
+**Common fixes:**
+- Add `permissions:` block to workflow YAML
+- Verify secrets exist: `gh secret list` or check repo settings
+- For fork PRs: some secrets aren't available by design
+
+---
+
+### Timeout Failures
+
+**Signatures in logs:**
+```
+Error: The operation was canceled.
+The job running on runner ... has exceeded the maximum execution time
+```
+
+**Diagnosis:**
+1. Check which step timed out
+2. Look for infinite loops, hung processes, or slow network calls
+
+**Common fixes:**
+- Add timeout to the specific step: `timeout-minutes: 10`
+- Fix the underlying performance issue
+- Split into parallel jobs
+
+---
+
+### Docker / Container Failures
+
+**Signatures in logs:**
+```
+docker: Error response from daemon
+failed to solve: ... not found
+COPY failed: file not found in build context
+```
+
+**Diagnosis:**
+1. Check Dockerfile for the failing step
+2. Verify the referenced files exist in the repo
+
+**Common fixes:**
+- Fix path in COPY/ADD command
+- Update base image tag
+- Add missing file to `.dockerignore` exclusion or remove from it
+
+---
+
+## Auto-Fix Decision Tree
+
+```
+CI Failed
+├── Test failure
+│   ├── Assertion mismatch → update test or fix logic
+│   └── Import/module error → add dependency
+├── Lint failure → run formatter, fix style
+├── Type error → fix types
+├── Build failure
+│   ├── Missing dep → add to requirements
+│   └── Version conflict → update pins
+├── Permission error → update workflow permissions (needs user)
+└── Timeout → investigate perf (may need user input)
+```
+
+## Re-running After Fix
+
+```bash
+git add <fixed_files> && git commit -m "fix: resolve CI failure" && git push
+
+# Then monitor
+gh pr checks --watch 2>/dev/null || \
+  echo "Poll with: curl -s -H 'Authorization: token ...' https://api.github.com/repos/.../commits/$(git rev-parse HEAD)/status"
+```

package/resources/local/hermes-agent-core/skills/github/github-pr-workflow/references/conventional-commits.md

@@ -0,0 +1,71 @@
+# Conventional Commits Quick Reference
+
+Format: `type(scope): description`
+
+## Types
+
+| Type | When to use | Example |
+|------|------------|---------|
+| `feat` | New feature or capability | `feat(auth): add OAuth2 login flow` |
+| `fix` | Bug fix | `fix(api): handle null response from /users endpoint` |
+| `refactor` | Code restructuring, no behavior change | `refactor(db): extract query builder into separate module` |
+| `docs` | Documentation only | `docs: update API usage examples in README` |
+| `test` | Adding or updating tests | `test(auth): add integration tests for token refresh` |
+| `ci` | CI/CD configuration | `ci: add Python 3.12 to test matrix` |
+| `chore` | Maintenance, dependencies, tooling | `chore: upgrade pytest to 8.x` |
+| `perf` | Performance improvement | `perf(search): add index on users.email column` |
+| `style` | Formatting, whitespace, semicolons | `style: run black formatter on src/` |
+| `build` | Build system or external deps | `build: switch from setuptools to hatch` |
+| `revert` | Reverts a previous commit | `revert: revert "feat(auth): add OAuth2 login flow"` |
+
+## Scope (optional)
+
+Short identifier for the area of the codebase: `auth`, `api`, `db`, `ui`, `cli`, etc.
+
+## Breaking Changes
+
+Add `!` after type or `BREAKING CHANGE:` in footer:
+
+```
+feat(api)!: change authentication to use bearer tokens
+
+BREAKING CHANGE: API endpoints now require Bearer token instead of API key header.
+Migration guide: https://docs.example.com/migrate-auth
+```
+
+## Multi-line Body
+
+Wrap at 72 characters. Use bullet points for multiple changes:
+
+```
+feat(auth): add JWT-based user authentication
+
+- Add login/register endpoints with input validation
+- Add User model with argon2 password hashing
+- Add auth middleware for protected routes
+- Add token refresh endpoint with rotation
+
+Closes #42
+```
+
+## Linking Issues
+
+In the commit body or footer:
+
+```
+Closes #42          ← closes the issue when merged
+Fixes #42           ← same effect
+Refs #42            ← references without closing
+Co-authored-by: Name <email>
+```
+
+## Quick Decision Guide
+
+- Added something new? → `feat`
+- Something was broken and you fixed it? → `fix`
+- Changed how code is organized but not what it does? → `refactor`
+- Only touched tests? → `test`
+- Only touched docs? → `docs`
+- Updated CI/CD pipelines? → `ci`
+- Updated dependencies or tooling? → `chore`
+- Made something faster? → `perf`

package/resources/local/hermes-agent-core/skills/github/github-pr-workflow/templates/pr-body-bugfix.md

@@ -0,0 +1,35 @@
+## Bug Description
+
+<!-- What was happening? -->
+
+Fixes #
+
+## Root Cause
+
+<!-- What was causing the bug? -->
+
+## Fix
+
+<!-- What does this PR change to fix it? -->
+
+-
+
+## How to Verify
+
+<!-- Steps a reviewer can follow to confirm the fix -->
+
+1.
+2.
+3.
+
+## Test Plan
+
+- [ ] Added regression test for this bug
+- [ ] Existing tests still pass
+- [ ] Manual verification of the fix
+
+## Risk Assessment
+
+<!-- Could this fix break anything else? What's the blast radius? -->
+
+Low / Medium / High — <!-- explanation -->

package/resources/local/hermes-agent-core/skills/github/github-pr-workflow/templates/pr-body-feature.md

@@ -0,0 +1,33 @@
+## Summary
+
+<!-- 1-3 bullet points describing what this PR does -->
+
+-
+
+## Motivation
+
+<!-- Why is this change needed? Link to issue if applicable -->
+
+Closes #
+
+## Changes
+
+<!-- Detailed list of changes made -->
+
+-
+
+## Test Plan
+
+<!-- How was this tested? Checklist of verification steps -->
+
+- [ ] Unit tests pass (`pytest`)
+- [ ] Manual testing of new functionality
+- [ ] No regressions in existing behavior
+
+## Screenshots / Examples
+
+<!-- If UI changes or new output, show before/after -->
+
+## Notes for Reviewers
+
+<!-- Anything reviewers should pay special attention to -->