Create Worktree

Create an isolated git worktree for parallel task execution.

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

# With task description
/create-worktree "Implement user authentication feature"

# With ticket ID (any system: ENG-123, PROJ-456, #789)
/create-worktree "ENG-456: Fix authentication bug"

# With plan file
/create-worktree "Add feature" --plan thoughts/shared/plans/feature.md

# With custom base branch
/create-worktree "Hotfix" --base production

# With agent assignment
/create-worktree "Security audit" --agent security-specialist

Arguments

$ARGUMENTS - Task Description (required)

Specify the task to create a worktree for:

• Simple: "Fix the login bug"
• With ticket: "ENG-456: Fix authentication bug" or "JIRA-123 Add feature"
• With plan: "Implement feature" (then use --plan flag)

Flags (optional)

Flag	Description	Default
--plan PATH	Path to plan file (relative)	None
--base BRANCH	Base branch to branch from	main
--agent NAME	Assign specific agent type	general-purpose
--prefix DIR	Worktree directory prefix	.coditect/worktrees

Process

1. Parse Input

Extract from $ARGUMENTS:

• Task description
• Ticket ID (if present: ENG-XXX, PROJ-XXX, #XXX, etc.)
• Generate branch name from description

2. Create Worktree

Use the TaskIsolationManager to create isolated worktree:

from skills.git_workflow_automation.core.task_isolation import TaskIsolationManager

manager = TaskIsolationManager()
task = manager.create_task_environment(
    task_description="$TASK_DESCRIPTION",
    base_branch="$BASE_BRANCH",
    metadata={"ticket": "$TICKET_ID", "plan": "$PLAN_PATH"},
    agent_name="$AGENT_NAME"
)

Or via CLI:

# Using Python directly
python3 -c "
from skills.git_workflow_automation.core.task_isolation import TaskIsolationManager
manager = TaskIsolationManager()
task = manager.create_task_environment('$TASK_DESCRIPTION', base_branch='$BASE_BRANCH')
print(f'Worktree created: {task.worktree_path}')
print(f'Branch: {task.branch_name}')
print(f'Task ID: {task.task_id}')
"

3. Confirm with User

Display confirmation:

Worktree created for parallel task execution:

  Task:        $TASK_DESCRIPTION
  Worktree:    .coditect/worktrees/$TASK_ID/
  Branch:      task/$TASK_ID
  Base:        main
  Status:      RUNNING
  Plan:        $PLAN_PATH (if specified)
  Agent:       $AGENT_NAME

To work in this worktree:
  cd .coditect/worktrees/$TASK_ID

To commit changes:
  python3 -c "from skills... manager.commit_task_changes('$TASK_ID', 'feat: description')"

To merge back to main:
  python3 -c "from skills... manager.merge_task('$TASK_ID')"

To list all active worktrees:
  python3 -c "from skills... print(manager.list_tasks())"

4. Optional: Launch Agent Session

If --agent specified, launch agent in worktree:

# Using Task tool with working directory
Task(
    subagent_type="$AGENT_NAME",
    prompt="Implement: $TASK_DESCRIPTION. Work in worktree at .coditect/worktrees/$TASK_ID"
)

Examples

Simple Task

/create-worktree "Add dark mode to settings page"

Creates:

• Branch: task/add-dark-mode-to-settings
• Worktree: .coditect/worktrees/add-dark-mode-to-settings-abc123/

With Ticket

/create-worktree "ENG-456: Fix authentication timeout"

Creates:

• Branch: task/eng-456-fix-auth-timeout
• Worktree: .coditect/worktrees/eng-456-fix-auth-timeout-def456/
• Metadata includes ticket: ENG-456

With Plan File

/create-worktree "Implement OAuth" --plan thoughts/shared/plans/oauth-implementation.md

Creates worktree with plan file symlinked/accessible.

With Specific Agent

/create-worktree "Security vulnerability audit" --agent security-specialist

Creates worktree and launches security-specialist agent in that directory.

Integration with TaskIsolationManager

This command uses the core TaskIsolationManager from skills/git-workflow-automation/core/task_isolation.py:

# Task lifecycle
manager = TaskIsolationManager()

# Create isolated environment
task = manager.create_task_environment("Fix bug", metadata={"priority": "high"})

# Work in worktree...
# Changes are isolated to task.worktree_path

# Commit changes
commit_hash = manager.commit_task_changes(task.task_id, "fix: resolve bug")

# Merge back
success = manager.merge_task(task.task_id, target_branch="main", squash=True)

# Cleanup completed worktrees
manager.cleanup_completed()

Task States

State	Description
PENDING	Task created, not started
RUNNING	Active work in progress
COMPLETED	Task finished, ready to merge
MERGED	Successfully merged to target
FAILED	Task failed or blocked
DISCARDED	Task abandoned

Related Commands

• /parallel-tasks - Execute multiple worktree tasks concurrently
• /git-sync - Synchronize git state across repos
• /implement-plan - Execute implementation plan in worktree

Related Skills

• git-workflow-automation - Core git workflow patterns
• multi-agent-workflow - Multi-agent coordination

---

Action Policy

<default_behavior> This command creates worktrees by default when user intent is clear. Proceeds with:

• Git worktree creation
• Branch creation from base
• Directory setup
• State file initialization

Provides confirmation after worktree creation. </default_behavior>

After execution, verify: - Worktree directory exists - Branch created and checked out - State file written (task_state.json) - Base branch tracking set up

Success Output

When worktree creation completes:

✅ COMMAND COMPLETE: /create-worktree
Task: <task-description>
Worktree: .coditect/worktrees/<task-id>/
Branch: task/<task-id>
Base: <base-branch>
Status: RUNNING

Completion Checklist

Before marking complete:

• Worktree directory created
• Branch created
• State file initialized
• Instructions provided

Failure Indicators

This command has FAILED if:

• ❌ Git repository not found
• ❌ Worktree creation failed
• ❌ Branch already exists
• ❌ Directory not created

When NOT to Use

Do NOT use when:

• Simple change (main branch sufficient)
• Not a git repository
• Worktree limit reached

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Too many worktrees	Resource drain	Cleanup completed
No task description	Unclear purpose	Always describe
Forget to merge	Lost work	Complete lifecycle

Principles

This command embodies:

• #1 Self-Provisioning - Auto-setup worktree
• #3 Complete Execution - Full worktree creation
• #6 Clear, Understandable - Clear instructions

Full Standard: CODITECT-STANDARD-AUTOMATION.md