Shared reference for the version-control operations the skills run against a local working copy of the project‘s source. On the GitHub tool this capability is backed by Git (git + git worktree), which is GitHub’s native VCS.
This is a distinct capability from the tracker / project-board surface documented in operations.md: those recipes talk to the GitHub API over gh; the recipes here operate on a local checkout with the git binary and never touch the network except for explicit fetch / push. A project can in principle pair GitHub's tracker with a different VCS, or a different forge with Git — see When to replace this capability.
This contract has a runnable implementation in tools/vcs/ (magpie-vcs): one abstract VCSBackend interface, a complete Git backend, and detected extension points for the non-Git bridges. A skill can call the abstract operation (magpie-vcs diff, magpie-vcs log) instead of a raw git command and let the tool dispatch to whichever backend governs the working copy. The Git-binding tables below are the contract that tool implements.
The dev-loop skills (issue-fix-workflow, pr-management-code-review, issue-reproducer, issue-reassess) and the setup-steward worktree machinery rely on the following abstract operations. The Git binding is shown alongside each; a sibling VCS tool provides its own binding for the same abstract operation.
| Abstract operation | Git binding | Used by |
|---|---|---|
| Locate the repo root / common dir | git rev-parse --show-toplevel / --git-common-dir / --git-dir | worktree setup, all dev-loop skills |
| Inspect working-copy state | git status (-s / --short) | fix-workflow, code-review pre-flight |
| Create / switch a line of work | git checkout / git switch, git branch | fix-workflow (branch per fix) |
| Stage + record a change | git add, git commit -m | fix-workflow |
| Show changes | git diff (--cached, <base>) | code-review, fix-workflow |
| History read | git log (--oneline / --grep / --author / --since), git show | reproducer, reassess, nomination |
| Determine divergence base | git merge-base, git rev-parse | code-review (diff against base) |
| Sync with the forge | git fetch [origin], git push [-u] | fix-workflow hand-off |
| Re-apply onto an updated base | git rebase | triage rebase action |
| Isolated checkouts | git worktree add / list --porcelain | setup-steward worktree flow |
| Park uncommitted work | git stash --include-untracked | fix-workflow safety |
Write-path operations (commit, push, rebase) stay gated on explicit user confirmation in the calling skill, exactly as the tracker write paths are.
The Git binding assumes a distributed model: local commits, cheap branches, a worktree primitive, and a fetch/push split from the forge. Skills written against this capability should treat those as the abstract contract, not as guaranteed primitives — a centralized backend (e.g. Subversion, Perforce) maps “branch + local commit + push” onto a different shape (changelists, server-side branches) and its tool doc must spell out the divergence.
Source control is a separable capability: any VCS that can provide the abstract operations above can be plugged in by creating a sibling tools/<vcs>/ directory with its own source-control.md binding and listing it in the project manifest under Tools enabled (the Source control row). The generic skill logic — “branch off the default branch, commit the fix, push for review” — does not change when the VCS changes; only the bindings in the tool doc do.
Tracked VCS bridges that implement this capability against a non-Git backend:
tools/asf-svn/ packages the full ASF SVN surface (source control + dist.apache.org release distribution + authorization) for ASF projectsForge bridges that pair a non-GitHub forge with this capability live alongside the tracker bridges (GitLab #305, Forgejo/Gitea #310, Bitbucket #606, SourceHut #607 — the last also exercising the Hg binding).