worktree structure old

BlueFly.io Worktree Structure - NAS-Backed Workflow

⚠️ OUTDATED: This document describes the OLD architecture with local worktrees.

CURRENT (as of 2026-01-23): 100% NAS-centralized - ALL worktrees on NAS.

See instead:

AGENTS.md - Complete NAS-centralized workflow
CLAUDE.md - Full instructions with NAS paths
INFRASTRUCTURE_MIGRATION_SUMMARY.md - Migration details
/Volumes/AgentPlatform/AGENTS.md - Master reference

OLD Architecture (Pre-NAS Migration)

Source of Truth: NAS bare repos (accessible from all devices) Working Copies: ~~Local worktrees (device-specific, ephemeral)~~ NOW ON NAS

NAS (blueflynas.tailcf98b3.ts.net)
└── /volume1/AgentPlatform/repos/bare/blueflyio/
    ├── agent-platform/
    │   ├── agent-buildkit.git           ← Bare repo (source of truth)
    │   ├── compliance-engine.git        ← Bare repo
    │   └── agent-protocol.git           ← Bare repo
    └── gitlab_components.git            ← Bare repo

Local Machine (M3, M4, etc.)
└── /Users/thomas.scola/Sites/blueflyio/
    ├── .worktrees/                      ← All work happens here
    │   └── ${DATE}/                     ← YYYY-MM-DD format
    │       └── ${PROJECT}/              ← Project name (matches GitLab)
    │           └── ${ISSUE#-SLUG}/      ← Issue worktree
    └── _WIKI/                           ← Documentation only

Path Pattern

# Worktrees (local, device-specific)
.worktrees/${DATE}/${PROJECT}/${ISSUE#-SLUG}/

# NAS bare repos (shared, multi-device)
/Volumes/AgentPlatform/repos/bare/blueflyio/${GROUP}/${PROJECT}.git

Variables

DATE="YYYY-MM-DD"              # Today's date (e.g., 2026-01-19)
PROJECT="project-name"         # GitLab project name
GROUP="agent-platform"         # GitLab group (or empty for root)
ISSUE#="383"                   # GitLab issue number
SLUG="issue-title-slug"        # GitLab-generated slug

Real Examples

Create Worktree for Issue #383

# NAS bare repo (source)
/Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-buildkit.git

# Creates local worktree
/Users/thomas.scola/Sites/blueflyio/.worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/

Multiple Projects Same Day

.worktrees/2026-01-19/
├── agent-buildkit/
│   ├── 383-cicd-recovery-commands/
│   └── 401-add-gitlab-audit/
├── compliance-engine/
│   ├── 145-fix-cedar-policy/
│   └── 167-add-organization-audit/
└── gitlab_components/
    └── 457-fix-golden-component-api-first/

Same Project Multiple Days

.worktrees/
├── 2026-01-18/
│   └── agent-buildkit/
│       └── 383-cicd-recovery-commands/  (still in progress)
└── 2026-01-19/
    └── agent-buildkit/
        └── 401-add-gitlab-audit/        (started today)

Critical Rules

❌ NEVER Do This

# NO source repos at root!
/Users/thomas.scola/Sites/blueflyio/agent-buildkit/        ← WRONG
/Users/thomas.scola/Sites/blueflyio/compliance-engine/     ← WRONG

# NO committing in source repos
cd agent-buildkit && git commit                            ← BLOCKED

# NO manual branch creation
git checkout -b feat/my-feature                            ← WRONG

✅ ALWAYS Do This

# Work in worktrees
cd .worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/

# Start work via slash command
/dev:start-issue 383

# Cleanup via slash command
/dev:cleanup-issue 383

Workflow Commands

Start Working on Issue

# From anywhere in blueflyio workspace
/dev:start-issue 383

# What it does:
# 1. Fetches latest from NAS: /Volumes/AgentPlatform/repos/bare/.../agent-buildkit.git
# 2. Creates MR+Branch via GitLab API: 383-cicd-recovery-commands
# 3. Creates local worktree: .worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/
# 4. Switches to worktree

Cleanup After MR Merges

/dev:cleanup-issue 383

# What it does:
# 1. Removes worktree: .worktrees/*/agent-buildkit/383-cicd-recovery-commands/
# 2. Deletes local branch
# 3. Cleans up empty folders

NAS Access Patterns

Via NFS Mount (Preferred)

# Mount NAS (if not auto-mounted)
mkdir -p /Volumes/AgentPlatform
mount_nfs blueflynas.tailcf98b3.ts.net:/volume1/AgentPlatform /Volumes/AgentPlatform

# Access bare repos
cd /Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/
ls -la *.git

Via SSH (Fallback)

# Fetch from NAS
git fetch bluefly@blueflynas.tailcf98b3.ts.net:/volume1/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-buildkit.git

# Push to NAS
git push bluefly@blueflynas.tailcf98b3.ts.net:/volume1/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-buildkit.git

Find Today's Work

cd .worktrees/$(date +%Y-%m-%d)/
ls -la  # All projects worked on today

Find All Work on a Project

# All agent-buildkit worktrees across all dates
ls -d .worktrees/*/agent-buildkit/*/

# All worktrees for a specific issue
find .worktrees -name "383-*" -type d

Find Work This Month

# Current month's worktrees
ls -d .worktrees/$(date +%Y-%m)-*/

# Specific month
ls -d .worktrees/2026-01-*/

Cleanup Strategies

Archive Old Worktrees

# Find worktrees older than 7 days
find .worktrees -maxdepth 1 -type d -mtime +7 -name "20*"

# Archive by month (once MRs merged)
mkdir -p ~/Archives/worktrees/2026-01/
mv .worktrees/2026-01-* ~/Archives/worktrees/2026-01/

# Delete archived (after verification)
rm -rf ~/Archives/worktrees/2025-*/

Evacuation Audit

# Check for uncommitted/unpushed work
cd .worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/
git status
git log @{u}..  # Unpushed commits

# Use buildkit evacuation tool
buildkit worktrees audit
buildkit worktrees evacuate --dry-run
buildkit worktrees evacuate

Benefits of NAS-Backed Architecture

Multi-Device Access

M3Gitlab (work laptop) and M4Bluefly (personal) access same NAS repos
iPhone/iPad can clone via Tailscale SSH
Any device with Tailscale can access bare repos

Single Source of Truth

NAS has canonical bare repos
All devices fetch/push to NAS
No sync conflicts between devices

Device-Local Worktrees

Worktrees are fast (local SSD)
No NAS latency during development
Can delete worktrees without losing data (still in NAS)

Automatic Backups

NAS handles backups (Hyper Backup)
Git objects replicated to cloud
No manual backup needed

Directory Size Management

# Check worktree disk usage
du -sh .worktrees/*

# Check per-project usage
du -sh .worktrees/*/agent-buildkit

# Find large worktrees
find .worktrees -type d -name "*-*" -exec du -sh {} \; | sort -h | tail -20

Pre-Commit Hooks

Git hooks block commits in wrong locations:

# ✅ Allowed: Commits in worktrees on feature branches
cd .worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/
git commit -m "feat: add command"  # ✅ Works

# ❌ Blocked: Commits in source repos
cd agent-buildkit/  # If this even existed
git commit          # ❌ Blocked by pre-commit hook

# ❌ Blocked: Commits to main/development
cd .worktrees/2026-01-19/agent-buildkit/383-cicd-recovery-commands/
git checkout development
git commit          # ❌ Blocked by pre-commit hook

Automation Support

[object Object] Command

# Input: Issue number
ISSUE_NUM="383"

# Logic:
# 1. Get current project from git remote
PROJECT=$(git remote get-url origin | sed 's/.*\/\([^/]*\)\.git/\1/')

# 2. Create MR+Branch via GitLab API
BRANCH=$(glab mr create --issue $ISSUE_NUM --print-url | grep -o '[0-9]*-.*')

# 3. Create dated worktree path
DATE=$(date +%Y-%m-%d)
WORKTREE_PATH=".worktrees/$DATE/$PROJECT/$BRANCH"

# 4. Add worktree from NAS
NAS_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/$PROJECT.git"
git worktree add $WORKTREE_PATH $BRANCH --track origin/$BRANCH

# 5. Switch to worktree
cd $WORKTREE_PATH

[object Object] Command

# Input: Issue number
ISSUE_NUM="383"

# Logic:
# 1. Find worktree
WORKTREE=$(git worktree list | grep "$ISSUE_NUM-" | awk '{print $1}')

# 2. Remove worktree
git worktree remove $WORKTREE --force

# 3. Delete local branch
BRANCH=$(basename $WORKTREE)
git branch -D $BRANCH

# 4. Cleanup empty folders
find .worktrees -type d -empty -delete

NAS Setup: _WIKI/technical-docs.wiki/action-items/02-infrastructure/NAS-CONFIGURATION.md
GitLab Workflow: CLAUDE.md (project root)
Issue-Driven Development: _WIKI/technical-docs.wiki/action-items/14-workflow/ISSUE-DRIVEN-DEVELOPMENT.md

worktree structure old

BlueFly.io Worktree Structure - NAS-Backed Workflow

OLD Architecture (Pre-NAS Migration)

Path Pattern

Variables

Real Examples

Create Worktree for Issue #383

Multiple Projects Same Day

Same Project Multiple Days

Critical Rules

❌ NEVER Do This

✅ ALWAYS Do This

Workflow Commands

Start Working on Issue

Cleanup After MR Merges

NAS Access Patterns

Via NFS Mount (Preferred)

Via SSH (Fallback)

Navigation

Find Today's Work

Find All Work on a Project

Find Work This Month

Cleanup Strategies

Archive Old Worktrees

Evacuation Audit

Benefits of NAS-Backed Architecture

Multi-Device Access

Single Source of Truth

Device-Local Worktrees

Automatic Backups

Directory Size Management

Pre-Commit Hooks

Automation Support

[object Object] Command

[object Object] Command

Related Documentation