Worktree Structure Guide

Last Updated: 2026-02-06 Status: MANDATORY STANDARD

📂 Directory Structure

Location: /Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/.worktrees/

Structure: <project-name>/<branch-name>/ (NO date folders)

✅ Correct Structure

.worktrees/
├── agent-buildkit/
│   ├── feature-123-new-command/
│   └── chore-456-refactor/
├── platform-agents/
│   └── release-v0.1.x/
├── openstandardagents/
│   └── feature-validator-architecture/
├── api_normalization/
│   └── release-v0.1.x/
└── compliance-engine/
    └── feature-789-audit/

❌ DEPRECATED: Date-Based Structure

OLD (DO NOT USE):

.worktrees/
├── 2026-02-05/
│   ├── agent-buildkit/
│   └── platform-agents/
└── 2026-02-06/
    └── openstandardagents/

Problem: Date-based folders create confusion about which worktree is current.

🚀 Worktree Creation

Standard Workflow

# Define project
PROJECT="agent-buildkit"
BRANCH="123-feature-name"
GITLAB_URL="https://gitlab.com/blueflyio/agent-platform/${PROJECT}.git"
WORKTREE_PATH="${HOME}/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/.worktrees/${PROJECT}/${BRANCH}"

# Create worktree
mkdir -p "${WORKTREE_PATH%/*}"
git clone "${GITLAB_URL}" "${WORKTREE_PATH}"
cd "${WORKTREE_PATH}"
git checkout "${BRANCH}"

For Existing Local Repo

# If you already have a local clone
cd ~/Sites/blueflyio/__CURRENT_WORK/${PROJECT}
git fetch origin ${BRANCH}
git worktree add "${WORKTREE_PATH}" origin/${BRANCH}

🔒 _REPOSITORIES Directory

Location: /Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES/

CRITICAL RULE: All repos MUST be on release/v0.N.x branches

Purpose

Stable reference copies
Always on release branches
Used for quick reference and browsing
NOT for active development (use .worktrees for that)

Branch Policy

✅ ALLOWED:

release/v0.1.x
release/v0.2.x
release/v0.3.x

❌ FORBIDDEN:

main (not stable)
feature/* (belongs in worktrees)
chore/* (belongs in worktrees)
Any non-release branch

Verification

cd "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES"

# Check all repos are on release branches
for dir in */; do
  cd "$dir"
  BRANCH=$(git branch --show-current)
  if [[ ! "$BRANCH" =~ ^release/v[0-9]+\.[0-9]+\.x$ ]]; then
    echo "❌ $dir is on $BRANCH (VIOLATION)"
  else
    echo "✅ $dir is on $BRANCH"
  fi
  cd ..
done

Enforcement

All agents MUST:

Check branch before making changes
Refuse to work on non-release branches in _REPOSITORIES
Redirect work to .worktrees instead

📋 Quick Reference

Directory	Purpose	Branch Policy	Active Dev
`.worktrees/<project>/<branch>/`	Active development	Any branch	✅ YES
`_REPOSITORIES/<project>/`	Stable reference	release/v0.N.x ONLY	❌ NO

🔄 Migration from Date-Based Structure

If you have old date-based worktrees, migrate them:

cd "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/.worktrees"

# Find all date-based folders
for date_dir in 2026-*/; do
  echo "Processing $date_dir..."

  for project_dir in "$date_dir"*/; do
    PROJECT=$(basename "$project_dir")

    # Move to project-based structure
    mkdir -p "${PROJECT}"
    mv "$date_dir$PROJECT" "${PROJECT}/"
  done

  # Remove empty date folder
  rmdir "$date_dir" 2>/dev/null
done

🎯 Benefits

Clarity: Easy to find current work by project name
No Confusion: No need to remember which date folder has current work
Stable References: _REPOSITORIES always on release branches
Clean: One location per project, multiple branches possible
iCloud Sync: Works seamlessly with iCloud Drive sync

🛡️ Workspace Protection (NEW - 2026-02-06)

Overview

Workspace Protection is a multi-layer system that enforces read-only access to _REPOSITORIES/ and ensures all development happens in .worktrees/.

Delivered: 2026-02-06 (pushed to GitLab release/v0.1.x) Repos: ide-supercharger, compliance-engine, api-schema-registry

Architecture

4-Layer Protection:

