📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,357 @@
|
||||
---
|
||||
name: gitbutler-multi-agent
|
||||
description: This skill should be used when coordinating multiple AI agents working concurrently, handling agent handoffs, transferring commits between agents, or when "multi-agent", "concurrent agents", "parallel agents", "agent collaboration", or "parallel execution" are mentioned with GitButler. Provides virtual branch patterns for parallel execution without coordination overhead.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
author: outfitter
|
||||
category: version-control
|
||||
related-skills:
|
||||
- gitbutler-virtual-branches
|
||||
- gitbutler-stacks
|
||||
- multi-agent-vcs
|
||||
---
|
||||
|
||||
# GitButler Multi-Agent Coordination
|
||||
|
||||
Multiple agents → virtual branches → parallel execution → zero coordination overhead.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Multiple agents working on different features simultaneously
|
||||
- Sequential agent handoffs (Agent A → Agent B)
|
||||
- Commit ownership transfer between agents
|
||||
- Parallel execution with early conflict detection
|
||||
- Post-hoc reorganization of multi-agent work
|
||||
|
||||
NOT for: single-agent workflows (use standard GitButler), projects needing PR automation (Graphite better)
|
||||
|
||||
</when_to_use>
|
||||
|
||||
## Core Advantage
|
||||
|
||||
**Traditional Git Problem:**
|
||||
- Agents must work in separate worktrees (directory coordination)
|
||||
- Constant branch switching (context loss, file churn)
|
||||
- Late conflict detection (only at merge time)
|
||||
|
||||
**GitButler Solution:**
|
||||
- Multiple branches stay applied simultaneously
|
||||
- Single shared workspace, zero checkout operations
|
||||
- Immediate conflict detection (shared working tree)
|
||||
- Each agent manipulates their own lane
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Parallel Feature Development
|
||||
|
||||
```bash
|
||||
# Agent 1
|
||||
but branch new agent-1-auth
|
||||
echo "auth code" > auth.ts
|
||||
but rub auth.ts agent-1-auth
|
||||
but commit agent-1-auth -m "feat: add authentication"
|
||||
|
||||
# Agent 2 (simultaneously, same workspace!)
|
||||
but branch new agent-2-api
|
||||
echo "api code" > api.ts
|
||||
but rub api.ts agent-2-api
|
||||
but commit agent-2-api -m "feat: add API endpoints"
|
||||
|
||||
# Result: Two independent features, zero conflicts
|
||||
```
|
||||
|
||||
### Pattern 2: Sequential Handoff
|
||||
|
||||
```bash
|
||||
# Agent A: Initial implementation
|
||||
but branch new initial-impl
|
||||
# ... code ...
|
||||
but commit initial-impl -m "feat: initial implementation"
|
||||
|
||||
# Agent B: Takes ownership and refines
|
||||
but rub <agent-a-commit> refinement-branch
|
||||
# ... improve code ...
|
||||
but commit refinement-branch -m "refactor: optimize implementation"
|
||||
```
|
||||
|
||||
### Pattern 3: Cross-Agent Commit Transfer
|
||||
|
||||
```bash
|
||||
# Instant ownership transfer
|
||||
but rub <commit-sha> agent-b-branch # Agent A → Agent B
|
||||
but rub <commit-sha> agent-a-branch # Agent B → Agent A
|
||||
```
|
||||
|
||||
### Pattern 4: Agent Code Review Cycle
|
||||
|
||||
Reviewer agent commits fixes separately, then swap/merge:
|
||||
|
||||
```bash
|
||||
# Author agent implements
|
||||
but branch new author-impl
|
||||
but commit author-impl -m "feat: implement feature"
|
||||
|
||||
# Reviewer agent creates sibling branch for fixes
|
||||
but branch new reviewer-fixes
|
||||
# ... reviewer makes fixes ...
|
||||
but commit reviewer-fixes -m "fix: address review feedback"
|
||||
|
||||
# Adopt reviewer fixes into author branch
|
||||
but rub <reviewer-commit> author-impl
|
||||
|
||||
# Clean audit trail, final branch has both
|
||||
```
|
||||
|
||||
### Pattern 5: Agent Swarm (Many Agents, One Branch)
|
||||
|
||||
Multiple agents contribute to a single feature:
|
||||
|
||||
```bash
|
||||
but branch new shared-feature
|
||||
|
||||
# Agent A assigns their work
|
||||
but rub <a-file-id> shared-feature
|
||||
|
||||
# Agent B assigns their work
|
||||
but rub <b-file-id> shared-feature
|
||||
|
||||
# Agent C assigns their work
|
||||
but rub <c-file-id> shared-feature
|
||||
|
||||
# Single commit with all contributions
|
||||
but commit shared-feature -m "feat: collaborative implementation"
|
||||
```
|
||||
|
||||
Use with Workspace Rules (`but mark`) for auto-assignment to branches.
|
||||
|
||||
### Pattern 6: Exploratory Development
|
||||
|
||||
Compare multiple approaches in parallel:
|
||||
|
||||
```bash
|
||||
# Parent branch with shared setup
|
||||
but branch new perf-parent
|
||||
but commit perf-parent -m "chore: benchmark setup"
|
||||
|
||||
# Strategy A
|
||||
but branch new perf-strategy-a --anchor perf-parent
|
||||
but commit perf-strategy-a -m "perf: try caching approach"
|
||||
|
||||
# Strategy B
|
||||
but branch new perf-strategy-b --anchor perf-parent
|
||||
but commit perf-strategy-b -m "perf: try batching approach"
|
||||
|
||||
# Run benchmarks on each, keep winner
|
||||
but rub <winning-commit> perf-parent
|
||||
```
|
||||
|
||||
### Pattern 7: Emergency Hotfix (Feature Work Continues)
|
||||
|
||||
Ship a fix without disturbing ongoing multi-agent work:
|
||||
|
||||
```bash
|
||||
# Create isolated hotfix branch
|
||||
but branch new hotfix-urgent
|
||||
but rub <file-id> hotfix-urgent
|
||||
but commit hotfix-urgent -m "fix: prod outage"
|
||||
|
||||
# Push and create PR
|
||||
but push hotfix-urgent
|
||||
but pr new hotfix-urgent
|
||||
|
||||
# Other agents continue unaffected in their lanes
|
||||
```
|
||||
|
||||
## Branch Naming Convention
|
||||
|
||||
```
|
||||
<agent-name>-<task-type>-<brief-description>
|
||||
|
||||
Examples:
|
||||
- claude-feat-user-auth
|
||||
- droid-fix-api-timeout
|
||||
- codex-refactor-database-layer
|
||||
```
|
||||
|
||||
Makes ownership immediately visible in `but status`.
|
||||
|
||||
## AI Integration Methods
|
||||
|
||||
### 1. Agents Tab (GUI)
|
||||
|
||||
- Branch-agent binding in GitButler GUI
|
||||
- Each virtual branch = independent agent session
|
||||
- Automatic commit management per session
|
||||
- Parallel execution with branch isolation
|
||||
- Access: `but gui` then navigate to Agents Tab
|
||||
|
||||
### 2. Lifecycle Hooks (CLI)
|
||||
|
||||
| Platform | Commands |
|
||||
|----------|----------|
|
||||
| **Claude Code** | `but claude pre-tool`, `but claude post-tool`, `but claude stop` |
|
||||
| **Cursor** | `but cursor after-edit`, `but cursor stop` |
|
||||
|
||||
Example Claude Code hooks config (`.claude/hooks.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "but claude post-tool"}]}],
|
||||
"Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "but claude stop"}]}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. MCP Server
|
||||
|
||||
```bash
|
||||
but mcp # Start MCP server for programmatic access
|
||||
```
|
||||
|
||||
Exposes `gitbutler_update_branches` tool for async commit processing.
|
||||
|
||||
### 4. Workspace Rules (Auto-Assignment)
|
||||
|
||||
```bash
|
||||
but mark agent-auth-branch
|
||||
but mark agent-api-branch
|
||||
```
|
||||
|
||||
New changes auto-route to the marked branch.
|
||||
|
||||
**Key Instruction for All Agents:**
|
||||
> "Never use the git commit command after a task is finished"
|
||||
|
||||
For detailed hook configs and MCP schemas, see `references/ai-integration.md`.
|
||||
|
||||
## The `but rub` Power Tool
|
||||
|
||||
Single command handles four critical multi-agent operations:
|
||||
|
||||
| Operation | Example | Use Case |
|
||||
|-----------|---------|----------|
|
||||
| **Assign** | `but rub m6 claude-branch` | Organize files to branches post-hoc |
|
||||
| **Move** | `but rub abc1234 other-branch` | Transfer work between agents |
|
||||
| **Squash** | `but rub newer older` | Clean up history |
|
||||
| **Amend** | `but rub file commit` | Fix existing commits |
|
||||
|
||||
## Coordination Protocols
|
||||
|
||||
**Status Broadcasting:**
|
||||
|
||||
```bash
|
||||
# File-based coordination
|
||||
but status > /tmp/agent-$(whoami)-status.txt
|
||||
|
||||
# Or use Linear/GitHub comments
|
||||
# "[AGENT-A] Completed auth module, committed to claude-auth-feature"
|
||||
```
|
||||
|
||||
**Concurrent Safety:**
|
||||
1. Snapshot before risky operations
|
||||
2. Broadcast status regularly to other agents
|
||||
3. Respect 🔒 locks — files assigned to other branches
|
||||
4. Use `but --json` for programmatic state inspection
|
||||
|
||||
## vs Other Workflows
|
||||
|
||||
| Aspect | Graphite | Git Worktrees | GitButler |
|
||||
|--------|----------|---------------|-----------|
|
||||
| Multi-agent concurrency | Serial | N directories | Parallel ✓ |
|
||||
| Post-hoc organization | Difficult | Difficult | `but rub` ✓ |
|
||||
| PR Submission | `gt submit` ✓ | Manual | `but push` + `but pr new` ✓ |
|
||||
| Physical layout | 1 directory | N × repo | 1 directory ✓ |
|
||||
| Context switching | `gt checkout` | `cd` | None ✓ |
|
||||
| Conflict detection | Late (merge) | Late (merge) | Early ✓ |
|
||||
| Disk usage | 1 × repo | N × repo | 1 × repo ✓ |
|
||||
|
||||
## Decision Framework: When to Use What
|
||||
|
||||
### Use GitButler when:
|
||||
|
||||
- Multiple agents work in same repo simultaneously
|
||||
- Exploratory development (organize code after writing)
|
||||
- Frequent reorganization of commits between branches
|
||||
- Visual organization preferred (GUI + CLI)
|
||||
- Early conflict detection matters
|
||||
|
||||
### Use Graphite when:
|
||||
|
||||
- Fully automated CLI workflows (scripted end-to-end)
|
||||
- Terminal-first teams
|
||||
- Established stacked PR practices
|
||||
- Need `gt up`/`gt down` stack navigation
|
||||
|
||||
### Use Git Worktrees when:
|
||||
|
||||
- Complete branch isolation required
|
||||
- Different dependencies per branch
|
||||
- CI/CD needs separate checkouts
|
||||
|
||||
**Don't mix in same repo** - Choose one model per repository.
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Use unique branch names per agent: `<agent>-<type>-<desc>`
|
||||
- Assign files immediately after creating: `but rub <id> <branch>`
|
||||
- Snapshot before coordinated operations
|
||||
- Broadcast status to other agents when completing work
|
||||
- Check for 🔒 locked files before modifying
|
||||
|
||||
NEVER:
|
||||
- Use `git commit` — breaks GitButler state
|
||||
- Let files sit in "Unassigned Changes" — assign immediately
|
||||
- Modify files locked to other branches
|
||||
- Mix git and but commands during active agent sessions
|
||||
|
||||
</rules>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Solution |
|
||||
|---------|-------|----------|
|
||||
| Agent commit "orphaned" | Used `git commit` | Find with `git reflog`, recover |
|
||||
| Files in wrong branch | Forgot assignment | `but rub <id> <correct-branch>` |
|
||||
| Conflicting edits | Overlapping files | Reassign hunks to different branches |
|
||||
| Lost agent work | Branch deleted | `but undo` or restore from oplog |
|
||||
|
||||
## Recovery
|
||||
|
||||
```bash
|
||||
# Find orphaned commits
|
||||
git reflog
|
||||
|
||||
# Recover agent work
|
||||
but oplog
|
||||
but undo
|
||||
|
||||
# Extract from snapshot
|
||||
git show <snapshot>:index/path/to/file.txt
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Overlapping file edits** — adjacent lines can only go to one branch
|
||||
- **No stack navigation CLI** — no `gt up`/`gt down` equivalent (all branches always applied)
|
||||
- **MCP server limited** — only `gitbutler_update_branches` tool currently exposed
|
||||
|
||||
<references>
|
||||
|
||||
### Reference Files
|
||||
|
||||
- **`references/ai-integration.md`** — Detailed hook configs, MCP schemas, troubleshooting
|
||||
|
||||
### Related Skills
|
||||
|
||||
- [gitbutler-virtual-branches](../virtual-branches/SKILL.md) — Core GitButler workflows
|
||||
- [gitbutler-stacks](../stacks/SKILL.md) — Stacked branches
|
||||
- **outfitter:multi-agent-vcs** — Tool-agnostic multi-agent policy (invoke with Skill tool)
|
||||
|
||||
### External
|
||||
|
||||
- [GitButler AI Docs](https://docs.gitbutler.com/features/ai-integration/) — Official AI integration
|
||||
- [Agents Tab Blog](https://blog.gitbutler.com/agents-tab) — Claude Code integration details
|
||||
|
||||
</references>
|
||||
@@ -0,0 +1,273 @@
|
||||
# Multi-Agent AI Integration Reference
|
||||
|
||||
Detailed configuration and patterns for multi-agent workflows with GitButler.
|
||||
|
||||
---
|
||||
|
||||
## Hook Configuration by Platform
|
||||
|
||||
### Claude Code
|
||||
|
||||
File: `.claude/hooks.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude pre-tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude post-tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "but claude stop"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Hook | Purpose |
|
||||
|------|---------|
|
||||
| `but claude pre-tool` | Snapshot before changes |
|
||||
| `but claude post-tool` | Auto-assign changes to agent's branch |
|
||||
| `but claude stop` | Finalize commits, cleanup |
|
||||
|
||||
### Cursor
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"after-edit": "but cursor after-edit",
|
||||
"stop": "but cursor stop"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server
|
||||
|
||||
### Starting
|
||||
|
||||
```bash
|
||||
but mcp
|
||||
```
|
||||
|
||||
### Available Tool
|
||||
|
||||
**`gitbutler_update_branches`**
|
||||
|
||||
```typescript
|
||||
{
|
||||
prompt: string // Description of changes
|
||||
}
|
||||
```
|
||||
|
||||
Returns immediately; commits processed asynchronously.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
- Single tool available
|
||||
- No branch creation
|
||||
- No stack operations
|
||||
- No push/PR operations
|
||||
|
||||
---
|
||||
|
||||
## Multi-Agent Coordination Strategies
|
||||
|
||||
### Strategy 1: Branch-Per-Agent
|
||||
|
||||
Each agent owns dedicated branch(es):
|
||||
|
||||
```bash
|
||||
# Agent A owns auth domain
|
||||
but branch new agent-a-auth
|
||||
but mark agent-a-auth
|
||||
|
||||
# Agent B owns api domain
|
||||
but branch new agent-b-api
|
||||
but mark agent-b-api
|
||||
|
||||
# New changes auto-route to marked branch
|
||||
```
|
||||
|
||||
**Best for:** Independent parallel development
|
||||
|
||||
### Strategy 2: Shared Branch with Turn-Taking
|
||||
|
||||
Agents share branch, coordinate via file-based status:
|
||||
|
||||
```bash
|
||||
# File-based coordination
|
||||
but status > /tmp/agent-$(whoami)-status.txt
|
||||
|
||||
# Other agents check before modifying
|
||||
```
|
||||
|
||||
**Best for:** Sequential refinement of same feature
|
||||
|
||||
### Strategy 3: Stack-Per-Agent
|
||||
|
||||
Agents own stack levels:
|
||||
|
||||
```bash
|
||||
# Agent A: Foundation layer
|
||||
but branch new foundation
|
||||
but commit foundation -m "feat: foundation"
|
||||
|
||||
# Agent B: Build on foundation
|
||||
but branch new feature --anchor foundation
|
||||
but commit feature -m "feat: feature layer"
|
||||
|
||||
# Agent C: Tests on top
|
||||
but branch new tests --anchor feature
|
||||
but commit tests -m "test: comprehensive tests"
|
||||
```
|
||||
|
||||
**Best for:** Layered architecture development
|
||||
|
||||
### Strategy 4: Review Pairs
|
||||
|
||||
Author and reviewer agents work in parallel:
|
||||
|
||||
```bash
|
||||
# Author implements
|
||||
but branch new author-impl
|
||||
|
||||
# Reviewer creates sibling for fixes
|
||||
but branch new reviewer-fixes
|
||||
|
||||
# Swap commits as needed
|
||||
but rub <commit> <other-branch>
|
||||
```
|
||||
|
||||
**Best for:** Code review cycles
|
||||
|
||||
---
|
||||
|
||||
## Status Broadcasting
|
||||
|
||||
### File-Based
|
||||
|
||||
```bash
|
||||
# Broadcast status
|
||||
but status > /tmp/agent-status-$(hostname)-$(date +%s).txt
|
||||
|
||||
# Other agents poll status files
|
||||
```
|
||||
|
||||
### Issue Tracker Comments
|
||||
|
||||
```markdown
|
||||
[AGENT-A] Completed auth module
|
||||
- Branch: agent-a-auth
|
||||
- Commits: abc1234
|
||||
- Ready for review
|
||||
```
|
||||
|
||||
### JSON for Programmatic Inspection
|
||||
|
||||
```bash
|
||||
# Machine-readable status
|
||||
but status --json | jq '.stacks'
|
||||
but show feature-branch --json | jq '.commits'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Instructions Template
|
||||
|
||||
Add to agent system prompt:
|
||||
|
||||
```
|
||||
## GitButler Rules
|
||||
|
||||
1. NEVER use `git commit` - use `but commit`
|
||||
2. NEVER use `git add` - GitButler manages staging
|
||||
3. NEVER use `git checkout` - all branches always applied
|
||||
4. ALWAYS check file IDs with `but status` before `but rub`
|
||||
5. ALWAYS snapshot before risky operations: `but oplog snapshot`
|
||||
6. Return to workspace after git ops: `git checkout gitbutler/workspace`
|
||||
|
||||
## Your Branch
|
||||
- Name: {agent-branch-name}
|
||||
- Pattern: {file-pattern}
|
||||
|
||||
Assign your changes: `but rub <file-id> {agent-branch-name}`
|
||||
Commit your work: `but commit {agent-branch-name} -m "your message"`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Multi-Agent
|
||||
|
||||
### Agents modifying same files
|
||||
|
||||
**Symptom:** Overlapping hunks in unassigned changes
|
||||
|
||||
**Solution:**
|
||||
1. Assign non-overlapping hunks to respective branches
|
||||
2. For overlapping lines: coordinate which agent owns them
|
||||
3. Use `but mark` rules for clearer ownership
|
||||
|
||||
### Lost agent work
|
||||
|
||||
**Recovery:**
|
||||
|
||||
```bash
|
||||
# Check oplog
|
||||
but oplog
|
||||
|
||||
# Undo if recent
|
||||
but undo
|
||||
|
||||
# Or restore from snapshot
|
||||
but oplog restore <snapshot-id>
|
||||
```
|
||||
|
||||
### Agent committed with git
|
||||
|
||||
**Symptom:** Orphaned commit not in GitButler
|
||||
|
||||
**Recovery:**
|
||||
|
||||
```bash
|
||||
git reflog # Find orphaned commit
|
||||
# Create new branch from it
|
||||
git branch recovered <commit-sha>
|
||||
# Return to GitButler
|
||||
git checkout gitbutler/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [GitButler MCP Docs](https://docs.gitbutler.com/features/ai-integration/mcp-server)
|
||||
- [Claude Code Hooks Docs](https://docs.gitbutler.com/features/ai-integration/claude-code-hooks)
|
||||
- [Cursor Hooks Docs](https://docs.gitbutler.com/features/ai-integration/cursor-hooks)
|
||||
Reference in New Issue
Block a user