flurdy/agent-skills / skills/rebase
rebase
VerifiedRebase feature or stacked branches, or explicitly integrate a fetched upstream into local main/master. Separate trunk mode proves local replay scope and never enters force-push or PR flows; its mutations require fresh confirmation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/upstream.md | markdown | 10.0 KB |
| scripts/gh-pr-base-branch.shexecutable | script | 70 B |
| scripts/gh-pr-edit-base.shexecutable | script | 80 B |
| scripts/rebase-range.shexecutable | script | 4.9 KB |
| scripts/upstream.py | script | 15.0 KB |
| tests/test-rebase-range.shexecutable | script | 10.9 KB |
| tests/test-skill-contract.shexecutable | script | 5.1 KB |
| tests/test_upstream.py | script | 15.6 KB |
references/upstream.md
View on GitHub# Explicit trunk-upstream integration
This path is entered **only** by `/rebase upstream`. It integrates a freshly observed
upstream tip into local `main` or `master`; it does not rebase or replace remote trunk
history. It never enters feature-mode target inference, force-push, or PR retargeting.
Do not infer it from a refusal by `rebase-range.sh`.
## Boundary and requirements
- `python3` 3.10+, Git with absolute `--git-path` output, and the repository's required
Git wrapper, if any. Divergent
replay requires the native rebase options checked by the helper, including
`--empty=stop` and `--no-update-refs`. Unsupported Git stops; do not weaken flags.
- The helper is read-only: no fetch, reference updates, integration, publication,
file writes, or automatic recovery. Its JSON is evidence, not authorization.
- Follow repository policy and current source/guard authority at every mutation.
Owning a bead, retaining a preview, or invoking this skill grants neither write
authority nor permission to rewrite history or publish.
- No concurrent writers may operate on this checkout. Fresh checks narrow races;
they are **not an atomic lock**. Keep the original inspection and plan unchanged
and independently available throughout integration and verification.
- Treat branch/commit text and JSON as data. Render command arrays with proper shell
quoting (for example `shlex.join`); never `eval` a plan or concatenate commit text
into a command. Show one exact command per approval and tool invocation.
- Use an authorized ignored `.artifacts/` location for caller-saved JSON, not tracked
documentation. Both evidence inputs accept `-` for stdin when file writes are not
authorized. The helper never saves a plan or creates a recovery branch itself.
## 1. Inspect and bind the Git route
For a normal single repository:
```bash
python3 ~/.agents/skills/rebase/scripts/upstream.py inspect --repo /absolute/repository
```
For a workspace requiring `mgit`, run from its root and use the same route throughout:
```bash
python3 ~/.agents/skills/rebase/scripts/upstream.py inspect \
--repo /absolute/member \
--mgit /absolute/workspace/scripts/mgit --service repos/member
```
All Git reads, including preflight and verification, go through this route. The
helper checks that it resolves to the requested repository and binds its cwd,
worktree, common directory, branch, upstream and effective remote configuration.
Never fall back to native Git after a required wrapper fails. For a different
repository-mandated wrapper not supported here, stop rather than bypass it.
Inspection requires a clean, attached `main` or `master`, a branch reflog, no Git
operation/lock in progress, full history, and no replacement/graft graph. It requires
one `branch.<trunk>.remote` and one matching `branch.<trunk>.merge`; multiple configured
repository remotes are fine. `main` tracking remote `master`, arbitrary trunk names,
local-branch upstream `.` and missing tracking refs are deliberately refused in v1.
A named remote backed by a local path is supported. Missing upstream setup is a
separate task; this workflow does not bootstrap it.
The version-1 `upstream-inspection` record contains original HEAD, the pre-fetch
tracking tip, route/configuration identity, other visible refs, and `fetch_command`.
Remote URLs are represented by a configuration digest, never echoed. Show the branch,
remote/ref, original HEAD and old target before proceeding.
## 2. Fresh fetch gate
Use `AskUserQuestion` immediately before the fresh `fetch_command` from inspection.
Show its configured remote and explicit source/destination refspec. Only approval
permits that **one visible fetch invocation**, routed through the required wrapper;
no command chains, `pull`, automatic sync, pruning, or unrelated fetches.
Retain the original inspection and observe the actual fetch exit status. Failure
stops with no integration or retry. A fetch may update local tracking refs even
when upstream history was rewritten; the next step rejects that history.
A helper cannot attest that a fetch ran or that the server has stayed unchanged.
Freshness means the tracking tip observed after the caller's successful fetch, not
proof of the server's present state. Do not manufacture fetch evidence or treat a
caller-supplied record, reflog message, or timestamp as authorization.
## 3. Preview the classification and exact range
Pass the **unchanged pre-fetch inspection**, with the same route options:
```bash
python3 ~/.agents/skills/rebase/scripts/upstream.py plan \
--repo /absolute/repository --before before.json
```
The helper requires unchanged source and route identities and the old tracking tip
as an ancestor of the newly observed tip. Missing evidence, unrelated history,
rewinds and unexpected rewrites stop; there is no automatic merge fallback.
| Classification | Disposition |
|---|---|
| `unchanged` | No integration command; report no-op. |
| `local-ahead` | No integration command; retain local commits, no implied push. |
| `fast-forward` | Preview one `merge --ff-only` to the exact target OID. |
| `replay` | Preview one rebase of the exact local range onto the target OID. |
Show repository, branch, configured upstream, original HEAD, target, common base,
`source_commits`, `remote_commits`, `replay` (subjects and patch IDs), `recovery_head`,
and the exact command. More than 200 commits in either preview range or 5,000 refs
requires a separate bounded investigation; never silently truncate evidence.
Replay rejects local merges, empty commits, upstream-equivalent patches and commits
reachable from another local branch, tag or remote-tracking ref. These are conservative
negative filters, **not proof of nonpublication**: refs may be stale, pruned or absent;
other clones and historical publications are unknown. Do not claim that absence from
one upstream, or even all locally known refs, establishes globally unpublished work.
Require the user to confirm the displayed replay range is unshared. If that cannot
be established, stop for an explicit separate disposition; do not offer force-push.
## 4. Revalidate, then separately confirm local integration
Retain the complete version-1 `upstream-plan`. Immediately before requesting action:
```bash
python3 ~/.agents/skills/rebase/scripts/upstream.py check \
--repo /absolute/repository --plan plan.json
```
Use the same wrapper options as before. `status=current` recomputes and compares the
preview, including source, target, other refs, configuration and command. A stale or
altered plan stops; regenerate the preview and obtain new approval, never reuse it.
For either integration, use `AskUserQuestion` immediately before the command.
For fast-forward, ask explicitly to perform the shown fast-forward. For replay,
explain that this rewrites **local** commit IDs and confirm the range is unshared. Approval
must make that standalone invocation the next tool call. No helper silently applies
it, and fetch approval never covers it. Keep `recovery_head` and the plan available.
The replay command disables autostash, autosquash, update-refs, rebase-merges,
fork-point and rerere-autoupdate surprises; it explicitly reapplies candidates and
stops if a commit becomes empty. Never remove these safeguards to make a refusal pass.
Repository hooks and signing policy still apply. Check their noninteractive support;
do not suppress required hooks or signing to avoid a prompt.
## 5. Conflicts and post-integration verification
On conflict or an empty-commit stop, report state and **stop before continuing**.
Do not skip, resolve, reset, abort, or continue automatically. Ask for an explicit
resolve/continue or abort disposition under current repository/guard permissions.
Use `AskUserQuestion` for each history-changing recovery command's own fresh,
visible approval immediately before that command.
An approved `rebase --abort` should restore the retained source OID; verify that fact.
Never substitute `reset --hard`. Conflict resolution requires manual review even
when later patch checks pass.
After a successful operation, with the original plan and route:
```bash
python3 ~/.agents/skills/rebase/scripts/upstream.py verify \
--repo /absolute/repository --plan plan.json
```
Verification rechecks identity, clean state and other refs; binds `ORIG_HEAD` and the
branch reflog to the original source; proves fetched-target ancestry; and requires
ordered stable patch-ID equality for replay (not just equal commit counts).
A mismatch, missing evidence or changed identity stops. Inspect the original/new
ranges using `range-diff`; legitimate conflict resolutions need manual disposition,
not a fabricated automatic pass. Patch IDs ignore some whitespace and metadata;
`range-diff` is a review aid, not semantic correctness proof.
Discover and run repository-native tests; do not guess a test command. Failed or
unavailable verification/tests blocks publication. Report exactly which evidence
passed and which is missing. Keep the result local.
## 6. Optional later publication: separate non-force gate
Publication is not a continuation implied by a successful rebase. Only when the user
requests it, recheck the local head, route/configuration and the single intended push
endpoint without exposing credentials. Multiple push URLs, mirror configuration,
a push endpoint different from the fetched endpoint, or ambiguous policy stops for
separate review; never silently fan out to additional destinations.
Show the exact verified source OID, remote and full destination ref.
Use `AskUserQuestion` immediately before publication to obtain fresh approval for
one visible **non-force push**, with no forced refspec,
no follow-tags and no PR retargeting. Route through the repository wrapper. For example:
```text
git push --no-force --no-follow-tags <remote> <verified-head>:refs/heads/<trunk>
```
This explicit refspec must not be replaced by configured push defaults. The server's
non-fast-forward check remains authoritative; a rejected push stops without retry,
refetch, escalation or force. Never force-push trunk. Report local integration and
publication as separate outcomes, and never claim an operation that did not run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |