[docs] Move GitButler stack mechanics out of AGENTS.md into a skill - #6359
Conversation
The stack section had grown to 173 of AGENTS.md's 281 lines (61%), while only ~6% of recent merged PRs were stacked. Every session paid context for lore it rarely needed, and the section broke the file's own rule to keep the always-loaded layer small. Move the four stack subsections verbatim into a new gitbutler-stacks skill that loads on demand. AGENTS.md keeps the everyday but commands plus two rules promoted out of the gotchas because they apply to single-lane work too: oplog recovery, and rebase-don't-merge-main-in.
dosubot
Bot
added
the
size:L
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe repository adds a GitButler stack workflow skill. It documents lane commits, stash isolation, stack topology, recovery, and common GitButler issues. Repository guidance references the skill, and a Claude skill link and ignore entries support it. ChangesGitButler stack guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Merge Risk: 🔵 Low · up to The PR moves GitButler procedures into a new on-demand skill, but one downstream workflow still uses path-based lane lookup and another blanket no-stash rule conflicts with multi-lane edit isolation. This could cause incorrect lane assignment or failed recovery workflows, so merge is reasonable with explicit owner follow-up. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.) ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: ec2bed87-27d3-4acd-ae32-4d11059c5f33
📒 Files selected for processing (4)
.agents/skills/gitbutler-stacks/SKILL.md.claude/skills/gitbutler-stacks.gitignoreAGENTS.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
| - **`but rub` by path goes stale after any mutation.** Every `but` mutation kicks a | ||
| background sync that invalidates the path index, so the *next* path-based | ||
| `but rub <path> ...` often fails with "Source '<path>' not found". Use the stable | ||
| **cliId** instead (the 2-4 char code in `but status` / `but status --json`): | ||
| `but rub <cliId> <target>`. cliIds survive across the sync; paths don't. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
printf '%s\n' '--- repository conventions ---'
find /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a -maxdepth 2 -type f -name '*.md' -print
printf '%s\n' '--- target skill ---'
sed -n '1,110p' .agents/skills/gitbutler-stacks/SKILL.md
printf '%s\n' '--- downstream instructions ---'
sed -n '1,180p' .agents/skills/implement-feature/SKILL.md
printf '%s\n' '--- handoff stash guidance ---'
rg -n -C 5 'git stash|no git stash|stash' docs/design/onboarding-revamp/HANDOFF.md
printf '%s\n' '--- scoped conventions and learnings ---'
for f in /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/*/*.md; do
case "$f" in
*architecture*gitbutler*|*architecture*implement*|*architecture*onboarding*|*learnings*gitbutler*|*learnings*implement*|*learnings*onboarding*) cat "$f";;
esac
doneRepository: Agenta-AI/agenta
Length of output: 26033
🌐 Web query:
GitButler CLI documentation "but branch new" "but rub" cliId path
💡 Result:
The GitButler CLI (accessed via the but command) provides specific subcommands for managing branches and editing commit history. Based on your request, here is the information regarding branch creation and history editing ("rubbing"): Branch Creation To create a new branch, use the but branch new command [1]: but branch new This creates a new parallel branch in your workspace [1]. If you wish to create a branch stacked on an existing branch, you can use the -a (or --above) flag: but branch new -a History Editing ("Rubbing") In GitButler terminology, editing or manipulating commit history is often referred to as "rubbing" [2]. You can access documentation on these operations via the but rub command or by visiting the "Edit commit history" guide in the official documentation [3]. Common history editing commands include: but amend: Used to add uncommitted changes to an existing commit [3]. but uncommit: Moves a commit (or a specific file from a commit) back to the uncommitted area [3]. but squash: Combines a newer commit into an older target commit [3]. but move: Moves a commit to a different branch or changes its order [3]. but status -fv: A helpful command to view commit IDs and file IDs necessary for performing these history edits [3]. For further assistance, you can always run but help or consult the official GitButler CLI documentation at docs.gitbutler.com [4][5].
Citations:
- 1: https://blog.gitbutler.com/but-cli
- 2: https://gitbutler.com/downloads
- 3: https://docs.gitbutler.com/cli-guides/cli-tutorial/rubbing
- 4: https://docs.gitbutler.com/cli-overview
- 5: https://docs.gitbutler.com/commands/commands-overview
🏁 Script executed:
printf '%s\n' '--- gitbutler skill isolation and branch sections ---'
sed -n '68,105p' .agents/skills/gitbutler-stacks/SKILL.md
sed -n '190,260p' .agents/skills/gitbutler-stacks/SKILL.md
printf '%s\n' '--- implement-feature GitButler section ---'
rg -n -C 12 'but branch new|but rub|cliId|Phase 6|GitButler' .agents/skills/implement-feature/SKILL.md
printf '%s\n' '--- handoff workflow section ---'
sed -n '220,242p' docs/design/onboarding-revamp/HANDOFF.md
printf '%s\n' '--- applicable learning ---'
cat /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings/agents-skills.mdRepository: Agenta-AI/agenta
Length of output: 14417
🌐 Web query:
site:docs.gitbutler.com CLI "Source" "not found" path "cliId" but rub
💡 Result:
The error message "CLI Source not found" in the context of the GitButler CLI (but) indicates that the system cannot locate the specific entity (such as a commit, branch, or file) you are attempting to target using its CLI ID [1][2]. GitButler assigns short, stable CLI IDs (e.g., "nn", "c5") to entities like commits and branches to allow for easy manipulation [1][3][4]. If you receive this error, it is typically for one of the following reasons: 1. The provided CLI ID is incorrect, has expired, or is no longer valid because the underlying git history or branch structure has been rewritten [4]. 2. The entity associated with the ID has been moved, squashed, or deleted [5][6]. 3. The command is being run in a repository that has not been initialized with but setup, or the current workspace state has changed [7][8]. To resolve this, ensure you are referencing a current and valid ID by running the following command to refresh your list of active entities: but status -fv This command displays the latest commit IDs and file IDs within each commit, which you can then use for operations like but show, but diff, or but move [4]. For more detailed information on managing these identifiers, you can also run: but help cli-ids
Citations:
- 1: https://docs.gitbutler.com/cli-guides/cli-tutorial/inspecting
- 2: https://docs.gitbutler.com/commands/but-diff
- 3: https://docs.gitbutler.com/commands/but-show
- 4: https://docs.gitbutler.com/cli-guides/cli-tutorial/rubbing
- 5: https://docs.gitbutler.com/commands/but-squash
- 6: https://docs.gitbutler.com/commands/but-move
- 7: https://docs.gitbutler.com/cli-guides/installation
- 8: https://docs.gitbutler.com/commands/commands-overview
Align downstream GitButler instructions with this skill.
.agents/skills/implement-feature/SKILL.md still runs but rub <path> <branch> after but branch new; use the stable file cliId instead because path lookup can fail after a mutation.
Scope the unqualified no git stash rule in docs/design/onboarding-revamp/HANDOFF.md to the normal new-lane workflow. Multi-lane isolation requires git stash push -u before restoring files lane by lane.
2 participants
Context
The GitButler section had grown to 173 of AGENTS.md's 281 lines. That is 61% of a file whose own closing section says to keep the always-loaded instruction layer small and push procedural guidance into layers that load on demand.
All four of its subsections cover stacked branches. Only 6 of the last 100 merged PRs were stacked. Every agent session in every area of the repo paid that context for mechanics it rarely needed.
Changes
The four stack subsections move verbatim into a new
gitbutler-stacksskill that loads on demand. AGENTS.md goes from 281 to 141 lines.It keeps the intro and the five everyday
butcommands, and gains two rules promoted out of the gotchas list because they apply to single-lane work too:but oplog listthenbut oplog restore <sha>as the recovery path.The skill opens with the rule that prevents most of what it documents. Commit each change to its lane as you go, instead of making edits first and assigning lanes afterward. The longest subsection ("Spreading a pile of edits back across an existing stack") exists only because that order gets reversed.
New
.gitignoreentries allowlist the skill directory and its.claude/skillssymlink, matching how the other repo skills are tracked.Tests
Notes
AGENTS.md still says to force-push with
but push <branch> -f. That contradicts how the team actually works and is worth a separate pass. Left alone here to keep this change to the move.