spec-kitty

Workspace-per-Work-Package Explained

This document explains the “why” behind the workspace-per-work-package model. For step-by-step instructions, see the how-to guides. For an introduction, see the tutorials.

Overview

Spec Kitty 0.11.0 introduces the workspace-per-work-package model to enable parallel multi-agent development. Instead of creating one worktree per feature where all work packages share the same workspace, each work package now gets its own isolated worktree.

Key Change: One git worktree per work package (instead of one per feature)

For background on how git worktrees work, see Git Worktrees Explained.

Benefits

Recommended: Install jj for the best multi-agent experience. See Jujutsu Workflow Tutorial.

Workflow Comparison

Old Model (0.10.x)

# Planning creates worktree immediately
/spec-kitty.specify "My Feature"
→ Creates .worktrees/010-my-feature/
→ All WPs work in same worktree
→ Sequential development (one agent at a time)

# Implementation happens in shared worktree
cd .worktrees/010-my-feature/
/spec-kitty.implement  # Agent implements all WPs here

Limitations:

New Model (0.11.0+)

# Planning happens in main repository (NO worktree created)
/spec-kitty.specify "My Feature"
→ Creates kitty-specs/010-my-feature/spec.md in main
→ Commits to main
→ NO worktree created

/spec-kitty.plan
→ Creates plan.md in main
→ Commits to main

/spec-kitty.tasks
→ LLM creates tasks.md + tasks/WP01.md, tasks/WP02.md, ... in main

spec-kitty agent feature finalize-tasks
→ Parses dependencies from tasks.md
→ Generates dependency graph in WP frontmatter
→ Validates dependencies (cycle detection)
→ Commits all to main

# Implementation creates worktrees on-demand (one per WP)
spec-kitty implement WP01
→ Creates .worktrees/010-my-feature-WP01/
→ Branches from main
→ Agent A implements WP01

spec-kitty implement WP02 --base WP01
→ Creates .worktrees/010-my-feature-WP02/
→ Branches from WP01's branch
→ Agent B implements WP02 (in parallel!)

spec-kitty implement WP03
→ Creates .worktrees/010-my-feature-WP03/
→ Branches from main (independent WP)
→ Agent C implements WP03 (also in parallel!)

Benefits:

Workflow Step-by-Step

Phase 1: Planning (in main repository)

All planning commands run in your main repository. No worktrees are created during planning.

1. Specify the feature

/spec-kitty.specify "Add user authentication system"

Creates:

2. Plan the implementation

/spec-kitty.plan

Creates:

3. Generate work packages

/spec-kitty.tasks

LLM creates tasks.md and WP files:

4. Finalize and commit tasks

spec-kitty agent feature finalize-tasks

Each WP file then includes dependency information in frontmatter:

---
work_package_id: "WP02"
title: "API Endpoints"
dependencies: ["WP01"]  # WP02 depends on WP01
lane: "planned"
---

Phase 2: Implementation (in separate worktrees)

Now agents create worktrees on-demand for each WP they implement.

1. Implement WP01 (foundation)

spec-kitty implement WP01

Creates:

Agent A works in this worktree, commits to the WP01 branch.

2. Implement WP02 (depends on WP01)

spec-kitty implement WP02 --base WP01

Creates:

Agent B works here in parallel with Agent A (different worktrees).

3. Implement WP03 (independent)

spec-kitty implement WP03

Creates:

Agent C works here in parallel with A and B.

Phase 3: Review and Merge

1. Review completed WPs

/spec-kitty.review WP01

Moves WP01 from doing → for_review lane. If WP02 depends on WP01, displays warning:

⚠️ WP02 depends on WP01
If review feedback requires changes, WP02 will need rebase

2. Merge completed WPs

# Run from any WP worktree for the feature
cd .worktrees/011-user-authentication-system-WP01/
spec-kitty merge

Merges all completed WP branches to main, removes worktrees.

Dependency Syntax

Declaring Dependencies

Dependencies are declared in each WP’s frontmatter using YAML list syntax:

---
work_package_id: "WP02"
title: "Build API"
dependencies: ["WP01"]  # This WP depends on WP01
---

Multiple Dependencies

dependencies: ["WP01", "WP03"]  # Depends on both WP01 and WP03

Git limitation: Git can only branch from ONE base commit. If a WP has multiple dependencies, use --base for the primary dependency and manually merge the others.

spec-kitty implement WP04 --base WP02  # Branches from WP02
cd .worktrees/011-feature-WP04/
git merge 011-feature-WP03  # Manually merge WP03

No Dependencies

dependencies: []  # Independent WP, branches from main

How Dependencies Work

At implementation time:

During review cycles:

Validation Rules

Dependencies are validated during spec-kitty agent feature finalize-tasks:

Invalid dependency examples:

dependencies: ["WP1"]    # Invalid: must be WP##
dependencies: ["WP99"]   # Invalid: WP99 doesn't exist
dependencies: ["WP02"]   # Invalid in WP02.md (self-dependency)

Common Dependency Patterns

Pattern 1: Linear Chain

Sequential work where each WP builds on the previous one.

WP01 → WP02 → WP03 → WP04

Example: Authentication feature

Implementation:

spec-kitty implement WP01
spec-kitty implement WP02 --base WP01
spec-kitty implement WP03 --base WP02
spec-kitty implement WP04 --base WP03

Parallelization: Limited (each WP must wait for previous one to complete)

Pattern 2: Fan-Out (Parallel Work)

One foundation WP with multiple independent WPs building on it.

        WP01
       /  |  \
    WP02 WP03 WP04

Example: E-commerce platform

Implementation:

spec-kitty implement WP01

