VitalArc Workstation Session Init

Start a full development session on Mac with Xcode builds and simulator access.

Task Dependency Graph

┌─────────────────────────────────────────────────────────────────────┐
│                    SESSION INITIALIZATION PIPELINE                   │
├─────────────────────────────────────────────────────────────────────┤
│  PHASE 1 - Git Sync (inline bash):                                  │
│    └── Stash changes → Fetch/pull main                              │
│                                                                      │
│  PHASE 2 - Session Number + Branch (inline bash):                   │
│    └── Parse SESSION_LOG.md → Calculate number → Create branch      │
│    ⚠️ MUST run inline - never delegate to subagent                  │
│                                                                      │
│  PHASE 3 - Focus + Parallel Skills:                            │
│    ├── Skill: focus-suggester            ─┐                            │
│    ├── Skill('build-validator')         ├── ALL run in parallel      │
│    └── Skill('design-system-scanner')  ─┘                            │
│                                                                      │
│  PHASE 4 - Restore Stash (inline bash)                              │
│                                                                      │
│  PHASE 5 - Session Log (inline write, uses Phase 3 results)        │
│                                                                      │
│  PHASE 6 - Output Summary                                           │
└─────────────────────────────────────────────────────────────────────┘

Execution Rules

Every phase has a binding execution method. Do not deviate.

Phase	Method	Rationale
1 - Git Sync	Inline bash	Deterministic git commands
2 - Session Number + Branch	Inline bash	Deterministic; must not delegate
3 - Focus/Build/Scan	Skill()	focus-suggester + build/scan via Skills
4 - Restore Stash	Inline bash	Simple git command
5 - Session Log	Inline Write/Edit	Template fill from Phase 3 results
6 - Output Summary	Inline text	Display to user

Prohibitions:

• Do not use TaskCreate for operations that have dedicated skills. Build validation and design system scanning have dedicated skills (build-validator, design-system-scanner). Invoke them via Skill().
• Do not delegate deterministic calculations to subagents. Session number parsing, date arithmetic, and focus determination must run inline. Subagents (especially lighter models) can produce incorrect results for arithmetic and date logic.

Implementation

Phase 1: Git Sync (Inline Bash)

Execute these git commands directly before any other work:

# Stash any uncommitted changes
[ -n "$(git status --porcelain)" ] && git stash push -m "Auto-stash $(date +%Y-%m-%d-%H%M)"

# Sync with main
git fetch origin && git checkout main && git pull origin main --ff-only

Phase 2: Session Number + Branch (Inline Bash)

Run this inline. Never delegate to a subagent.

Calculate the session number and create the branch in a single inline bash block:

TODAY=$(date +%Y-%m-%d)
FOCUS="${ARGUMENTS:-session}"

# Parse latest session entry from SESSION_LOG.md
LATEST_ENTRY=$(grep -E "^## Session [0-9]+\.[0-9]+ - " SESSION_LOG.md | head -1)
LATEST_MAJOR=$(echo "$LATEST_ENTRY" | sed -E 's/## Session ([0-9]+)\..*/\1/')
LATEST_MAJOR=${LATEST_MAJOR:-0}

# Extract and parse the date from the latest entry
# Format in log: "February 5, 2026" → need to compare with today
LATEST_DATE_STR=$(echo "$LATEST_ENTRY" | grep -oE "[A-Z][a-z]+ [0-9]+, [0-9]+" | head -1)

# macOS date parsing (use -jf, NOT -d which is Linux-only)
LATEST_DATE=$(date -jf "%B %d, %Y" "$LATEST_DATE_STR" +%Y-%m-%d 2>/dev/null || echo "")

if [ "$LATEST_DATE" = "$TODAY" ]; then
    SESSION=$LATEST_MAJOR
    # Count existing entries for this session number today
    MINOR=$(grep -cE "^## Session ${SESSION}\.[0-9]+ - " SESSION_LOG.md)
else
    SESSION=$((LATEST_MAJOR + 1))
    MINOR=0
fi

FULL_SESSION="${SESSION}.${MINOR}"
BRANCH="dev/mac-${FOCUS}-${FULL_SESSION}-${TODAY}"

# Create the branch
git checkout -b "$BRANCH"

Validation: After running, echo $FULL_SESSION and $BRANCH to confirm correctness before proceeding.

Phase 3: Focus + Parallel Skills

Determine the session focus and invoke focus/build/scan skills in a single message for parallel execution.

3a. Focus (bash)

FOCUS="${ARGUMENTS:-session}"
echo "Requested focus: $FOCUS"

If no explicit focus was given (FOCUS=session), let focus-suggester recommend the highest-value area from the roadmap and recent history.

