Parallel Task Isolation Workflow

Version: 1.0.0 Status: Production Last Updated: 2025-12-18 Category: DevOps / Multi-Agent Orchestration

Overview

This workflow defines the process for executing multiple tasks in parallel using isolated git worktrees. Each agent operates in a separate working directory, preventing file conflicts while sharing repository history.

Quick Reference

Component	Type	Purpose
`/create-worktree`	Command	Create single isolated worktree
`/parallel-tasks`	Command	Execute multiple tasks concurrently
`git-workflow-orchestrator`	Agent	Orchestrate multi-agent workflows
`task_isolation.py`	Skill Module	Core worktree management logic

Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                    PARALLEL TASK ISOLATION                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  PHASE 1: TASK DEFINITION                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ User defines tasks:                                       │   │
│  │  • "Security audit"                                       │   │
│  │  • "Performance optimization"                             │   │
│  │  • "API documentation"                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  PHASE 2: WORKTREE CREATION                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ TaskIsolationManager creates worktrees:                   │   │
│  │                                                           │   │
│  │  Main Repo (./)                                          │   │
│  │  ├── .coditect/worktrees/                                │   │
│  │  │   ├── security-audit-abc123/   [Agent 1]              │   │
│  │  │   ├── perf-opt-def456/         [Agent 2]              │   │
│  │  │   └── api-docs-ghi789/         [Agent 3]              │   │
│  │  └── [main working tree]                                 │   │
│  └──────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  PHASE 3: PARALLEL EXECUTION                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                                                           │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐         │   │
│  │  │  Agent 1   │  │  Agent 2   │  │  Agent 3   │         │   │
│  │  │  security  │  │  perf      │  │  docs      │         │   │
│  │  │  specialist│  │  profiler  │  │  writer    │         │   │
│  │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘         │   │
│  │        │               │               │                 │   │
│  │        ▼               ▼               ▼                 │   │
│  │  [Isolated Work] [Isolated Work] [Isolated Work]        │   │
│  │        │               │               │                 │   │
│  │        ▼               ▼               ▼                 │   │
│  │  [Commit]        [Commit]        [Commit]               │   │
│  │                                                           │   │
│  └──────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  PHASE 4: MERGE & CLEANUP                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ For each completed task:                                  │   │
│  │  1. Review changes                                        │   │
│  │  2. Merge to target branch (squash optional)              │   │
│  │  3. Delete worktree and branch                            │   │
│  │  4. Update task status to MERGED                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Task Lifecycle States

┌─────────┐     ┌─────────┐     ┌───────────┐     ┌────────┐
│ PENDING │ ──► │ RUNNING │ ──► │ COMPLETED │ ──► │ MERGED │
└─────────┘     └─────────┘     └───────────┘     └────────┘
                    │
                    ▼
               ┌────────┐     ┌───────────┐
               │ FAILED │ ──► │ DISCARDED │
               └────────┘     └───────────┘

State	Description	Next Actions
`PENDING`	Worktree created, agent not started	Start agent
`RUNNING`	Agent actively working	Monitor progress
`COMPLETED`	Work finished successfully	Review and merge
`MERGED`	Changes integrated to target	Cleanup worktree
`FAILED`	Task encountered errors	Debug or discard
`DISCARDED`	Task abandoned	Cleanup worktree

Detailed Process

Phase 1: Task Definition

Input: User provides task descriptions

Methods:

# Method 1: Command line
/parallel-tasks "Task 1" "Task 2" "Task 3"

# Method 2: With agent assignment
/parallel-tasks "Security audit:security-specialist" "Perf test:performance-profiler"

# Method 3: From file
/parallel-tasks --from tasks.txt

Task file format (tasks.txt):

# One task per line, optional agent after colon
Add user authentication
Fix XSS vulnerability:security-specialist
Update API documentation:documentation-generation
# Comments are ignored

Phase 2: Worktree Creation

Process:

Parse task descriptions
Generate branch names from descriptions
Create git worktrees in .coditect/worktrees/
Initialize task state files

Code:

from skills.git_workflow_automation.core.task_isolation import TaskIsolationManager

manager = TaskIsolationManager()

# Create isolated environment
task = manager.create_task_environment(
    task_description="Implement user authentication",
    base_branch="main",
    metadata={"priority": "high"},
    agent_name="security-specialist"
)

# Result:
# - Worktree: .coditect/worktrees/impl-user-auth-abc123/
# - Branch: task/impl-user-auth-abc123
# - State: .coditect/worktrees/impl-user-auth-abc123/task_state.json

Verification:

# List all worktrees
git worktree list

