/worktree - Isolated Submodule Development

Create, manage, and orchestrate isolated worktrees for parallel submodule development with full Git, Docker, and Claude Code session isolation.

Usage

# Create isolated worktree for feature work
/worktree create <submodule> <branch>

# Create with Docker container
/worktree create <submodule> <branch> --container

# List all worktrees
/worktree list

# Get status overview
/worktree status

# Remove a worktree
/worktree remove <path>

# Run command across all worktrees
/worktree orchestrate "<command>"

# Enter a worktree (prints cd command)
/worktree enter <submodule> <branch>

System Prompt

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.

---

You are executing the CODITECT Worktree Manager for isolated submodule development.

Isolation Levels:

1. Git Worktrees - Parallel branches without checkout switching
2. Docker Containers - Separate runtime, dependencies, secrets
3. Claude Sessions - Scoped context per worktree

Benefits:

• Security: Isolated secrets and credentials per submodule
• Parallel: Multiple developers/agents work simultaneously
• Audit: Clear git history per submodule, no mixed commits
• Rollback: Revert one submodule without affecting others

Execute worktree command:

python3 scripts/worktree-manager.py $ARGS

Examples

Create Feature Worktree

/worktree create submodules/core/coditect-core feature/new-api

Creates isolated worktree at worktrees/submodules-core-coditect-core--feature-new-api/

Create with Container

/worktree create submodules/cloud/backend hotfix-auth --container

Creates worktree + Docker container with appropriate base image and ports.

List Worktrees

/worktree list

Shows all worktrees with status (exists, has changes, change count).

Status Overview

/worktree status

Shows summary: total submodules, worktrees, active, with changes.

Orchestrate Command

/worktree orchestrate "git pull origin main"
/worktree orchestrate "npm test" --submodules frontend,templates
/worktree orchestrate "cargo build" --branches main,develop

Run commands across multiple worktrees in parallel.

Remove Worktree

/worktree remove worktrees/submodules-core-coditect-core--feature-new-api
/worktree remove <path> --force  # Remove even with uncommitted changes

Enter Worktree

cd $(python3 scripts/worktree-manager.py enter submodules/core/coditect-core feature/new-api)

Container Types

Submodule Type	Base Image	Ports
core	python:3.11-slim	8000
cloud	python:3.11-slim	8080, 8443
frontend	node:20-slim	3000, 5173
integrations	python:3.11-slim	9000
tools	python:3.11-slim	-
personas	python:3.11-slim	-
templates	node:20-slim	3000

Workflow

# 1. Create isolated worktree
/worktree create submodules/core/coditect-core feature/sprint-4

# 2. Enter the worktree
cd worktrees/submodules-core-coditect-core--feature-sprint-4

# 3. Work in isolation (Claude session auto-scoped)
# ... make changes ...

# 4. Commit and push
git add . && git commit -m "feat: Sprint 4 changes"
git push origin feature/sprint-4

# 5. Create PR or merge via orchestration
/worktree orchestrate "git merge main" --branches feature/sprint-4

# 6. Cleanup when done
/worktree remove worktrees/submodules-core-coditect-core--feature-sprint-4

Integration

• Doc Search - Worktrees can be registered as doc workspaces with --register
• Git Workflow - Works with /git-sync for cross-submodule coordination
• Session Memory - Context preserved per worktree via .worktree-info.json

---

Action Policy

<default_behavior> This command manages git worktrees. Provides:

• Create isolated development environments
• List and status all worktrees
• Orchestrate commands across worktrees
• Remove worktrees when done

Creates directories and modifies git configuration. </default_behavior>

After execution, verify: - Worktree created/removed successfully - Git state consistent - Container started (if --container) - Session isolation in place

Success Output

When worktree operation completes:

✅ COMMAND COMPLETE: /worktree
Action: <create|list|remove|orchestrate>
Submodule: <path>
Branch: <branch-name>
Location: <worktree-path>

Completion Checklist

Before marking complete:

• Worktree operation executed
• Git state verified
• Container ready (if applicable)
• Path accessible

Failure Indicators

This command has FAILED if:

• ❌ Submodule not found
• ❌ Branch doesn't exist
• ❌ Worktree creation failed
• ❌ Docker error (if --container)

When NOT to Use

Do NOT use when:

• Simple branch checkout needed (use git checkout)
• Not working with submodules
• Single-developer workflow

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Leave stale worktrees	Disk waste	Remove when done
Skip --force on dirty	Lose changes	Commit first
Ignore container logs	Debug harder	Check container status

Principles

This command embodies:

• #4 Separation of Concerns - Isolated development environments
• #3 Complete Execution - Full worktree setup

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Script: scripts/worktree-manager.py Config: .coditect/worktree-config.json Version: 1.0.0