Context Branch Methodology

This skill provides knowledge about the context branch methodology - a pattern for separating AI assistant configuration from project source code using git worktrees.

The Problem

When using AI coding assistants like Claude Code, projects accumulate:

• CLAUDE.md

  files with instructions

• .claude/

  directories with settings, commands, agents
• Custom hooks and configurations

These files:

1. Clutter project history with AI-specific commits
2. Mix tooling concerns with business logic
3. Create noise in code reviews
4. May contain sensitive prompts or configurations

The Solution

Use two independent git histories in the same repository:

Branch Structure

context

main

master

feature/*

Directory Layout

bare-repo/
└── root/
    ├── context/           # context branch worktree
    │   ├── CLAUDE.md      # AI instructions
    │   ├── .claude/       # Commands, agents, skills
    │   ├── .gitignore     # Contains: worktree/**/
    │   └── worktree/      # All code worktrees here
    │       ├── feature/
    │       │   └── my-feature/  # Feature branch worktree
    │       └── fix/
    │           └── bug-123/     # Bugfix branch worktree
    └── main/              # main/master branch (direct access, read-only)

Key Insight

The

context

.gitignore

worktree/**/

• Nested worktrees are invisible to context commits
• AI config and code remain in separate histories
• Claude Code runs from

  context/

  , sees both contexts

Detecting the Default Branch

Repositories may use either

main

master

# Method 1: From remote HEAD (most reliable if remote exists)
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

# Method 2: Check which branch exists locally
git branch -l main master 2>/dev/null | head -1 | tr -d '* '

# Method 3: Combined approach
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || git branch -l main master 2>/dev/null | head -1 | tr -d '* ')

Workflow

Creating a New Feature

# From the context worktree
cd root/context

# Detect default branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# Create feature worktree from default branch
git worktree add -b feature/my-feature worktree/feature/my-feature $DEFAULT_BRANCH

# Work in the feature
cd worktree/feature/my-feature
# ... make changes ...

# Commit and push
git add . && git commit -m "feat: add feature"
git push -u origin feature/my-feature

# Create PR targeting default branch
gh pr create --base $DEFAULT_BRANCH

Updating AI Configuration

# From context worktree (root/context)
# Edit CLAUDE.md or .claude/ files
git add .
git commit -m "context: update AI instructions"
git push origin context

Rules

1. Never edit

   root/main/

   or

   root/master/

   directly - always use a worktree
2. All code worktrees inside

   worktree/

   - maintains the separation
3. Feature branches from default branch - not from

   context

4. Context branch is orphan - no shared history with main/master
5. PRs target default branch - context changes stay on context branch

Benefits

• Clean project history (no AI config commits)
• Separate concerns (tooling vs code)
• Team flexibility (share context or keep personal)
• Easy experimentation (modify AI config without affecting code)

Common Questions

Q: How does Claude Code see both contexts? A: Claude runs from the

context/

worktree/

Q: Can I have multiple context branches? A: Yes! You could have

context-personal

context-team

Q: What if I need different AI config per feature? A: Each worktree can have its own

.claude/

Q: How do I migrate an existing repo? A: Use the

/context-init

worktree-manager

Q: Does it work with both main and master? A: Yes! The commands auto-detect the default branch. You can also explicitly specify the base branch as an argument.