# After WP01 completes, run in parallel:
spec-kitty implement WP02 --base WP01  # Agent A
spec-kitty implement WP03 --base WP01  # Agent B
spec-kitty implement WP04 --base WP01  # Agent C

Parallelization: Excellent (3 agents work simultaneously after WP01 completes)

Pattern 3: Diamond (Multiple Dependencies)

Converging dependencies where one WP depends on multiple upstream WPs.

        WP01
       /    \
    WP02    WP03
       \    /
        WP04

Example: Integration layer

Implementation:

spec-kitty implement WP01

# Parallel:
spec-kitty implement WP02 --base WP01
spec-kitty implement WP03 --base WP01

# After both WP02 and WP03 complete:
spec-kitty implement WP04 --base WP03
cd .worktrees/###-feature-WP04/
git merge ###-feature-WP02  # Manually merge second dependency

Frontmatter:

# WP04.md
dependencies: ["WP02", "WP03"]

Note: Git limitation requires manual merge of second dependency. With jj, this is handled automatically via auto-rebase. See Jujutsu for Multi-Agent Development.

Pattern 4: Independent Modules

Multiple WPs with no dependencies (fully parallel).

WP01   WP02   WP03   WP04

Example: Documentation updates

Implementation:

# All run in parallel from main:
spec-kitty implement WP01  # Agent A
spec-kitty implement WP02  # Agent B
spec-kitty implement WP03  # Agent C
spec-kitty implement WP04  # Agent D

Parallelization: Maximum (4 agents work simultaneously)

Example Scenario: Building a Feature

Let’s walk through a real example using this workspace-per-WP model.

Scenario: Add OAuth Integration

Goal: Add OAuth login to an existing application.

Planning Phase:

  1. Create specification: 
    /spec-kitty.specify "OAuth Integration for User Login"
  2. Create plan: 
    /spec-kitty.plan
  3. Generate work packages: 
    /spec-kitty.tasks

Generated WPs with dependencies:

Implementation Phase:

# Wave 1: Foundation (parallel)
spec-kitty implement WP01  # Agent A: Database
spec-kitty implement WP02  # Agent B: Config
# Both agents work in parallel

# Wave 2: Backend (waits for Wave 1)
# After WP01 and WP02 complete:
spec-kitty implement WP03 --base WP02
cd .worktrees/012-oauth-integration-WP03/
git merge 012-oauth-integration-WP01  # Merge second dependency
# Agent C implements backend flow

# Wave 3: Frontend (waits for Wave 2)
spec-kitty implement WP04 --base WP03
# Agent D implements UI

# Wave 4: Tests (waits for Wave 3)
spec-kitty implement WP05 --base WP04
# Agent E writes tests

Timeline:

Troubleshooting

Error: “Legacy worktrees detected”

Symptom: During upgrade to 0.11.0:

❌ Cannot upgrade to 0.11.0
Legacy worktrees detected:
  - 008-unified-python-cli
  - 009-jujutsu-vcs

Cause: You have in-progress features using the old worktree model.

Solution:

  1. Complete or delete each legacy feature: 
    # Option A: Complete the feature
spec-kitty merge 008-unified-python-cli

# Option B: Delete the feature
git worktree remove .worktrees/008-unified-python-cli
git branch -D 008-unified-python-cli
  2. Verify clean state: 
    ls .worktrees/
# Should be empty or only show ###-feature-WP## patterns
  3. Retry upgrade: 
    pip install --upgrade spec-kitty-cli

Error: “Base workspace does not exist”

Symptom: When implementing dependent WP:

❌ Base workspace WP01 does not exist
Implement WP01 first or remove --base flag

Cause: You’re trying to implement WP02 with --base WP01, but WP01’s worktree hasn’t been created yet.

Solution:

  1. Implement the dependency first: 
    spec-kitty implement WP01
  2. Then implement dependent WP: 
    spec-kitty implement WP02 --base WP01

Error: “Circular dependency detected”

Symptom: During /spec-kitty.tasks generation:

❌ Circular dependency detected:
WP01 → WP02 → WP03 → WP01

Cause: Your dependency declarations create a cycle (WP01 depends on WP03, which depends on WP02, which depends on WP01).

Solution:

  1. Review your WP dependencies in tasks.md
  2. Identify the circular reference
  3. Remove or restructure dependencies to break the cycle
  4. Re-run /spec-kitty.tasks

Valid restructuring:

Before (invalid):
WP01 → WP02 → WP03 → WP01  ❌

After (valid):
WP01 → WP02 → WP03  ✅

Warning: “Dependent WPs need rebase”

Symptom: During review:

⚠️ WP02, WP03 depend on WP01
If review feedback requires changes, they'll need rebase

Cause: WP02 and WP03 are built on WP01’s branch. If WP01 changes during review, downstream WPs need updating.

Solution:

  1. If WP01 has no changes after review:
    • No action needed, continue as normal
  2. If WP01 has changes after review: 
    # Update WP02 to include WP01 changes
cd .worktrees/###-feature-WP02/
git rebase ###-feature-WP01

# Update WP03 to include WP01 changes
cd .worktrees/###-feature-WP03/
git rebase ###-feature-WP01

Issue: Multiple dependencies, git limitation

Symptom: WP has multiple dependencies, but --base only accepts one.

Cause: Git branches from a single commit. If WP04 depends on WP02 and WP03, you must choose one as base.

Solution:

# Use primary dependency as base
spec-kitty implement WP04 --base WP03

# Manually merge secondary dependency
cd .worktrees/###-feature-WP04/
git merge ###-feature-WP02

Future: jj integration will automate multi-parent merging.

Migration from Legacy Model

See Upgrading to 0.11.0 for detailed migration guide.

Quick checklist:

See Also

Migration and Reference

Try It

How-To Guides

Reference

This site is open source. Improve this page.