uclaw-github-ops

Files (1)

• SKILL.md

SKILL.md (first lines)

# uClaw GitHub Operations (Mac-direct)

This skill is the canonical operations playbook for Claude when the user
wants GitHub work executed AT THEIR Mac (not via Cowork sandbox shell).
Distilled from the 2026-05-21 Bundle 25/26/27 PR #394 session, where
multiple sandbox approaches hit walls before the Mac-direct route worked.

## When to use

- User says "你帮我做", "你来操作", "帮我 commit/push/merge/开 PR".
- Multi-step git workflow that mixes commit, push, branch ops, and the
  GitHub REST API.
- Any time the Cowork bash sandbox `mcp__workspace__bash` is hitting
  HEAD.lock / index.lock / "Operation not permitted" errors on `.git/`.

## The hierarchy of execution surfaces

Pick the **highest** surface that satisfies the task. Lower surfaces
have more limitations but cover edge cases.

| Surface | Tool | Strengths | Limits |
|---|---|---|---|
| 1. **Mac shell direct** | `mcp__Macos__Shell` | Real bash on Mac, full git perms, `gh` CLI access, cargo/npm/etc. | Doesn't see Cowork-only state like `/sessions/.../mnt/` paths. |
| 2. **Cowork bash** | `mcp__workspace__bash` | Reads worktree via mount, fast for grep/read | `.git/` writes often fail with `Operation not permitted`; HEAD.lock races with external lock-cleaner daemon. |
| 3. **Computer-use Terminal** | `mcp__computer-use__*` | Visual, last resort | Terminal granted at tier "click" only — Claude can SEE Terminal but cannot type into it. Don't go here. |

**Default to Surface 1 (`mcp__Macos__Shell`) for any git operation that mutates state.**
Use Surface 2 only for read-only inspection (grep, cat, ls) or when
Surface 1 isn't accessible.

## The end-to-end recipe (commit → push → PR → merge)

### Setup (run once per session if unsure)

```bash
# Surface 1
gh auth status              # confirm "Logged in to github.com"
gh repo set-default <owner>/<repo>   # only if gh complains about default
```

If gh isn't logged in, tell the user to run `gh auth login` once
(GitHub.com → HTTPS → web browser); after that all gh commands work.

### Commit one branch's worth of changes

```bash
cd ~/Documents/uclaw-cowork          # or wherever the branch lives
export GIT_PAGER=cat                 # MANDATORY — kills less paginator

# create branch if not on one
git checkout -b prep/<topic>

# stage + commit
git add <specific files>             # NEVER `git add .` — be explicit
git diff --cached --stat              # sanity check what's staged
git commit -F /Users/ryanliu/Documents/uclaw/target/_<bundle>_msg.txt
git show -s --format='%h %s' HEAD    # confirm subject + sha
```

Project convention: **one logical change per commit**, no `git add .`,
no squashing across logical boundaries. See `BEHAVIOR.md` §10.

### Push

```bash
git push -u origin <branch>          # -u sets upstream first time
```

### Open PR

```bash
gh pr create \
  --base main \
  --head <branch> \
  --title "<Title>" \
  --body "$(cat <<'EOF'
<PR body markdown — heredoc with 'EOF' quoted to disable interpolation>
EOF
)"
# OR --body-file /path/to/body.md
```

### Check PR state before merge

```bash
gh pr view <num> --repo <owner>/<repo> \
  --json state,mergeable,reviewDecision,statusCheckRollup,headRefName \
  --jq '. | "state=\(.state) mergeable=\(.mergeable) reviewDecision=\(.reviewDecision // "—") checks=\([.statusCheckRollup[]? | .conclusion] | join(",") )"'
```

Look for `state=OPEN mergeable=MERGEABLE checks=...` — empty checks array
means no CI configured (acceptable for this repo's current setup; would
be a blocker on most teams).

### Merge

```bash
# Match project convention — see existing main history.
# uClaw uses merge commits (NOT squash) per #393, #389, #388 pattern.
gh pr merge <num> --repo <owner>/<repo> --merge --delete-branch
```

`--delete-branch` cleans the head branch on origin AND locally.

### Verify merge succeeded

```bash
gh pr view <num> --repo <owner>/<repo> --json state,mergedAt,mergeCommit --jq '.'
# expect: {"state":"MERGED","mergedAt":"...","mergeCommit":{"oid":"<sha>"}}
```

### Sync local main after merge

```bash
cd ~/Documents/uclaw-cowork
git fetch origin --prune              # picks up deleted refs
git checkout main                     # if your worktree was on the prep branch
git pull --ff-only
git branch -D prep/<topic> 2>/dev/null || true

From novolei/uclaw-pi, Apache-2.0.

More from novolei/uclaw-pi