import DefinitionCard from "@site/src/components/DefinitionCard"

# Parallel Development Workflow

_Run independent tasks in separate working directories and integrate each result through normal review._

## Introduction

Parallel development cuts waiting time when tasks do not depend on each other. Each task gets its own branch and working directory, so edits and local build state never collide.

Running work in parallel only helps while review and merging keep up.

## Understanding the Workflow

A **workstream** is one bounded task with an owner, a workspace, and a clear way in.

**Workspace isolation** gives each workstream its own working files. [Git worktrees](/learn/concepts/git/git-worktrees) share refs and objects, so they keep edits apart but give you no security boundary.

Tasks are independent when you can build, review, and merge them in any order. Different file names are a hint, not proof: shared schemas, interfaces, generated output, and deploy order all tie tasks together.

Use a [stacked PR workflow](./stacked-pr) when one task must build on another.

## Applying It in Practice

Check each candidate task for:

- overlapping files or symbols
- shared database or API contracts
- common configuration and generated files
- required merge or deployment order
- enough review ownership

Create one worktree and branch per task:

```bash
git fetch origin
git worktree add -b task/password-reset ../repo-password-reset origin/main
git worktree add -b task/search-index ../repo-search-index origin/main
```

Give each owner a clear task contract and a file boundary. Settle any shared interface before work starts, so two people are not left to invent the same one apart.

Open a pull request as soon as one workstream is ready, then review and merge it without waiting for the rest. Bring the other branches up to date before they land:

```bash
git -C ../repo-search-index fetch origin
git -C ../repo-search-index rebase origin/main
```

Only rebase a branch when rewriting it is safe. If other people are building on its commits, merge `main` into it instead.

When conflicts show up, fix them in whichever branch merges next and re-run its tests against current `main`. Restarting an agent task is often cheaper than saving a small stale patch, but compare the old and new behavior before you throw anything away.

Remove finished worktrees through Git:

```bash
git worktree remove ../repo-search-index
git branch -d task/search-index
```

## Engineering Considerations

Start with two or three workstreams. Add more only while reviews stay quick and conflicts stay rare. There is no single right number, because task size and review capacity differ from team to team.

Separate working directories do not separate databases, ports, caches, or outside services, and [separate clones](/learn/concepts/git/git-worktrees-vs-clones) do not either. Give each concurrent test process its own resources wherever the app needs them.

Rebasing often is not a substitute for thinking about dependencies. It keeps you close to `main`, but a rebase with no text conflicts can still merge two behaviors that do not work together.

Feature flags let independent changes land before the feature is ready for users. They shift the coordination into runtime config, which then needs an owner, a cleanup plan, and testing in production.

## Scaling and Operations

Track each workstream's task, branch, workspace, owner, review state, and dependencies. Close dead work quickly and delete its workspace.

Watch how old the review queue gets and how often conflicts appear. Stop starting work once the queue grows faster than reviewers can clear it.

Automation should hand out unique branch names, directories, ports, and temporary resources, and clean them all up after a task fails or is interrupted. A [branch naming pattern](/docs/how-to/customizing-settings) keeps those names predictable, and [running coding agents in parallel](/learn/parallel-coding-agents) covers how the rest of that allocation works.

When parallel work stops paying off, pause new tasks, finish or close what is open, and redraw the dependency boundaries before you scale back up.

## Next Steps

- [What are Git Worktrees?](/learn/concepts/git/git-worktrees): learn how linked working directories share repository state
- [Stacked PR Workflow](./stacked-pr): handle dependent changes in order
- [AI Feature Development Workflow](/learn/workflows/ai/ai-feature-development): define tasks for coding agents
- [What is Agent Orchestration?](/learn/concepts/ai-engineering/agent-orchestration): coordinate several agent tasks