Skip to content

WORKFLOW.md

Latest commit

 

History

History
163 lines (110 loc) · 3.46 KB

WORKFLOW.md

File metadata and controls

163 lines (110 loc) · 3.46 KB
Raw

Agent Workflow Guide

End-to-end guide for running parallel Claude Code agents with stacked PRs.

1. Install amp

Prerequisites:

  • Go
  • git
  • tmux
  • gh CLI with the gh-stack extension
# Install gh-stack
gh extension install timrogers/gh-stack

# Clone and install amp
git clone https://github.com/mdawess/amp
cd amp
make install

Make sure ~/go/bin is in your PATH:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify: amp --help

2. Setup

Each feature gets its own tmux session and git worktree. Worktrees are created as sibling directories to your repo.

# Start tmux (or attach to an existing server)
tmux new-session -s main

# Create a worktree + tmux session for a feature
amp worktree new <branch>
# e.g. amp worktree new 0-auth-base
# This creates the branch, a sibling worktree directory, and opens a new tmux session

For customer-specific work that branches off a non-main base:

git checkout ward
amp worktree new 0-ward-feature

Each agent should get its own session so they run fully isolated.

3. Navigation

Action Keybinding
Switch to previous session Option+p
Switch window up Option+k
Switch window down Option+j
New tmux window Alt+t

Tmux prefix is Ctrl+a.

4. Running Claude Agents

Open the worktree session for the feature you want to work on, then launch Claude Code:

claude

Claude will pick up the global CLAUDE.md guidelines automatically, including the stacked PR workflow.

For parallel features, create a separate worktree and session per feature, then run claude in each:

# Terminal 1
amp worktree new 0-feature-a
# navigate to that session, run: claude

# Terminal 2
amp worktree new 0-feature-b
# navigate to that session, run: claude

Each agent works in isolation and will create its own local stack.

5. Stacked PRs

Agents manage the stack themselves, but here's what's happening under the hood and how to interact with it.

How stacks work

Each stack is scoped to one feature. Layers build on each other:

main
 └── 0-auth-base       ← foundational layer (types, schema)
      └── 1-auth-middleware  ← depends on base
           └── 2-auth-routes ← depends on middleware

Agent commands (handled automatically)

amp stack init 0-<feature>   # start the stack
amp stack add 1-<next>       # add a layer
amp stack ls                 # inspect the stack

Human commands (after agent is done)

amp stack push     # push all branches to remote
amp stack submit   # open PRs for the full stack

Agents never push or open PRs — that's always a human step.

6. Human-in-the-Loop (HITL)

Agents are fully autonomous within their session but require human action at two points:

Review

When an agent finishes, it outputs a concise summary of what changed. Review this summary, then inspect the stack:

amp stack ls          # see the layers
git log --oneline     # review commits per branch
git diff main...HEAD  # diff against base

Push & submit

Once you're satisfied:

amp stack push      # push all branches
amp stack submit    # open PRs (one per layer, stacked)

Review each PR in order from bottom to top before merging. Merge the base layer first, then each layer above it in sequence.

Cleanup

amp worktree rm <branch>   # remove worktree and session when done