Git Workflow Strategies

The core workflow (Interview -> Create Spec -> Create Work Items -> Implement) runs the same regardless of how you manage branches. The plain workflow is platform-agnostic; use the paired -flutter skills for Flutter/Dart work. This guide covers the two git strategies for isolating that work, and when to pick each one.

Strategy 1: Branch-based (serial)

The default for most tasks. You create a feature branch, run the full workflow, ship, and return to main.

git switch -c feature/add-persistence
# Interview -> Create Spec -> Create Work Items -> Implement
/act-git-push-make-pr
# Merge PR on GitHub
/act-git-switch-main-pull
git branch -d feature/add-persistence

Best for	One feature at a time
Setup	None — standard git
Context switches	Stash or commit before switching
CLI sessions	One

Strategy 2: Worktree-based (parallel)

Each feature gets its own directory, branch, and AI client session. No stashing, no context switching — just open another terminal.

# Create worktrees/add-persistence/ — a sibling directory with its own branch
/act-git-worktree create add-persistence
# Open a new terminal at the worktree directory
cd worktrees/add-persistence
claude
# Interview -> Create Spec -> Create Work Items -> Implement
/act-git-push-make-pr
# Merge PR on GitHub, then clean up
/act-git-worktree delete add-persistence

Best for	Parallel features or comparing approaches
Setup	ACT Pro (/act-git-worktree)
Context switches	Switch terminals — no stashing needed
CLI sessions	One per worktree

Worktrees share git history

All worktrees point to the same .git directory. Commits, branches, and tags are visible everywhere — only the working directory and checked-out branch differ. See the Git Worktrees playbook for detailed setup steps.

When to choose which

Factor	Branch	Worktree
One feature at a time	Yes	Overkill
Multiple features in parallel	Painful (stash/switch)	Yes
Comparing two models on the same feature	No	Yes — one worktree per model
Quick hotfix while mid-feature	Stash + switch	Create a second worktree
Disk space constrained	Lighter	Each worktree is a full checkout

Hybrid model comparison workflow

When you want to evaluate two different models (e.g., Opus vs GPT) on the same feature, you can mix branch-based and worktree-based isolation depending on the artifact you are comparing.

For Spec creation, staying on a single branch is often simpler because you are only producing a small number of markdown files in the same folder:

1. Generate the initial Spec with one model and save it as [feature-name]-opus-spec.md
2. Generate the same Spec with another model and save it as [feature-name]-gpt-spec.md
3. Start a fresh session and ask Opus to review the differences and pick the stronger Spec
4. Start another fresh session and ask GPT to review the differences and pick the stronger Spec

This gives you two independent proposals plus two review passes, while keeping everything easy to compare side by side in one directory.

Once you move from Work Item creation into implementation, worktrees become more useful because each model now needs its own full working directory:

1. Create two worktrees from the same starting point
2. Open separate AI client sessions, configured with Opus/GPT respectively
3. Run the same Spec and Work Item through /act-implement in both, or /act-implement-flutter for Flutter/Dart work
4. Compare both implementations across the same criteria such as code quality, test coverage, and approach; if you want an extra layer of analysis, also ask each model to review both implementations and explain which one is stronger
5. Keep the better result, delete the other worktree

In practice, a hybrid workflow works well: use one branch when comparing lightweight artifacts such as Specs and Work Items, then switch to worktrees when comparing full implementations that would otherwise conflict in the same checkout.

The full cycle

Whichever strategy you choose, the end-to-end cycle is broadly the same:

1. Isolate — create a branch or worktree
2. Build — run the core workflow (Interview -> Create Spec -> Create Work Items -> Implement)
3. Ship — /act-git-push-make-pr to create a PR
4. Merge — review and merge on GitHub
5. Clean up — delete the branch or worktree, return to main

act-workflow-compound is a deprecated legacy skill with no current replacement.

Isolation can happen at different stages

You do not have to isolate work at the same point every time. For straightforward tasks, you may create the branch or worktree before writing the Spec and keep the whole workflow contained there. For model comparison or other exploratory planning, it can be easier to stay on one branch through Spec generation, then create worktrees only when you are ready to compare implementations.

Ultimately, there is no one-size-fits-all workflow. ACT is designed so you stay in control of when worktrees are created, with the convenient /act-git-worktree skill available when you want it, rather than making worktree creation a mandatory step inside the core workflow skills.

Related

• Workflow Overview — the Interview -> Create Spec -> Create Work Items -> Implement pipeline
• Git Skills — commit, push, and PR automation