|
| 1 | +# Agentic Skill: Git & GitHub CLI (`gh`) Operations |
| 2 | + |
| 3 | +## Core Philosophy for Autonomous Execution |
| 4 | +When operating Git and the GitHub CLI (`gh`), you are interacting with persistent, shared state. You must adhere to these strict rules to prevent lockups, infinite loops, and merge conflicts: |
| 5 | +1. **Never Assume a Clean Slate**: Always assume previous runs may have crashed. Use hard resets before checking out branches. |
| 6 | +2. **Never Use Interactive Commands**: Commands must execute entirely via standard input/output. Never allow Git to open a text editor (e.g., always use `git commit -m`). |
| 7 | +3. **The "Last Word" Protocol**: Always use your own GitHub comments as state checkpoints to prevent repeating the same work. |
| 8 | +4. **Parallel Safety via Worktrees**: Never modify files in the base repository clone. Always use `git worktree` to isolate parallel tasks. |
| 9 | + |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +**Note**: `$HOME` is the environment variable for the user's home directory (e.g., `/root`, `/home/username`). `<code_base_dir>` represents `$HOME/repositories`, which is the workspace root where repositories and worktrees are stored. |
| 14 | + |
| 15 | +## 1. Architectural Setup: Base Repositories vs. Worktrees |
| 16 | +To support concurrent agent tasks without locking errors, you must separate the Git database from the working files. |
| 17 | + |
| 18 | +* **Base Repository** (`$HOME/<repo_name>`): Used *only* to hold the `.git` database. You never write code here. |
| 19 | +* **Isolated Worktrees** (<code_base_dir>/worktrees/<repo_name>/<branch_name>`): Dedicated directories for specific PRs or features. |
| 20 | + |
| 21 | +### Creating and Managing Worktrees |
| 22 | +```bash |
| 23 | +# 1. Always fetch the latest remote state first from inside the Base Repo |
| 24 | +cd <code_base_dir>/<repo_name> |
| 25 | +git fetch origin <branch_name> |
| 26 | + |
| 27 | +# 2. Create a new branch and worktree simultaneously |
| 28 | +git worktree add -b <new_branch> <code_base_dir>/worktrees/<repo_name>/<new_branch> origin/main |
| 29 | + |
| 30 | +# 3. Create a worktree for an existing branch |
| 31 | +git worktree add <code_base_dir>/worktrees/<repo_name>/<existing_branch> <existing_branch> |
| 32 | + |
| 33 | +# 4. Clean up a worktree when the PR is merged/closed |
| 34 | +git worktree remove <code_base_dir>/worktrees/<repo_name>/<branch_name> --force |
| 35 | +``` |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## 2. Idempotent State Recovery (The "Clean Slate" Sync) |
| 40 | +If you are waking up or resuming a session, the worktree might be in a dirty or conflicted state. You must force it back to a clean state matching the remote branch before writing new code. |
| 41 | + |
| 42 | +```bash |
| 43 | +cd <code_base_dir>/worktrees/<repo_name>/<branch_name> |
| 44 | + |
| 45 | +# Nuke any uncommitted, modified, or staged files |
| 46 | +git reset --hard HEAD |
| 47 | +git clean -fd |
| 48 | + |
| 49 | +# Safely pull the absolute latest changes from the remote |
| 50 | +git pull origin <branch_name> |
| 51 | +``` |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +## 3. GitHub CLI (`gh`) for Agentic Context |
| 56 | +Use `gh` to read the environment, establish your identity, and build a timeline of events. |
| 57 | + |
| 58 | +### Identity & Verification |
| 59 | +Before acting, you must know your own username so you can recognize your own comments. |
| 60 | +```bash |
| 61 | +# Retrieve your bot's authenticated username |
| 62 | +gh api user -q .login |
| 63 | +``` |
| 64 | + |
| 65 | +### Reading PR State & Feedback |
| 66 | +To prevent infinite loops, you must fetch the state, the reviews, and the inline comments simultaneously to build a timeline. |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | +```bash |
| 71 | +# Get the high-level PR state (Merge status, Base/Head info) |
| 72 | +gh pr view <URL> --json state,headRepositoryOwner,headRepository,headRefName |
| 73 | + |
| 74 | +# Get general conversation and formal reviews |
| 75 | +gh pr view <URL> --json comments,reviews |
| 76 | + |
| 77 | +# Get inline code comments with timestamps and authors mapped via jq |
| 78 | +gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '.[] | "[\(.created_at)] \(.user.login) on File \(.path) (Line \(.line)): \(.body)\n---"' |
| 79 | +``` |
| 80 | + |
| 81 | +### Checking CI Status (Continuous Integration) |
| 82 | +Before pushing new fixes or declaring a task complete, verify the CI pipeline. |
| 83 | +```bash |
| 84 | +# Outputs a clean table of passing/failing checks |
| 85 | +gh pr checks <URL> |
| 86 | +``` |
| 87 | +*Agentic Rule*: If checks fail, attempt to reproduce them locally in your worktree (`npm test`, `pytest`) before pushing a fix. If you attempt 3 fixes and CI still fails, **STOP** and request human assistance to prevent an infinite loop. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## 4. Safe Pushing & Conflict Resolution |
| 92 | +When multiple humans and agents work on a PR, your `git push` may be rejected if the remote branch moved ahead while you were working. |
| 93 | + |
| 94 | +### The Rebase-Push Workflow |
| 95 | +Never force push (`--force`) unless explicitly commanded. Use `--rebase` to replay your automated commits cleanly on top of the human's new commits. |
| 96 | + |
| 97 | +```bash |
| 98 | +# Standard push (assumes tracking is set up) |
| 99 | +git push -u origin HEAD |
| 100 | + |
| 101 | +# IF REJECTED ("fetch first" error): |
| 102 | +git pull --rebase origin <branch_name> |
| 103 | +# (Resolve conflicts if necessary, then `git rebase --continue`) |
| 104 | +git push origin HEAD |
| 105 | +``` |
| 106 | + |
| 107 | +--- |
| 108 | + |
| 109 | +## 5. The "Checkpoint" Protocol (Leaving the Last Word) |
| 110 | +To ensure background loops are idempotent (safe to run repeatedly), you must leave a comment on the PR after pushing a fix. When you scan the PR later, if the *last* comment in the timeline is yours, you know you are waiting on a human or CI, and should safely ignore the PR. |
| 111 | + |
| 112 | +```bash |
| 113 | +# Standard Checkpoint Reply |
| 114 | +gh pr comment <URL> -b "I have applied the requested fixes. Awaiting further review." |
| 115 | + |
| 116 | +# CI Attempt Checkpoint |
| 117 | +gh pr comment <URL> -b "I have pushed an attempted fix for the CI failures." |
| 118 | +``` |
0 commit comments