[docs] Document GitButler branching/PR workflow in AGENTS.md

[jp-agenta]

Context

The repo can run in GitButler workspace mode, but AGENTS.md had no guidance on using the but CLI. This led to relearning the same gotchas (force-push semantics, stacked PRs, when commits get swept into the wrong lane).

Changes

• Add a "Branching and PRs with GitButler" section to AGENTS.md: the but lifecycle (status/branch/commit/absorb/push), stacked-PR flow via gh pr create --base <parent>, and the hard-won gotchas (linear-history requirement, absorb over hand-amend, but pull rebases on main not the branch's upstream, oplog snapshot/restore for recovery).
• Ignore the local .gitbutler.lanes.md lane-tracking scratchpad in .gitignore.

Tests / notes

• Docs + gitignore only. No code.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 17, 2026 10:34am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 29d60808-5583-40f8-af81-90d436daa116

📥 Commits

Reviewing files that changed from the base of the PR and between 5722ff7 and 97cb551.

📒 Files selected for processing (2)

• .gitignore
• AGENTS.md

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Added comprehensive guidance for using GitButler, including instructions for creating branches, commits, and pull requests, handling stacked PRs, and important workflow considerations.

• Chores

  • Updated development configuration files.

Walkthrough

Adds a "Branching and PRs with GitButler" section to AGENTS.md documenting the but CLI workflow for branching, committing, creating PRs, and handling stacked PRs. Also updates .gitignore to exclude the /.gitbutler.lanes.md file.

Changes

GitButler Tooling Documentation

Layer / File(s)	Summary
GitButler workflow docs and .gitignore entry AGENTS.md, .gitignore	Inserts a new section in AGENTS.md with but CLI commands for creating branches, commits, and PRs in GitButler workspace mode, including stacked PR base-branch handling, safe amend/absorb patterns, and workflow gotchas. Adds /.gitbutler.lanes.md to .gitignore alongside existing IDE/LSP entries.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Agenta-AI/agenta#4543: Also modifies AGENTS.md with structural rewrites and scoped contributor guidance, directly overlapping with this PR's addition of a new workflow section to the same file.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding GitButler branching/PR workflow documentation to AGENTS.md, which is the primary focus of this PR.
Description check	✅ Passed	The description is directly related to the changeset, providing context, detailed explanation of changes, and testing notes that align with the AGENTS.md and .gitignore modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore-gitbutler-workflow-docs

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds contributor-facing guidance for working in GitButler workspace mode, documenting an opinionated but CLI workflow and common pitfalls, and ensures a local GitButler lane scratchpad file isn’t accidentally committed.

Changes:

• Document the GitButler lane/stack workflow (but status/branch/commit/absorb/push) and a stacked-PR flow using gh pr create --base <parent>.
• Capture key GitButler gotchas (linear history expectations, but pull behavior, oplog snapshot/restore recovery).
• Ignore .gitbutler.lanes.md in .gitignore.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.

File	Description
AGENTS.md	Adds a new “Branching and PRs with GitButler” section describing a recommended workflow and recovery guidance.
.gitignore	Ignores a local GitButler lane-tracking scratchpad file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mmabrouk]

I am not sure this the right way to do it.

I would rather instead:

• Have a small note: this current trunk might be using gitbutler. In that case the current branch `gitbutler/workspace. If that is the case please check local skills and memories to how to deal with gitbuterl

And then have the rest in your local skills / memories

[mmabrouk]

Global Agents.md tokens are very valuable, we should only have important things in global context