# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## IMPORTANT: Session Start Protocol

**At the beginning of every new session**, if the user has NOT explicitly specified which exploration they are working on, you MUST ask the user:

> "Which exploration are you working on today?"

This is critical for maintaining context and ensuring you're working on the correct feature or experiment. Do not proceed with any implementation work until the user has clarified their current exploration focus.

### Exploration Scoping Rules

Once the user specifies their current exploration:

1. **ONLY work within that exploration's scope** - All code changes, new files, and modifications should be isolated to that specific exploration
2. **DO NOT modify code in other explorations** - Treat other explorations as off-limits unless explicitly instructed otherwise
3. **Keep explorations independent** - Each exploration should be self-contained and not affect the functionality of other explorations
4. **Shared code considerations** - If you need to modify shared/common code that affects multiple explorations, explicitly ask the user for confirmation before proceeding

When in doubt about whether a change affects multiple explorations, always ask the user first.

### Creating New Explorations and Sections

If the user wants to create a new exploration or section, offer them these options:

1. **Create a new exploration in an existing section** - Add the exploration to their current section/namespace
2. **Create a new section with a name and exploration** - Set up a new section (typically named after a person) and create the first exploration within it

When creating new explorations:
- Ask the user for the section name (if creating a new section)
- Ask for the exploration name
- Ensure proper organization and isolation from other explorations
- Set up any necessary folder structure or naming conventions to keep explorations clearly separated
- **By default, disable navigation back controls** - New explorations should have `.navigationBarBackButtonHidden(true)` and include a `DragGesture()` to block swipe-to-go-back unless the user specifically requests these navigation features

## Project Overview

This is a SwiftUI iOS application called "vibes" that follows a design-focused development approach with integration to Figma via MCP (Model Context Protocol). The project emphasizes creating reusable, responsive SwiftUI components with attention to visual polish and user experience.

## Build and Development Commands

### Building and Testing
- **Build**: Use Xcode's build system (⌘+B) or `xcodebuild -project vibes.xcodeproj -scheme vibes build`
- **Run Tests**: Use Xcode's test runner (⌘+U) or `xcodebuild test -project vibes.xcodeproj -scheme vibes -destination 'platform=iOS Simulator,name=iPhone 15'`
- **Code Formatting**: SwiftFormat is integrated via Swift Package Manager for consistent code style

### Testing Framework
- Uses Swift Testing framework (not XCTest) - note the `import Testing` and `@Test` syntax
- Test files are in `vibesTests/` directory
- Example test structure available in `vibesTests/vibesTests.swift:13`

## Architecture and Code Organization

### Main Structure
- **App Entry Point**: `vibes/vibesApp.swift:11` - Standard SwiftUI App structure
- **Main View**: `vibes/ContentView.swift:10` - Primary content view with preview support
- **Constants**: `vibes/Constants.swift:10` - Centralized color and styling constants

### Design System Integration
- Figma integration via Claude MCP for design-to-code workflow
- Reusable component approach emphasized
- Constants file established for consistent styling (e.g., `BorderPrimary` color)

### Key Dependencies
- **Figma Code Connect**: Integration for design handoff workflow
- **SwiftFormat**: Code formatting and style consistency
- **Swift Argument Parser**: Command-line argument handling
- **Swift Syntax**: Swift AST manipulation

### File Organization Recommendations
Based on the swift.md guide, follow this structure:
```
/vibes
├── Components/          # Reusable SwiftUI components
├── Views/              # Screen-level views
├── Assets.xcassets/    # Images, colors, icons
├── Utils/              # Extensions and custom modifiers
└── Constants.swift     # Centralized styling constants
```

### Development Guidelines
- Prioritize component reusability and modularity
- Use meaningful naming conventions for assets: `[Context]/[AssetType]_[Name]`
- Implement responsive layouts using GeometryReader, ViewThatFits, and LayoutPriority
- Add subtle animations that enhance UX without distraction
- Maintain design-code consistency via Figma MCP integration

### Memory
- Always refer to the swift.md before doing something