training

Claude Code Training - BlueFly.io Workspace

Created: 2026-01-19 Updated: 2026-01-25 (NAS-Centralized Migration) Purpose: NAS-centralized workflow training

Architecture Change (2026-01-23)

OLD: Local repos + local worktrees NEW: NAS bare repos + NAS worktrees (100% NAS-based)

Migration Complete:

✅ All 67 repositories → NAS bare repos (/Volumes/AgentPlatform/repos/bare/blueflyio/)
✅ All worktrees → NAS device namespaces (/Volumes/AgentPlatform/worktrees/[device]/)
✅ All wikis → NAS (/Volumes/AgentPlatform/wikis/blueflyio/)
✅ Local cleanup complete (freed 3.2GB)

Core Principles (NEVER VIOLATE)

1. File Policy

❌ NO .md files (use GitLab Wiki or Issues)
❌ NO .sh scripts (use npm scripts or TypeScript)
❌ NO scripts/ folders (dumping ground)
❌ NO root-level clutter

2. Git Workflow

✅ ALWAYS work in worktrees (.worktrees/YYYY-MM-DD/[project]/[issue]/)
✅ ALWAYS start from GitLab issues
✅ ALWAYS use /dev:start-issue and /dev:cleanup-issue
❌ NEVER commit to main/development directly
❌ NEVER manually create branches
❌ NEVER add AI attribution or emoji to commits

3. Architecture

OpenAPI-first (spec → types → validation)
DRY (single source of truth)
CRUD (full Create/Read/Update/Delete)
SOLID principles
Type-safe (Zod schemas from OpenAPI)

BlueFly.io Workspace Structure (NAS-Centralized)

NAS: /Volumes/AgentPlatform/
├── repos/bare/blueflyio/          # ALL git repositories (bare)
│   ├── agent-platform/            # Nested group
│   │   ├── agent-buildkit.git
│   │   ├── compliance-engine.git
│   │   └── ... (50+ repos)
│   ├── gitlab_components.git
│   └── platform-agents.git
├── worktrees/                     # ALL worktrees (device namespaces)
│   ├── shared/YYYY-MM-DD/        # Multi-device access
│   │   └── [project]/[issue]/
│   ├── m3/YYYY-MM-DD/            # Mac M3 performance work
│   │   └── [project]/[issue]/
│   └── m4/YYYY-MM-DD/            # Mac M4 performance work
│       └── [project]/[issue]/
└── wikis/blueflyio/              # ALL wikis
    ├── technical-docs.wiki/      # Agent Platform docs
    ├── api_normalization.wiki/
    └── ai_assets.json            # DEPRECATED (use $BARE_REPOS/config.json)

Local: /Users/thomas.scola/Sites/blueflyio/
├── .claude/                      # Config only
│   ├── config.json
│   ├── README
│   └── TRAINING.md
├── AGENTS.md                     # Project instructions
├── CLAUDE.md                     # Full instructions
└── [NO REPOS, NO WORKTREES, NO WIKIS - ALL ON NAS]

Workflow Automation (NAS-Centralized)

Starting Work on an Issue

# 1. Find your issues
glab issue list --assignee @me

# 2. Fetch from NAS bare repo
BARE_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/[group]/[project].git"
git -C "$BARE_REPO" fetch --prune origin

# 3. Create worktree on NAS (choose device namespace)
# For multi-device work (code-server, phone, iPad):
WORKTREE="/Volumes/AgentPlatform/worktrees/shared/$(date +%Y-%m-%d)/[project]/845-fix-auth"
# For performance work on Mac M4:
# WORKTREE="/Volumes/AgentPlatform/worktrees/m4/$(date +%Y-%m-%d)/[project]/845-fix-auth"

git -C "$BARE_REPO" worktree add "$WORKTREE" 845-fix-auth

# 4. Work in NAS worktree
cd "$WORKTREE"

Working in NAS Worktree

# Navigate to NAS worktree
cd /Volumes/AgentPlatform/worktrees/shared/2026-01-25/[project]/845-fix-auth/

# Make changes (accessible from ANY device)
git add .
git commit -m "fix: resolve authentication issue"

# Push (ALWAYS ask user first per CLAUDE.md rules)
git push

