docs-researcher

Dotfiles - Windows 11 Development Environment

Automated Windows 11 development environment setup using PowerShell scripts and configuration management.

🎯 Purpose

Transform a factory-reset Windows 11 machine into a fully configured development workstation:

• Automated installation of development tools via Chocolatey
• Configuration management through symlinked dotfiles
• PowerShell profile with Oh My Posh and custom tooling
• Reproducible setup in under 30 minutes

📁 What's Inside

dotfiles/
├── .claude/commands/         # SpecKit slash commands for Claude Code
├── .specify/                 # Spec-driven development templates
├── windows-install-scripts/  # PowerShell Windows automation scripts
├── powershell/               # PowerShell profile config (planned)
├── git/                      # Git configuration (planned)
├── plugin.json               # Claude Code plugin definition
└── .gitignore                # Excludes secrets and working files

Current Status: Implementation complete! All scripts and configuration files are ready for use.

🚀 Quick Start

Option 1: Full Windows 11 Environment Setup

Prerequisites:

• Windows 11 (Windows 10 supported with warnings)
• Administrator privileges
• Internet connectivity
• 20GB free disk space

Installation Steps:

1. Clone the repository:

   git clone https://github.com/amoscicki/dotfiles.git
   cd dotfiles
   

2. Run the master installation script:

   # Interactive installation (with confirmations)
   .\windows-install-scripts\install.ps1
   
   # Fully automated installation (no prompts)
   .\windows-install-scripts\install.ps1 -Unattended
   
   # Preview what would be installed (dry-run)
   .\windows-install-scripts\install.ps1 -WhatIf
   

3. Complete manual post-installation steps:

   # Update Git user configuration (REQUIRED)
   git config --global user.name "Your Name"
   git config --global user.email "[email protected]"
   
   # Install Claude Code plugin (if Claude Code installed)
   # In Claude Code, run:
   /plugin install file://P:/dotfiles
   # Or from GitHub:
   /plugin install github.com/amoscicki/dotfiles
   
   # Restart PowerShell to load profile with Oh My Posh
   

4. Verify installation:

   choco --version
   git --version
   node --version
   pnpm --version
   gh --version
   fzf --version
   oh-my-posh --version
   

Time Estimate: ~30 minutes (excluding download times)

Option 2: Install as Claude Code Plugin Only

From GitHub:

/plugin install github.com/amoscicki/dotfiles

Local development:

/plugin install file://P:/dotfiles

Verify:

/plugin list
/speckit.constitution

This makes all SpecKit commands (/speckit.*) available globally in Claude Code.

Option 3: Clone for Development

git clone https://github.com/amoscicki/dotfiles.git dotfiles
cd dotfiles

Commands in .claude/commands/ are available when working in this directory.

🛠️ Technology Stack

• Platform: Windows 11
• Package Manager: Chocolatey
• Scripting: PowerShell 7+
• Prompt Theme: Oh My Posh (powerlevel10k_rainbow)
• Development: SpecKit for spec-driven workflow

🎓 Philosophy

This dotfiles repository follows the principles defined in .specify/memory/constitution.md:

1. Public by Default - All configuration files, scripts, and documentation are safe for public repositories. Sensitive data excluded via .gitignore or stored externally using secure credential management.

2. Automation First - Manual setup steps minimized through PowerShell scripts, Chocolatey package managers, and symlink automation. Installation achievable through a single master script execution.

3. Modular & Independent - Each tool's configuration is self-contained in its own directory. Configurations have no hidden dependencies on other configurations. Each module is installable independently via its own script.

4. Spec-Driven Development - All significant features follow SpecKit workflow: specification → planning → tasks → implementation. Changes are documented in spec files before implementation.

5. Documentation as Code - Every script includes comments explaining its purpose and usage. Every configuration directory contains a README or inline comments describing the configuration's purpose. The main README is kept current with actual repository structure and capabilities.

🔧 Troubleshooting

Common Issues

Chocolatey Installation Fails:

• Check internet connectivity and proxy settings
• Verify Windows Defender or antivirus isn't blocking the installer
• Manual install: Visit https://chocolatey.org/install
• Check logs in logs/ directory for detailed error messages