IDE Hooks (PreToolUse) - Block Edit/Write operations before they happen
Cedar Policies - Runtime authorization via compliance-engine
Git Hooks - Prevent commit/push/merge in read-only directories
Claude Settings - Auto-approve work directories, block read-only dirs

Protected Directories (Read-Only)

**/_REPOSITORIES/**           # All repos in _REPOSITORIES (release branches only)
**/__CURRENT_WORK/**         # Legacy location (if used)
**/vendor/**                  # Composer dependencies
**/web/modules/**             # Drupal contrib modules
**/web/themes/**              # Drupal contrib themes
**/web/core/**                # Drupal core
**/.git/objects/**            # Git internals

Allowed Operations:

✅ Read files
✅ git pull, git fetch, git worktree, git status, git log, git diff
❌ Edit, create, delete files
❌ git commit, git push, git merge, git rebase, git reset

Auto-Approved Directories (No Prompts)

**/.worktrees/**              # All active development
**/DEMOs/**                   # Local demos and examples
**/wikis/**                   # Documentation
**/tmp/**                     # Temporary files

All Operations Allowed: Edit, create, delete, git commit, git push, etc.

Configuration

Location: ~/.claude/workspace-protection.json

Example Config:

{
  "version": "1.0",
  "workspace": {
    "root": "${WORKSPACE_ROOT}",
    "readOnlyDirs": [
      "**/_REPOSITORIES/**",
      "**/__CURRENT_WORK/**",
      "**/vendor/**"
    ],
    "workDirs": [
      "**/.worktrees/**",
      "**/DEMOs/**"
    ],
    "autoApprovedDirs": [
      "${WIKIS_PATH}",
      "${WORKSPACE_ROOT}/.worktrees"
    ]
  },
  "environments": {
    "m4-mac": {
      "WORKSPACE_ROOT": "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform",
      "WIKIS_PATH": "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/wikis"
    }
  }
}

Team Installation

Option 1: NPM Package (Recommended)

npx ide-init

Option 2: BuildKit CLI

buildkit hooks install-preset workspace-protection --yes
buildkit workspace setup --yes
buildkit workspace validate

Option 3: Manual Install

# Copy config template
cp ~/.claude/templates/workspace-protection.json ~/.claude/workspace-protection.json

# Install hooks
buildkit hooks install protect-current-work protect-git-operations

How It Works

Before Edit/Write: Claude Code checks PreToolUse hooks
- Hook reads ~/.claude/workspace-protection.json
- Checks if file path matches read-only patterns
- Blocks operation if in read-only directory
- Shows error: "🚫 BLOCKED: Cannot edit files in _REPOSITORIES"
Before Git Operations: Git hook checks current directory
- Blocks git commit, git push, git merge in read-only dirs
- Shows hint: "Create a worktree instead: git worktree add <path> <branch>"
Runtime Authorization: compliance-engine evaluates Cedar policies
- Policies check resource.path against config patterns
- Agent tier restrictions (even tier_3_full_access agents blocked)
- Requires approval for destructive operations in worktrees

Benefits

Prevent Accidents: Can't accidentally commit to release branches in _REPOSITORIES
Enforce Workflow: Forces worktree-based development (best practice)
Multi-Developer: Config-driven, supports multiple environments
Relocatable: No hardcoded paths, uses environment variables
Team-Wide: Distribute via NPM package or BuildKit CLI

GitLab Repos

ide-supercharger: https://gitlab.com/blueflyio/agent-platform/ide-supercharger/-/tree/release/v0.1.x
compliance-engine: https://gitlab.com/blueflyio/agent-platform/compliance-engine/-/tree/release/v0.1.x
api-schema-registry: https://gitlab.com/blueflyio/agent-platform/api-schema-registry/-/tree/release/v0.1.x

Worktree Structure Guide

Worktree Structure Guide

📂 Directory Structure

✅ Correct Structure

❌ DEPRECATED: Date-Based Structure

🚀 Worktree Creation

Standard Workflow

For Existing Local Repo

🔒 _REPOSITORIES Directory

Purpose

Branch Policy

Verification

Enforcement

📋 Quick Reference

🔄 Migration from Date-Based Structure

🎯 Benefits

🛡️ Workspace Protection (NEW - 2026-02-06)

Overview

Architecture

Protected Directories (Read-Only)

Auto-Approved Directories (No Prompts)

Configuration

Team Installation

How It Works

Benefits

GitLab Repos

See Also