After MR Merges

# Cleanup NAS worktree
BARE_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/[group]/[project].git"
WORKTREE="/Volumes/AgentPlatform/worktrees/shared/2026-01-25/[project]/845-fix-auth"

# Remove worktree from NAS
git -C "$BARE_REPO" worktree remove "$WORKTREE"

# Or use slash command (if available)
/dev:cleanup-issue 845

NAS Path Pattern Benefits

Pattern: /Volumes/AgentPlatform/worktrees/{DEVICE}/{YYYY-MM-DD}/{PROJECT}/{ISSUE#-SLUG}/

Benefits:

Multi-Device Access: Work from Mac M3, M4, code-server, phone, iPad - same files
Device Namespaces: shared/, m3/, m4/ for isolation and performance
Chronological: Year-first sorting (2026-01-19, 2026-01-20, etc.)
Project Isolation: Each repo has its own folder
GitLab Mirroring: Structure matches gitlab.com/blueflyio/
Context Preservation: Path shows device, date, and issue
Easy Cleanup: Find old work by date across all devices

Examples:

# Today's work (all devices)
ls /Volumes/AgentPlatform/worktrees/*/$(date +%Y-%m-%d)/

# All work on agent-buildkit (all devices, all dates)
ls -d /Volumes/AgentPlatform/worktrees/*/*/agent-buildkit/*/

# This month (all devices)
ls -d /Volumes/AgentPlatform/worktrees/*/2026-01-*/

# Cleanup old (30+ days, all devices)
find /Volumes/AgentPlatform/worktrees -name "2025-*" -type d

GitLab Integration

Organization: https://gitlab.com/blueflyio

Key Commands

# List assigned issues
glab issue list --assignee @me

# View issue details
glab issue view 845

# List your MRs
glab mr list --assignee @me

# View MR details
glab mr view 123

# Check CI status
glab ci status

Development Standards

TypeScript Project Structure

project-name/
├── src/
│   ├── api/          # API route handlers
│   ├── cli/          # CLI tools (replaces .sh)
│   ├── schemas/      # Zod schemas (from OpenAPI)
│   ├── services/     # Business logic
│   └── tools/        # Dev utilities
├── specs/            # OpenAPI specifications
├── tests/            # Test files
├── .husky/           # Git hooks (JS/TS only)
└── package.json      # npm scripts for automation

OpenAPI → Zod → Types Flow

Define API in OpenAPI spec (specs/api.yaml)
Generate Zod schemas (auto-generated)
Use schemas for runtime validation
Types derived from schemas
Single source of truth (the spec)

Safety Features

Pre-Commit Hooks

Your bash-safety-validator blocks:

Recursive deletions in home directory (use trash instead)
Commits in source repos (not on development/main)
Direct commits to protected branches

Status Line

Custom status line shows:

User@hostname
Current directory
Git branch + dirty state (± if uncommitted changes)

Current State

~/.claude: 2.7MB (minimal, clean) Remaining:

plugins: 1.7MB
commands: 632KB (custom commands)
settings.json: hooks + status line config
CLAUDE.md: global instructions
hooks/: bash-safety-validator.py

All history cleared: Fresh conversation, no context from old projects

Next Steps (NAS-Centralized)

Mount NAS: /Volumes/AgentPlatform/ (Finder > ⌘K > nfs://192.168.68.54/volume1/AgentPlatform)
Verify bare repos: ls /Volumes/AgentPlatform/repos/bare/blueflyio/
Use glab issue list to find work
Create NAS worktrees (choose device namespace: shared/, m3/, or m4/)
Work in NAS worktrees (accessible from any device)
Push to MRs (ask user first)
Cleanup NAS worktrees after merge

Remember (NAS-Centralized)

NO local repos - All repos are bare on NAS at [PATH-BARE-REPOS]
NO local worktrees - All worktrees on NAS at [PATH-WORKTREES]
NO local wikis - All wikis on NAS at [PATH-WIKIS-BASE]
All feature work in NAS worktrees (accessible from ANY device)
GitLab creates branches automatically
Professional commits (no AI attribution, no emoji)
OpenAPI is the source of truth
DRY, SOLID, type-safe always
Everything on NAS, nothing local except instructions