spec-kitty

Multi-Agent Parallel Development

Divio type: Tutorial

Learn how to coordinate multiple AI agents working on different work packages simultaneously.

Time: ~1 hour Prerequisites: Completed Your First Feature

Why Parallel Development?

• Shorter delivery time by splitting work packages
• Clear isolation with dedicated worktrees
• Reduced merge conflicts

With jujutsu (jj): Multiple agents can work on dependent work packages simultaneously. When one WP changes, others auto-rebase. No manual coordination needed. See Why Jujutsu for Multi-Agent.

Understanding Work Package Dependencies

Common dependency patterns:

• Linear: WP02 depends on WP01
• Fan-out: WP01 unblocks multiple packages
• Diamond: WP02 and WP03 depend on WP01, then WP04 depends on both

Dependencies are declared in each WP frontmatter.

Hands-On: Two Agents, Two WPs

Setup

Generate work packages for your feature.

In your agent:

/spec-kitty.tasks

Confirm two independent packages are lane: "planned".

Terminal 1: Agent A on WP01

spec-kitty agent workflow implement WP01
cd .worktrees/###-feature-WP01
# Agent A works here

Terminal 2: Agent B on WP02

spec-kitty agent workflow implement WP02
cd .worktrees/###-feature-WP02
# Agent B works here simultaneously

Each agent updates only their own worktree. Do not edit another agent’s worktree.

Handling Dependencies with –base

If WP02 depends on WP01, create WP02 from the WP01 base:

spec-kitty implement WP02 --base WP01

Expected output (abridged):

OK Created workspace: .worktrees/###-feature-WP02

Git Worktrees, Briefly

Each work package is a Git worktree on its own branch. This keeps changes isolated and lets agents work in parallel without merge conflicts. For details, see Workspace-per-WP and Git Worktrees.

Tips for Coordinating Agents

• Run spec-kitty agent tasks list-tasks to see current lanes.
• Use spec-kitty agent tasks add-history WP## --note "..." to share progress.
• Avoid overlapping file edits across WPs.

Troubleshooting

• “WP has dependencies”: Re-run with spec-kitty implement WP## --base WPXX.
• Worktree already exists: Run git worktree list and reuse the existing folder.
• Agent edits the wrong WP: Stop and switch to the correct worktree before continuing.

What’s Next?

You’ve completed the core tutorials. Explore how-to guides for specific tasks or explanations for deeper understanding.

Related How-To Guides

• Parallel Development - Run multiple agents simultaneously
• Handle Dependencies - Manage WP dependencies
• Implement a Work Package - Detailed implementation steps
• Use the Dashboard - Monitor progress in real time

Reference Documentation

• Agent Subcommands - Agent workflow commands
• CLI Commands - Full command reference
• File Structure - Worktree layout

Learn More

• Multi-Agent Orchestration - Coordination patterns
• Workspace-per-WP Model - Isolation strategy
• Git Worktrees - How worktrees work

This site is open source. Improve this page.