Gitterflow

GitterFlow: Agent Orchestration

Use GitterFlow to spawn sub-agents that work in parallel on independent tasks. Each sub-agent runs in an isolated git worktree and automatically merges back when complete.

When to Use

Use GitterFlow when you have:

• Multiple independent features that don't conflict with each other
• Large refactoring that can be split into parallel workstreams
• Bug fixes + tests where implementation and testing can happen simultaneously
• Documentation + code tasks that can proceed in parallel

Do NOT use GitterFlow for:

• Tasks that depend on each other's output
• Changes to the same files (will cause merge conflicts)
• Quick single-file fixes (overhead not worth it)

Commands

Spawn a Sub-Agent

gf new --task "Detailed task description" --autonomous

This creates a new worktree, spawns Claude Code with the task, and automatically merges when complete.

Example:

gf new --task "Implement shell completions for bash, zsh, and fish" --autonomous
gf new --task "Add retry logic with exponential backoff to API client" --autonomous
gf new --task "Write comprehensive unit tests for the auth module" --autonomous

Check Status

gf status

Shows all running, completed, and failed sub-agents.

Manual Worktree (Non-Autonomous)

gf new feature-branch --task "Add new feature"

Creates worktree and starts Claude, but requires manual gf finish when done.

How It Works

1. Isolation: Each sub-agent gets its own git worktree (separate directory)
2. Pre-trusted: Worktrees are automatically trusted (no permission dialogs)
3. Auto-merge: Autonomous agents run gf finish when Claude exits
4. Failure handling: Failed agents leave worktree intact for inspection

Task Description Best Practices

Write clear, self-contained task descriptions:

Good:

gf new --task "Add a --verbose flag to all CLI commands. The flag should:
1. Enable detailed logging of git operations
2. Show timing information for each step
3. Be configurable via GITTERFLOW_VERBOSE env var
Include tests for the new functionality." --autonomous

Bad:

gf new --task "Add verbose mode" --autonomous  # Too vague

Parallel Execution Pattern

When orchestrating multiple sub-agents:

# 1. Spawn all sub-agents at once
gf new --task "Implement feature A with tests" --autonomous
gf new --task "Implement feature B with tests" --autonomous
gf new --task "Update documentation for A and B" --autonomous

# 2. Monitor progress
gf status

# 3. Handle any failures
# Failed agents have status: failed
# Inspect worktree: cd ../branch-name
# Fix issues and run: gf finish

Handling Merge Conflicts

If a sub-agent completes but has merge conflicts:

1. Status shows conflict state
2. Navigate to the worktree: cd ../branch-name
3. Resolve conflicts manually
4. Run gf finish to complete the merge

For Sub-Agents: Completing Your Task

If you are a sub-agent spawned by GitterFlow, run gf ready when your task is complete:

gf ready

This command:

1. Auto-commits any uncommitted changes with an AI-generated message
2. Marks your work as ready for the brain to merge
3. Exits successfully - you're done!

IMPORTANT - Do NOT use gf finish! The brain agent will handle merging.

Why gf ready instead of gf finish?

You can't see what other sub-agents are doing. If you try to merge directly:

• You might conflict with another agent's recent merge
• You lack context to resolve conflicts correctly
• You could corrupt the base branch for everyone

The brain agent coordinates all merges because it has full visibility into all agents' work.

After running gf ready:

• Your status changes to ready
• The brain sees you're ready via gf status
• The brain merges your work at the right time
• The brain handles any conflicts with full context

For Brain Agents: Merging Sub-Agent Work

When you are the orchestrating "brain" agent coordinating sub-agents:

1. Monitor Progress

gf status

Look for agents with ready status - these have completed their work and are awaiting merge.

2. Merge Ready Branches

For each ready branch, go to the base branch directory and merge:

# In the main repo (not a worktree)
git checkout main
git pull origin main
git merge <branch-name>

If merge succeeds, the agent's work is now in the base branch.

3. Handle Conflicts

If a merge conflicts:

1. You're left in the base branch with conflict markers
2. Review both sides - you have context from ALL agents
3. Resolve based on your understanding of the full picture
4. Complete the merge: git add . && git commit

4. Merge Order Considerations

• Independent features: any order works
• Overlapping changes: merge simpler/foundation changes first
• If unsure, review diffs before deciding order

5. Update Agent Status (Future Enhancement)

After successful merge, update the agent's status:

# This will be automated in future versions
# For now, the worktree can be cleaned up manually:
git worktree remove <worktree-path>
git branch -d <branch-name>

Plan Mode (Plan-Then-Execute Workflow)

Note: This feature is in design phase. See docs/PLAN-APPROVAL-DESIGN.md.

Overview

Plan mode enables a two-phase workflow where subagents write an implementation plan before executing. The brain agent reviews and approves/rejects plans before any code is written.

For Brain Agents: Spawning with Plan Mode

# Spawn subagent in plan-first mode
gf new --task "Implement feature X" --plan-first --autonomous

This will:

1. Start the subagent with --permission-mode plan (read-only)
2. Subagent analyzes codebase and writes plan
3. Subagent sets status to awaiting_approval and exits
4. Brain reviews plan and runs gf approve or gf reject

For Brain Agents: Plan Review Protocol

When subagents are in awaiting_approval status:

1. Check status: gf status shows agents awaiting approval
2. Read plan: Plan is at .gitterflow/agents/{branch}/plan.md
3. Evaluate:
   • Does the approach align with overall architecture?
   • Are there conflicts with other agents' plans?
   • Is the scope appropriate?
4. Decide:
   • gf approve <branch> - Plan is good, start execution
   • gf reject <branch> --message "feedback" - Needs revision

For Sub-Agents: Plan Mode Instructions

If you were spawned with --plan-first, you are in plan mode:

1. Analyze only - You have read-only access (Read, Glob, Grep, WebSearch)
2. Write your plan to: .gitterflow/agents/{your-branch}/plan.md
3. Update status: Run gf status --write "awaiting_approval"
4. Exit - Do NOT implement anything yet

Plan file format:

# Implementation Plan: {task summary}

## Analysis
- Examined files: [list]
- Key findings: [summary]

## Approach
1. Step one
2. Step two

## Files to Modify
| File | Changes |
|------|---------|
| src/foo.ts | Add new function |

## Files to Create
- src/new-feature.ts - Main implementation

## Risks and Considerations
- Risk 1: mitigation

## Questions for Brain (if any)
- Should we use approach A or B?

Plan Approval Commands (Placeholder)

# Approve a plan and start execution phase
gf approve <branch>
gf approve <branch> --message "Looks good, proceed"

# Reject a plan with feedback
gf reject <branch> --message "Use exponential backoff instead"

Important Notes

• Sub-agents merge to your current branch (the branch you were on when spawning)
• Each sub-agent is completely independent - they cannot communicate with each other
• Monitor gf status to track progress of all agents
• Keep tasks independent to avoid merge conflicts
• Brain agents should handle ALL merges - sub-agents should only use gf ready
• Plan mode prevents wasted work by validating approach before implementation