How the AIOX Worktree Manager Provides Branch Isolation in Epic 1

The AIOX Worktree Manager guarantees branch isolation by automatically provisioning dedicated Git worktrees and uniquely prefixed branches (auto-claude/<storyId>) for every story, ensuring complete separation from the main repository and concurrent development streams.

The SynkraAI/aiox-core repository implements Epic 1 through the Worktree Manager, a specialized component that solves concurrent development conflicts by binding each story to its own isolated Git branch and working directory. This architecture prevents cross-contamination between stories while maintaining a clean main branch history.

Core Branch Isolation Mechanisms

Per-Story Branch Naming with Configurable Prefixes

In .aiox-core/infrastructure/scripts/worktree-manager.js, the getBranchName(storyId) function (lines 13-15) constructs isolated branch identifiers by concatenating the configurable branchPrefix (defaulting to auto-claude/) with the story identifier. This naming convention ensures that every story operates on a distinct branch namespace, physically separating commits from the main branch and other stories.

Isolated Worktree Creation

The create(storyId) method (lines 24-48) enforces isolation at the filesystem level. It first validates against the maxWorktrees limit to prevent resource exhaustion, then executes:

git worktree add <repo>/.aiox/worktrees/<storyId> -b auto-claude/<storyId>

This command simultaneously creates a new working directory under .aiox/worktrees/<storyId> and a fresh branch with the prefixed name, establishing a sandboxed environment where changes remain invisible to the main repository.

Filtered Worktree Discovery

Isolation requires that the manager only recognizes its own worktrees. The list() method (lines 16-20) parses git worktree list --porcelain output and filters entries to return only those branches starting with the configured branchPrefix. This prevents the manager from interfering with manually created worktrees or branches outside the AIOX ecosystem.

Complete Cleanup of Branches and Worktrees

The remove(storyId) implementation (lines 63-84) terminates isolation cleanly by executing git worktree remove followed by git branch -d (or -D when forced). This dual deletion ensures that neither the working directory nor the isolated branch persists after story completion, preventing branch clutter and repository bloat.

Configuration and Resource Limits

The Worktree Manager preserves isolation integrity through configurable guards defined in the options (lines 18-22). The maxWorktrees setting caps concurrent isolated environments, while staleDays identifies inactive worktrees for automatic cleanup via cleanupStale() (lines 34-55). These limits prevent resource exhaustion while maintaining strict separation for active stories.

Practical Implementation Examples

Creating an Isolated Story Worktree

const WorktreeManager = require('.aiox-core/infrastructure/scripts/worktree-manager');

async function startStory(storyId) {
  const manager = new WorktreeManager(process.cwd());
  await manager.create(storyId);  // Creates .aiox/worktrees/STORY-42
  console.log(`Isolated worktree for ${storyId} ready`);
}

startStory('STORY-42');

This invocation triggers the branch isolation protocol, creating both the directory .aiox/worktrees/STORY-42 and the branch auto-claude/STORY-42 automatically.

Listing Isolated Worktrees Only

async function showIsolatedWorktrees() {
  const mgr = new WorktreeManager('.');
  const list = await mgr.list();  // Filters to branchPrefix 'auto-claude/'
  console.log(mgr.formatList(list));
}

showIsolatedWorktrees();

The output displays only manager-owned worktrees, confirming isolation boundaries:

📁 Active Worktrees (2/10)
──────────────────────────────────────────────────
🟡 STORY-42   │ auto-claude/STORY-42 │ clean          │ 1h ago
🟢 STORY-99   │ auto-claude/STORY-99 │ 3 uncommitted │ 5m ago

Merging and Cleaning Up Isolated Branches

async function finalizeStory(storyId) {
  const mgr = new WorktreeManager('.');
  const result = await mgr.mergeToBase(storyId, { cleanup: true });
  console.log(result.success ? 'Merge succeeded' : 'Merge failed');
}

finalizeStory('STORY-42');

The mergeToBase() method integrates the isolated branch back into the base branch and, with cleanup: true, invokes remove() to eliminate both the worktree and the auto-claude/STORY-42 branch, completing the isolation lifecycle.

Related Components

Branch isolation extends beyond the core manager into supporting infrastructure:

• .aiox-core/infrastructure/scripts/story-worktree-hooks.js: Lazy-loads the Worktree Manager during story lifecycle events to maintain isolation boundaries during automated transitions.
• .aiox-core/infrastructure/scripts/project-status-loader.js: Consumes the filtered list() output to render isolation status in UI dashboards without exposing non-AIOX worktrees.
• tests/infrastructure/worktree-manager.test.js: Validates that branch prefixes are respected and isolation holds across concurrent operations.

Summary

• The AIOX Worktree Manager binds every story to a unique branch using the auto-claude/<storyId> naming convention implemented in getBranchName().
• Physical isolation occurs through git worktree add with the -b flag, creating dedicated directories under .aiox/worktrees/ that mirror isolated branch states.
• The manager maintains separation boundaries by filtering git worktree list results to only recognize branches matching the configurable prefix.
• Complete isolation teardown via remove() deletes both the working directory and the associated branch, ensuring no residual artifacts remain.
• Resource guards (maxWorktrees, staleDays) preserve isolation quality by preventing system overload while automatically retiring inactive environments.

Frequently Asked Questions

How does the Worktree Manager prevent branch name collisions between stories?

The manager eliminates collisions through the getBranchName() function in .aiox-core/infrastructure/scripts/worktree-manager.js (lines 13-15), which prefixes every branch with auto-claude/ followed by the unique story identifier. This namespace guarantees that auto-claude/STORY-42 and auto-claude/STORY-99 remain distinct, preventing cross-story interference.

Can the Worktree Manager interfere with manually created Git worktrees?

No. The list() method (lines 16-20) explicitly filters the output of git worktree list --porcelain to return only worktrees whose branches start with the configured branchPrefix. This ensures the manager only manipulates AIOX-generated worktrees, leaving manually created worktrees and branches completely untouched.

What happens to the isolated branch after a story is merged?

When mergeToBase() is called with cleanup: true, or when remove() is invoked directly (lines 63-84), the manager executes git worktree remove to delete the directory followed by git branch -d (or -D for forced deletion) to eliminate the auto-claude/<storyId> branch. This ensures complete cleanup of the isolated environment.

How does AIOX limit resource consumption while maintaining branch isolation?

The Worktree Manager implements configurable guards defined in the constructor options (lines 18-22). The maxWorktrees parameter caps the number of concurrent isolated environments, while staleDays triggers automatic cleanup via cleanupStale() (lines 34-55) to remove inactive worktrees and their branches, preventing repository bloat without compromising active story isolation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}