3b. Parallel Skill Invocations

// In a SINGLE message, invoke:
Skill('focus-suggester')        // agent: Explore - recommends focus from SESSION_LOG/PROJECT_STATUS/git
Skill('build-validator')        // agent: general-purpose - runs xcodebuild
Skill('design-system-scanner')  // agent: Explore - scans Modules/*/Presentation for violations

Save the focus-suggester output for Phase 5 (session log) and Phase 6 (summary). Wait for all three skills to complete before proceeding to Phase 5.

Phase 4: Restore Stash (Inline Bash)

git stash list | grep -q "Auto-stash $(date +%Y-%m-%d)" && git stash pop

Phase 5: Create Session Log (Inline Write/Edit)

Using results from the three completed skills, write the session log entry directly. Do not delegate this to a TaskCreate.

Use the Write or Edit tool to prepend/append the following template to SESSION_LOG.md, filled with actual values:

## Session [FULL_SESSION] - [Month Day, Year] ([Time])

### Session Start
- **Time**: [Time] PST
- **Platform**: macOS
- **Focus**: [FOCUS from arguments or focus-suggester recommendation]
- **Branch**: [BRANCH]
- **Base**: main @ [latest commit]

### Environment
- **Build Capable**: Yes
- **Test Capable**: Yes (unit + UI)

### Pre-Session Status
- **Build**: [from build-validator result]
- **Design Violations**: [from design-system-scanner result]
- **Uncommitted Changes**: None

### Session Goals
1. [Top focus-suggester recommendation]
2. [Second recommendation, if any]
3. General development as directed

### Work Log
| Time | Action | Files | Notes |
|------|--------|-------|-------|
| [Time] | Session started | - | Build verified |

Phase 6: Output Summary

═══════════════════════════════════════════════════════════════
       VITALARC WORKSTATION SESSION INITIALIZED
═══════════════════════════════════════════════════════════════
Branch:   [branch]
Session:  [FULL_SESSION]
Build:    [status from build-validator]
Focus:    [focus area] + [N-1] more
Violations: [count from design-system-scanner]
───────────────────────────────────────────────────────────────
Full builds, simulator, and testing available
═══════════════════════════════════════════════════════════════

Error Handling

Build Failed on Init

If build-validator reports FAILED:

═══════════════════════════════════════════════════════════════
       ⚠️ SESSION STARTED WITH BUILD ERRORS
═══════════════════════════════════════════════════════════════
Branch:   [branch]
Session:  [FULL_SESSION]
Build:    FAILED ([N] errors)
───────────────────────────────────────────────────────────────
Priority: Fix build before starting new work
═══════════════════════════════════════════════════════════════

Skill Timeout

If any skill doesn't complete within 2 minutes, proceed with available results and note the timeout in the session log.

Options

Option	Description
--worktree	Create isolated worktree for this session
--no-build	Skip build validation (for quick starts)

Worktree Mode (--worktree)

When --worktree flag is provided, create the isolated worktree using native tooling before starting the session. Do not hand-roll git worktree add in inline shell — the session-number and branch-name logic already lives in Phase 2 and must not be duplicated as pseudo-code.

Run worktree creation FIRST (before Phase 1 git sync) using one of:

• The native EnterWorktree tool — creates a new worktree (under .claude/worktrees/) and switches the session into it automatically.
• The /worktree-manager skill — for explicit create/list/remove/switch operations with chosen paths and branches.

The branch name still follows the Phase 2 convention: dev/mac-<focus>-<session>.<minor>-<date>. Once inside the new worktree, proceed with the normal session pipeline (Phases 1-6).

Worktree Output Summary:

═══════════════════════════════════════════════════════════════
       VITALARC WORKTREE SESSION INITIALIZED
═══════════════════════════════════════════════════════════════
Worktree: [worktree path]
Branch:   dev/mac-workout-17.0-2026-02-01
Session:  17.0
Build:    [status]
Focus:    workout
───────────────────────────────────────────────────────────────
NEXT STEPS:
1. Continue development in the isolated worktree
2. Run the normal session pipeline (Phases 1-6)
═══════════════════════════════════════════════════════════════

Benefits of Worktree Mode

• Parallel Development: Work on multiple features simultaneously
• No Branch Switching: Each worktree has its own branch
• Isolated Changes: Changes in one worktree don't affect others
• Easy Cleanup: Remove worktree after PR merge

When to Use Worktree Mode

• Starting a new feature while another is in review
• Need to make urgent fixes while feature work is in progress
• Want to experiment without affecting main development
• Running parallel sessions for different focus areas