Defame1297
20e5627fd7
Three statements were false against the git in use (2.39.5), each verified by
running it.
`git rebase --autosquash HEAD~N` without `-i` is a silent no-op: git prints
"Successfully rebased", the `fixup!` commit survives with the same SHA, and
rewrite-history.md presented that as the preferred flow with `-i` as an optional
review step. The agent reports the squash as done and the `fixup!` subject then
trips this repo's own commit-msg gate. `-i` is now the command, not the alternative.
"Fetch never modifies a local branch, so it is always safe to run" — new text on
this branch — is false: `git fetch origin main:probe` fast-forwarded the local
branch, and a `+` prefix force-updates it, losing commits. The claim is scoped to
the no-refspec form.
`git worktree add --orphan` does not exist before Git 2.42; on 2.39.5 it is
`error: unknown option 'orphan'`, exit 129. The same file gives a version floor for
`--recurse-submodules` three sections earlier. Floor added, with a fallback that
was tested before being documented.
git-workflow claimed "every request resolves to exactly one of these six" while
rebase, reset and stash were owned by no skill — `git reset` appeared nowhere in
the plugin, old tree or new — so "undo my last commit" routed nowhere. The claim is
gone, the router gains rows for all three, and the procedures now exist: plain
rebase with `--onto` and conflict handling, a reset mode table gated on `--hard`,
and stash save/pop/list/drop. `--hard` gets an always-loaded Gotcha, matching the
register the force-push refusal already sets.
Cherry-pick had three claimants pointing at git-history while git-commits owned the
flow, and the two copies were not equivalent — git-history's lacked the destination
check, the rtk prefix and `--abort`. Resolved to git-commits per #112; the weaker
duplicate is replaced by a hand-off.
git-commits' metadata.version was deleted rather than bumped in 14af50b, leaving two
house-contract documents citing a worked v0.1.2 to v0.1.3 transition against a file
declaring no version. Restored to 0.1.3.
Also: the divergent-pull explanation stated a `--ff-only` default that does not
exist (it is a hard error); `--remote` "requires" a configured branch where it uses
one; `git push origin --delete` moved to git-remotes, which owns the remote-side
gates; seven retired `git:<name>` source slugs; git-orchestrate quoted a
git-workflow sentence that no longer exists; git-submodules regains the indirect
trigger that made "add a dependency repo" routable; and commit atomicity is a common
gate rather than reachable only from the create flow.
Refs: #112, #113
4.3 KiB
4.3 KiB
name, description, metadata
| name | description | metadata | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| git-workflow | Use when a human's local git request is general or ambiguous — it routes to the owning domain skill: `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules` or `git-worktrees`. An unambiguous request goes straight to its domain skill instead. Not an agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. |
|
Gotchas
- Session context built during one multi-step request — branch names, the chosen base, the commit strategy — persists for that request and then clears. Do not re-ask the user for a decision they already gave you earlier in the same workflow.
- Run parent-repo commands through
rtk git <command>, never baregit <command>. This is a mandated org wrapper, not a style preference. Submodule-specific commands run from inside the submodule's own directory instead.
Domains
Route to the domain that owns the operation, and in sequence when a request spans two — a rebase
that ends in a force-push is git-commits, then git-remotes. An unambiguous request should have
gone straight to the domain skill; this one exists for the ones that did not.
| The request is about | Domain |
|---|---|
| Writing, amending, squashing, or cherry-picking a commit, and its message | git-commits |
Rebasing onto a new base, or undoing a commit with reset |
git-commits |
| Creating, switching, deleting, renaming, tracking, or merging a local branch | git-branches |
| Stashing work in progress to move between branches | git-branches |
| When a change landed, which commit broke something, what to revert or backport | git-history |
| Anything touching a remote — remote config, fetch, push, pull — even unnamed | git-remotes |
| A nested repository pinned inside this one by a recorded commit | git-submodules |
| Several branches checked out at once, in separate directories, without stashing | git-worktrees |
git-orchestrate executes whatever this resolves to (step 5); the table only decides which domain
owns the request.
Workflow
- Parse intent — extract the operation and, from the table above, the domain that owns it, plus any options the user named.
- Check the hard rules — if the request creates, amends, or rewrites a commit, pushes, or
touches hooks, config, or credentials, read
references/hard-rules.md. Raise the relevant rule before acting, not after. - Read the repo — current branch, working-tree state, and which branching model the repo
follows (the orchestrator reads
branching_patternfrom plugin config; infer from branch names if absent); the last of those decides which tips are worth offering. - Gate destructive operations — before force-push, branch deletion, rebase, or
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
confirmations: never offer "Proceed?" for a force-push of
mainormaster. - Invoke the
git-orchestrateagent withoperation,parameters(user-provided or inferred),context(step 3 plus the session context), andconfirm: trueonly for a destructive op the user approved in step 4. - Clarify when the orchestrator asks for more — put its question to the user in plain language ("Which branch should this be based on?") and loop back to step 5 with the answer.
- Report the outcome — on success, the result and what changed, in plain language; on failure, the error reason and a recovery action.
Interaction style
The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as you go, and prefer natural language to raw command lines.
Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo,
feature branches come off develop and main tracks only released code; on a trunk-based or
GitHub Flow repo, short-lived branches off main keep merges small and reviewable.