Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(git-plugin): add complete git workflow automation suite

Browse Source 
## Why
The git plugin only covered a partial slice of common git workflows.
This adds the remaining skill set (branches, commits, history, remotes,
submodules, workflow, worktrees) plus a git-orchestrate agent so the
plugin can handle end-to-end git automation instead of a handful of
commands.

## Implementation Notes
Each new skill was validated against its research docs and org
conventions after initial authoring, which surfaced hallucinated
version pins, factual errors, and completeness gaps that were
corrected in the same pass rather than left for follow-up.

## Impact
Bumps the git plugin to 1.3.0.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-07-04 18:41:09 +00:00
parent 05bb9d6e9f
commit 0239b00944
48 changed files with 2306 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
plugins/git/skills/git-remotes/README.md Normal file
View File

@@ -0,0 +1,24 @@
# git-remotes
Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows.
## What it does
This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition.
## Usage
```
/git-remotes
```
Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/README.md` | Describes the references directory contents |
| `references/remotes.md` | Full `set-url` variants, shallow-clone/fetch options, force-push mitigation detail, and pull config precedence |
| `references/sources.md` | Research sources and provenance |

123
plugins/git/skills/git-remotes/SKILL.md Normal file
View File

@@ -0,0 +1,123 @@
---
name: git-remotes
description: >
Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks,
handle fetch patterns and tracking branch updates, support multi-remote workflows.
Use when automating remote operations, pushing with force-push safety, fetching with pruning,
pulling with divergence resolution, or managing multi-remote tracking. Include indirect triggers:
any git operation that touches a remote, even if the user doesn't explicitly name the remote.
Do not use when working with local git history, commits, branches, or staging — use git-history
or git-branches instead.
metadata:
category: git-workflow
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
- context7-git-htmldocs
---
## Gotchas
- **Never force-push `main` or `master`, under any circumstances** — this is a hard refusal, not a `confirm: true` gate. If a force-push targets one of these branches, decline and explain why, regardless of how the request is confirmed.
- **Force-push to any other branch requires explicit confirmation** — never execute `git push --force` or `git push -f` without user/agent approval. Always ask or require `confirm: true` flag first.
- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) that run `git fetch` silently defeat the protection. Always combine with `--force-if-includes` or use explicit SHA form `--force-with-lease=<ref>:<sha>`.
- **Prune doesn't touch tags by default** — `git fetch --prune` leaves orphaned tags. Use `git fetch --prune --prune-tags` or configure `fetch.pruneTags true` globally.
- **Pull with rebase rewrites history** — only safe for unpublished work. Rebasing already-pushed commits breaks everyone downstream. Check what's been pushed before rebasing.
- **`git remote show` requires network access** — use `-n` flag for cached data if working offline. `git remote -v` lists URLs without network queries.
- **Pull behavior defaults shift between Git versions** — older versions default to merge, newer versions to `--ff-only`. Always set `pull.ff only` explicitly for deterministic behavior.
## Operations
### Remote Management
Use these to configure which remotes you push to and pull from:
- **Add a remote**: `git remote add <name> <url>` or `git remote add -f <name> <url>` to fetch immediately
- **Remove a remote**: `git remote remove <name>` (deletes remote + all tracking refs + config)
- **Rename a remote**: `git remote rename <old> <new>`
- **Inspect remotes**: `git remote -v` (show URLs) or `git remote show <name>` (live tracking status, requires network)
- **Set-url separately for fetch vs. push**: `git remote set-url --push <name> <url>` changes only where pushes go — but fetch and push URLs must still reference the same repository. For genuine fetch-from-A / push-to-B workflows, use two separate named remotes instead; `--push` cannot do this. Full `set-url` variants (regex-targeted replace, `--add`, `--delete`): `references/remotes.md`.
- **Remove a stale URL**: `git remote set-url --delete <name> <regex>`
- **Inspect effective URLs**: `git remote get-url <name>` (shows URL after `insteadOf` rewrites) or `git remote get-url --push --all <name>` (all push URLs)
- **Track only one branch**: `git remote add -t <branch> <name> <url>` (repeatable), or suppress tag import entirely with `git remote add --no-tags <name> <url>`
- **Mirror a remote**: `git remote add --mirror=fetch <name> <url>` mirrors all refs locally (bare repos only); `--mirror=push` makes every push behave like `--mirror`
- **Prune stale tracking refs without fetching**: `git remote prune <name>` (add `--dry-run` to preview first)
- **Set the remote's default branch pointer**: `git remote set-head <name> -a` (auto-detect, requires a prior fetch), `git remote set-head <name> <branch>` (explicit), or `git remote set-head <name> -d` (delete `refs/remotes/<name>/HEAD`)
### Fetch Operations
Use these to update your tracking branches without touching your local branches:
- **Fetch from one remote**: `git fetch <remote>` — fetches all branches
- **Fetch one branch only**: `git fetch <remote> <branch>` — stores the result in `FETCH_HEAD`, not a tracking ref
- **Fetch from all remotes**: `git fetch --all` with optional `--prune` to clean up stale tracking refs
- **Prune properly**: Use `git fetch --all --prune --prune-tags` to clean both branches and tags
- **Configure auto-prune**: Set `git config --global fetch.prune true` to auto-prune on every fetch across all remotes (or `remote.<name>.prune` to scope it to one remote)
- **Shallow clones**: `--depth=<n>` to deepen or create a shallow clone, `--unshallow` to convert to full history, `--update-shallow` to allow the shallow boundary to move. Details and the default fetch refspec: `references/remotes.md`.
Fetch never modifies your local branches — it only updates remote-tracking branches (`refs/remotes/origin/*`).
### Push Operations
Use these to send your commits upstream. Default: safe push to same-named branch on the remote.
- **Basic push**: `git push <remote> <branch>` — pushes to same-named remote branch
- **Set upstream**: `git push -u <remote> <branch>` — push and configure this branch to track the remote
- **Multi-remote push**: `git push origin develop` and `git push staging develop` sequentially, or use `git remote set-url --add <name> <url>` to push to multiple remotes with one command
- **Force-push safety**: Always use `git push --force-with-lease --force-if-includes <remote> <branch>` over bare `--force`. Require explicit confirmation first — and never for `main`/`master` (see Gotchas). `--force-if-includes` is a no-op without `--force-with-lease`. If background tools (IDE, cron) auto-fetch and could poison the lease check, use a dedicated push-only remote instead — see `references/remotes.md`.
- **Server-side enforcement**: `receive.denyDeletes`, `receive.denyDeleteCurrent`, and `receive.denyNonFastForwards` are enforced on the remote regardless of local flags — a hardened server rejects the push even with `--force`.
- **Delete remote branch**: `git push <remote> --delete <branch>` (not `:<branch>` syntax; clearer and cleaner)
- **Push everything**: `git push --all` (all local branches) or `git push --tags` (all tags)
- **Push a single tag**: `git push origin <tag>`
- **Delete remote branches with no local counterpart**: `git push --prune origin 'refs/heads/*:refs/heads/*'`
- **Force only part of a multi-ref push**: prefix the one refspec that needs it with `+`, e.g. `git push origin +main develop` forces `main` while safe-pushing `develop`
Refspec syntax is `[+]<src>[:<dst>]`:
| Pattern | Meaning |
|---|---|
| `<branch>` | Push to same-named remote branch |
| `<src>:<dst>` | Push `<src>` local ref to `<dst>` remote ref |
| `+<src>:<dst>` | Force this refspec (non-fast-forward allowed) |
| `:<branch>` | Delete remote `<branch>` |
| `refs/heads/*:refs/heads/*` | Glob: push all matching branches |
| `^refs/heads/dev-*` | Negative: exclude matching refs |
| `tag <name>` | Sugar for `refs/tags/<name>:refs/tags/<name>` |
### Pull Operations
Use these to fetch and integrate remote changes. Default strategy: `--ff-only` (fail if diverged, forcing a conscious choice).
- **Pull with fast-forward only**: `git pull --ff-only` (recommended default — fails if you've diverged, forcing a rebase/merge decision)
- **Pull with rebase**: `git pull --rebase` (replays your unpublished commits on top; linear history, but rewrites SHAs — only safe for unpublished work)
- **Pull with merge**: `git pull --no-rebase` (three-way merge commit; preserves original commits, non-linear)
- **Pull with rebase, preserving merges**: `git pull --rebase=merges` (like `--rebase`, but keeps intentional local merge commits during replay)
- **Pull without integrating**: `git pull --squash` collapses incoming commits into staged changes without committing — you write the commit message
- **Set pull strategy globally**: `git config pull.ff only` (or `pull.rebase true`; respects branch-specific overrides via `branch.<name>.rebase`). Full precedence order (CLI flag > `pull.rebase` > `branch.<name>.rebase` > `branch.autoSetupRebase`): `references/remotes.md`.
- **Check before rebasing**: Always verify your commits haven't been pushed before using `--rebase`. Rebasing published commits breaks everyone downstream.
- **Merge strategy default**: Git 2.34+ defaults to the `ort` merge strategy (`recursive` is now just an alias for it). Strategy options like `-X ours`, `-X theirs`, `-X ignore-space-change` still pass through unchanged.
- **Submodules on pull**: `--recurse-submodules` only fetches submodules that are already checked out — newly added submodules are not initialized automatically. Use the `git-submodules` skill to initialize new ones.
If pull diverges and you haven't set a strategy, the operation fails — this is good, forces a conscious choice. Never auto-merge diverged branches without asking.
### Return Format (for agents)
Return structured output:
```json
{
"success": true,
"operation": "push",
"remote": "origin",
"branch": "main",
"output": "...",
"warnings": ["force-with-lease not confirmed"],
"recommendations": ["set pull.ff=only globally"]
}
```
On failure, include `error` field with root cause and recovery suggestion.

17
plugins/git/skills/git-remotes/references/README.md Normal file
View File

@@ -0,0 +1,17 @@
---
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
- context7-git-htmldocs
---
# References
This directory contains provenance metadata and research sources for the `git-remotes` skill.
## Files
- `sources.md` — Extracted research sources and their contributing documents
- `remotes.md` — Full `set-url` variants, shallow-clone/fetch options, default fetch refspec, force-push mitigation detail, server-side deny policies, and pull config precedence

82
plugins/git/skills/git-remotes/references/remotes.md Normal file
View File

@@ -0,0 +1,82 @@
---
topic: remotes
source_keys:
- git-scm-remote-docs
- git-scm-fetch-docs
- git-scm-push-docs
- git-scm-pull-docs
---
## `set-url` — full form
```bash
git remote set-url <name> <newurl> # replace the first fetch URL
git remote set-url <name> <newurl> <oldurl-regex> # replace only the URL matching regex
git remote set-url --push <name> <url> # change push URL only (must point at same repo)
git remote set-url --add <name> <url> # add an extra push URL (push to multiple remotes)
git remote set-url --delete <name> <regex> # remove URLs matching regex
```
`--push` changes only where pushes go — fetch and push URLs must still reference the same repository. For genuine fetch-from-A / push-to-B workflows, use two separate named remotes instead.
## Shallow clones and partial fetch
```bash
git fetch <remote> <branch> # fetch one branch only, stored in FETCH_HEAD (not a local/tracking ref)
git fetch --depth=<n> # deepen history, or create a shallow clone
git fetch --unshallow # convert a shallow clone to full history
git fetch --update-shallow # allow the fetch to update the shallow boundary
git fetch --refmap='' <remote> <branch> # fetch without updating any tracking ref (FETCH_HEAD only)
```
## Default fetch refspec
The default fetch refspec is `+refs/heads/*:refs/remotes/<name>/*`. The leading `+` forces the update — remote-tracking branches always mirror the remote exactly and provide no protection for local history. Fetch never touches your local branches, only remote-tracking refs.
## Force-push safety — full detail
`--force-with-lease` rejects the push if the remote ref moved since your last fetch. Three forms:
| Form | What it protects |
|---|---|
| `--force-with-lease` (bare) | All refs being pushed, checked against your remote-tracking branch |
| `--force-with-lease=<refname>` | Named ref only |
| `--force-with-lease=<refname>:<sha>` | Named ref must be at exact SHA — most stable |
**Caveat with the bare form:** any background process that runs `git fetch` (IDE plugin, cron job, editor auto-fetch) updates your remote-tracking branch, which can make the lease check pass even though someone else pushed in between. The protection is silently defeated.
Two mitigations:
```bash
# Option 1 — dedicated push-only remote: background tools fetch `origin`, you push
# through a separate remote that nothing else touches, so its tracking ref can't be
# poisoned by an unrelated fetch.
git remote add origin-push $(git config remote.origin.url)
git push --force-with-lease origin-push
# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state
git fetch
git tag base master
git rebase -i master
git push --force-with-lease=master:base master:master
```
`--force-if-includes` adds a second check on top of bare `--force-with-lease`: it verifies the remote-tracking tip actually appears in your local branch's reflog, i.e. you genuinely integrated it before rewriting. It is a no-op without `--force-with-lease`, and has no effect when the `--force-with-lease=<ref>:<sha>` form is used (that form already pins an exact SHA).
Safest combination: `git push --force-with-lease --force-if-includes origin`.
Remote-side policies (`receive.denyDeletes`, `receive.denyDeleteCurrent`, `receive.denyNonFastForwards`) are enforced server-side regardless of any local flag — a server configured this way rejects the push even with `--force`.
## Pull config precedence
Highest wins:
1. Command-line flag (`--ff-only` / `--rebase` / `--no-rebase`)
2. `pull.rebase` config (global or local)
3. `branch.<name>.rebase` (branch-specific override)
4. `branch.autoSetupRebase` (set automatically when the tracking branch was created)
```bash
git config --global pull.rebase true
git config branch.develop.rebase false # develop always merges, regardless of the global default
```

71
plugins/git/skills/git-remotes/references/sources.md Normal file
View File

@@ -0,0 +1,71 @@
---
# Research sources referenced by this skill
# Each entry documents where the skill's guidance came from.
---
## git-scm-remote-docs
**Description:** Git SCM official documentation for `git remote` command — remote configuration, add/remove/rename, URL management, inspection, and housekeeping.
**Source:** https://git-scm.com/docs/git-remote
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Remote Management (`git remote`)`
**Contributing files:**
- SKILL.md (Remote Management section)
- references/remotes.md (`set-url` full form)
---
## git-scm-fetch-docs
**Description:** Git SCM official documentation for `git fetch` command — fetching from remotes, tracking branch updates, pruning stale refs, shallow clones, and refspecs.
**Source:** https://git-scm.com/docs/git-fetch
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Fetching (`git fetch`)`
**Contributing files:**
- SKILL.md (Fetch Operations section, Gotchas)
- references/remotes.md (shallow clones, default fetch refspec)
---
## git-scm-push-docs
**Description:** Git SCM official documentation for `git push` command — pushing branches, tags, force-push safety (--force-with-lease, --force-if-includes), refspecs, and multi-remote workflows.
**Source:** https://git-scm.com/docs/git-push
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pushing (`git push`)`
**Contributing files:**
- SKILL.md (Push Operations section, Gotchas)
- references/remotes.md (force-push safety full detail, server-side deny policies)
---
## git-scm-pull-docs
**Description:** Git SCM official documentation for `git pull` command — fetch + merge/rebase strategies, divergence resolution (--ff-only, --rebase, merge), config precedence, and pull-specific gotchas.
**Source:** https://git-scm.com/docs/git-pull
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pulling (`git pull`)`
**Contributing files:**
- SKILL.md (Pull Operations section, Gotchas)
- references/remotes.md (pull config precedence)
---
## context7-git-htmldocs
**Description:** Context7 MCP library providing current Git documentation and API reference — used for validation of modern Git syntax, behavior, and config semantics. This is a blanket cross-cutting reference and does not map to a single heading in the research doc; it informed terminology and syntax checks across all sections.
**Source:** Context7 MCP / Git library
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md (cross-cutting — no dedicated section)
**Contributing files:**
- SKILL.md (all sections)