Table of Contents

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 execution worktrees
  • Reduced merge conflicts

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 action implement WP01
cd <workspace path printed by the command>
# Agent A works here

Terminal 2: Agent B on WP02

spec-kitty agent action implement WP02
cd <workspace path printed by the command>
# Agent B works here simultaneously

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

Handling Dependencies Through Execution Lanes

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

spec-kitty implement WP02

Expected output (abridged):

OK Created workspace: .worktrees/###-feature-lane-b

Git Worktrees, Briefly

Each execution lane is a Git worktree on its own branch. Sequential WPs may reuse the same lane workspace, while independent WPs run in parallel in separate lane worktrees. For details, see Execution Workspace Model 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

  • "lanes.json is required": Run task finalization before implementation.
  • Worktree already exists: Run git worktree list and reuse the existing folder.
  • Agent edits the wrong WP: Stop and switch to the workspace path printed for the correct WP before continuing.

What's Next?

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

Reference Documentation

Learn More

Edit this page