Skip to content

CLAUDE.md

Latest commit

 

History

History
78 lines (56 loc) · 3.24 KB

CLAUDE.md

File metadata and controls

78 lines (56 loc) · 3.24 KB
Raw

CLAUDE.md

This file provides Claude-specific guidance when working with this dotfiles repository.

For general project information, installation instructions, and usage details, see the README.

Uphold Project Invariants

Before designing, writing, or editing any code — invoke the uphold-project-invariants skill. It loads this repo's own docs/invariants/ and docs/standards/. This is in addition to the global uphold-standards skill, not instead of it: that one carries portable engineering guidance, this one carries what is true only here.

Folder Structure

See README.md for the complete overview. Key points for Claude:

Current Active Structure:

  • Installation scripts are in features/install/zsh/ (individual .zsh files)
  • Update scripts are in features/update/zsh/
  • Main setup script is features/setup/setup.zsh
  • Configuration files are in tools/{tool}/config/ directories

Folder Structure

  • Common functionality being built in features/common/ (bash modules for shared logic)
  • Tool-specific logic is in tools/{tool}/ folders
  • Feature-specific code (leveraging one or more tools) is in features/{feature}/ folders
  • Future main setup script will be features/setup/setup.bash
  • Future main update script will be features/update/bash/tools.bash
  • Note: These bash files are not yet functional or ready for use

Self-Contained Feature Modules (features/common/) - Under construction:

  • detection/ - Machine and macOS detection logic
  • dry-run/ - Dry run utilities
  • errors/ - Error handling
  • permissions/ - Permission utilities
  • prerequisites/ - Installation prerequisites validation
  • symlinks/ - Symlink management
  • testing/ - Testing utilities and test suite

Self-Contained Tool Modules (tools/{tool}/)

  • See tools/@new for an example of the files in each folder
  • See tools/README.md for an explanation of the feature folder approach
  • For brew formulae without config, see tools/eza/ or tools/logcli/ as examples

Symlink Management

Important for Git commits: Files in tools/claude/config/ are symlinked to ~/.claude/. To commit changes to global Claude settings (like ~/.claude/CLAUDE.md), commit the dotfiles copy at tools/claude/config/CLAUDE.md instead of trying to commit outside the repository.

The symlink creation logic is in features/update/symlinks.bash, invoked by features/update/tools.bash and by the symlinks alias. (features/install/zsh/deprecated/symlinks.zsh is deprecated and only still sourced by features/setup/setup.zsh.)

Claude Development Workflow

When making changes to this repository:

  1. Verify file existence before referencing scripts or commands
  2. Use actual file paths from the repository structure
  3. Update all relevant README.md files after making any user-facing changes
  4. Update all relevant project-level CLAUDE.md files after clarifying any Claude-specific workflows

Testing and Verification

  • The commands that check a change, and how to run what you changed, are in CONTRIBUTING.md. Read it before running anything, and run every check it lists before reporting a change as done.
  • Run symlinks alias to recreate all symlinks
  • Test individual scripts by sourcing them