# Check task state
cat .coditect/worktrees/*/task_state.json

Phase 3: Parallel Execution

Process:

Launch agent for each worktree
Agent works exclusively in isolated directory
Agent commits changes with conventional format
Agent updates task status to COMPLETED

Agent Launch Pattern:

# Launch multiple agents in parallel
for task in tasks:
    Task(
        subagent_type=task.metadata.get("agent", "general-purpose"),
        prompt=f"""
Execute task in isolated worktree:

Task: {task.task_description}
Worktree: {task.worktree_path}
Branch: {task.branch_name}

CRITICAL RULES:
1. Work ONLY in the worktree directory
2. Do NOT modify files outside the worktree
3. Commit all changes before completing
4. Update task status when done

When complete, commit with conventional format:
  git add -A
  git commit -m "feat(scope): description"
""",
        run_in_background=True
    )

Monitoring:

# Check task status
for task_id in active_tasks:
    task = manager.get_task(task_id)
    print(f"{task_id}: {task.status.value}")

Phase 4: Merge & Cleanup

Process:

Review completed task changes
Merge to target branch
Delete worktree and branch
Update status to MERGED

Merge Options:

# Standard merge
manager.merge_task(task_id, target_branch="main")

# Squash merge (recommended for clean history)
manager.merge_task(task_id, target_branch="main", squash=True)

# Merge without deleting branch
manager.merge_task(task_id, delete_branch=False)

Cleanup:

# Cleanup all completed/merged tasks
cleaned = manager.cleanup_completed()
print(f"Cleaned {cleaned} worktrees")

Usage Examples

Example 1: Basic Parallel Tasks

# Define and execute 3 tasks in parallel
/parallel-tasks "Add login page" "Implement API auth" "Write auth tests"

Result:

3 worktrees created
3 agents launched in parallel
Progress monitored automatically
Summary report generated

Example 2: Specialized Agents

/parallel-tasks \
  "Security vulnerability scan:security-specialist" \
  "Performance profiling:performance-profiler" \
  "API documentation:documentation-generation"

Result:

Each task gets specialized agent
Agents work concurrently without conflict
Expert-level output per domain

Example 3: Single Worktree for Complex Task

/create-worktree "Implement OAuth2 flow" --plan thoughts/shared/plans/oauth.md --agent backend-development

Result:

Single isolated worktree created
Plan file accessible in worktree
Backend agent launched with plan context

Example 4: Python API Direct Usage

from skills.git_workflow_automation.core.task_isolation import TaskIsolationManager, TaskStatus

manager = TaskIsolationManager()

# Create tasks
tasks = [
    manager.create_task_environment("Implement feature A"),
    manager.create_task_environment("Implement feature B"),
]

# Work in tasks...
# (Each in isolated worktree)

# Commit changes
for task in tasks:
    manager.commit_task_changes(
        task.task_id,
        message="Implement feature",
        commit_type="feat"
    )
    task.status = TaskStatus.COMPLETED

# Merge all
for task in tasks:
    manager.merge_task(task.task_id, squash=True)

# Cleanup
manager.cleanup_completed()

Error Handling

Error	Cause	Resolution
`Worktree already exists`	Task ID collision	Auto-generates unique suffix
`Branch already exists`	Previous task not cleaned up	Use `--force` or cleanup first
`Merge conflict`	Parallel changes to same file	Manual resolution required
`Agent failed`	Task error	Check logs, retry or discard

Recovery Pattern:

try:
    manager.merge_task(task_id)
except MergeConflictError:
    # Manual intervention required
    print(f"Conflict in {task_id}, resolve manually")
    print(f"  cd {task.worktree_path}")
    print(f"  git status")

Best Practices

DO:

Use specialized agents for domain-specific tasks
Set reasonable concurrency limits (default: 5)
Review changes before merging
Cleanup completed worktrees regularly
Use squash merge for clean history

DON'T:

Assign overlapping file changes to parallel tasks
Leave stale worktrees indefinitely
Force push without understanding conflicts
Ignore failed task status

Commands

/create-worktree - Create single worktree
/parallel-tasks - Multi-task parallel execution
/git-sync - Repository synchronization

Agents

git-workflow-orchestrator - Orchestration coordinator
security-specialist - Security audits
performance-profiler - Performance analysis
documentation-generation - Doc generation

Skills

git-workflow-automation - Core git patterns
multi-agent-workflow - Agent coordination
production-patterns - Error handling

Metrics & Monitoring

Metric	Target	Description
Worktree creation	<2s	Time to create isolated environment
Agent startup	<5s	Time to launch specialized agent
Task completion	Variable	Depends on task complexity
Merge success rate	>95%	Tasks merged without conflict
Cleanup efficiency	100%	All completed tasks cleaned

Last Updated: 2025-12-18 Owner: CODITECT Core Team Status: Production Ready

Overview​

Quick Reference​

Workflow Diagram​

Task Lifecycle States​

Detailed Process​

Phase 1: Task Definition​

Phase 2: Worktree Creation​

Phase 3: Parallel Execution​

Phase 4: Merge & Cleanup​

Usage Examples​

Example 1: Basic Parallel Tasks​

Example 2: Specialized Agents​

Example 3: Single Worktree for Complex Task​

Example 4: Python API Direct Usage​

Error Handling​

Best Practices​

DO:​

DON'T:​

Related Components​

Commands​

Agents​

Skills​

Metrics & Monitoring​

Overview

Quick Reference

Workflow Diagram

Task Lifecycle States

Detailed Process

Phase 1: Task Definition

Phase 2: Worktree Creation

Phase 3: Parallel Execution

Phase 4: Merge & Cleanup

Usage Examples

Example 1: Basic Parallel Tasks

Example 2: Specialized Agents

Example 3: Single Worktree for Complex Task

Example 4: Python API Direct Usage

Error Handling

Best Practices

DO:

DON'T:

Related Components

Commands

Agents

Skills

Metrics & Monitoring