Windows Developer Setup Automation

A comprehensive Windows developer setup automation repository featuring PowerShell 7+, Windows 11 optimizations, and mandatory WSL integration. Provides streamlined two-step installation, automated tool deployment, and Claude Code integration with 9+ specialized AI agents for modern development workflows.

🚀 Key Features

• ⚡ Two-Step Setup: Simple install.ps1 → configure.ps1 process
• 🐧 Mandatory WSL Integration: Ubuntu 22.04 development environment
• 🤖 9 Claude Code AI Agents: Specialized experts for domain-specific development
• 📦 30+ Development Tools: Automated WinGet package installation
• 🔐 1Password Integration: Secure credential and environment variable management
• 💻 Professional IDE Setup: VSCode (31+ extensions) + Visual Studio 2022 Professional
• 🎨 Enhanced Terminal Experience: Windows Terminal + PowerShell 7 + Oh My Posh themes
• 🔗 Symbolic Link Management: Centralized configuration with live updates

📋 Table of Contents

• Prerequisites
• Installation and Setup
• Architecture and Components
• Configuration Details
• Claude Code Integration
• Usage Examples
• Directory Structure
• Troubleshooting
• Contributing Guidelines

🔧 Prerequisites

🚀 Installation and Setup

Two-Step Setup Process

Step 1: Install Development Tools & WSL Environment

# Run as Administrator (auto-elevation handled)
.\install.ps1

What this installs:

• ✅ WinGet Package Manager - Windows package management with comprehensive error handling
• ✅ 30+ Development Tools - IDEs, utilities, and development environments via WinGet
• ✅ WSL Environment - Ubuntu 22.04 with Node.js, .NET SDK, Azure CLI, 1Password CLI
• ✅ Cascadia Code Fonts - Programming fonts with ligatures and registry integration
• ✅ VSCode Extensions - 31+ curated extensions for full-stack development
• ✅ Global NPM Packages - Essential development packages via Fast Node Manager (fnm)

Step 2: Configure Complete Development Environment

# Interactive configuration wizard
.\configure.ps1

What this configures:

• ✅ Claude Code for WSL - Bash shell optimization with development tools
• ✅ 1Password Integration - Secure environment variables for Windows and WSL
• ✅ Git Identity Management - Separate identities for user and Claude Code commits
• ✅ Symbolic Link Creation - Centralized configuration management
• ✅ PowerShell Profile - Oh My Posh themes and productivity functions
• ✅ Interactive Guidance - Step-by-step explanations and confirmations

Advanced Configuration Options

# Automated deployment (skip confirmations)
.\configure.ps1 -SkipConfirmation

# Force overwrite existing configurations
.\configure.ps1 -Force

# Selective installation options
.\install.ps1 -SkipWinGet          # Skip package installation
.\install.ps1 -SkipExtensions      # Skip VSCode extensions
.\install.ps1 -SkipNpmPackages     # Skip global npm packages

🏗️ Architecture and Components

Development Stack Overview

WSL Development Environment

The mandatory WSL integration provides a comprehensive Linux development environment:

System Tools

• Node.js LTS: Latest stable version via NodeSource repository
• .NET SDK: Microsoft .NET development platform for cross-platform development
• Azure CLI: Complete Azure command-line tools and authentication
• 1Password CLI: Secure credential retrieval and environment variable management

Development Tools

• Essential NPM Packages: prettier, markdownlint-cli, typescript, eslint
• Build Tools: make, build-essential, curl, wget, git
• Claude Code Integration: Bash shell with tool permissions and environment optimization

Installed Package Categories

⚙️ Configuration Details

Centralized Configuration Management

The setup creates symbolic links from system locations to repository files, enabling:

• Live Configuration Updates: Changes to repository files immediately affect system settings
• Version Control Integration: All configuration changes tracked in Git
• Multi-Machine Consistency: Same configurations across different development environments
• Easy Restoration: Simple repository checkout restores all settings

Configuration Components

Enhanced Configuration Features

• Multi-Path Support: Automatically detects Windows Terminal installation methods (standard vs. Microsoft Store)
• Developer Mode Detection: Uses symbolic links without Administrator privileges when enabled
• Backup Management: Creates backups before overwriting existing configurations
• Error Recovery: Comprehensive error handling with clear recovery instructions
• Interactive Guidance: Step-by-step configuration with detailed explanations

🤖 Claude Code Integration

9 Specialized AI Agents

The repository includes comprehensive Claude Code configuration with domain-specific agents:

WSL-Optimized Configuration

The Claude Code setup is optimized for WSL development:

{
  "shell": "/bin/bash",
  "env": {
    "SHELL": "/bin/bash",
    "CLAUDE_SHELL": "/bin/bash",
    "WSL_DISTRO_NAME": "Ubuntu-22.04"
  },
  "terminal": {
    "shell": "wsl",
    "args": ["-d", "Ubuntu-22.04", "bash", "-l"]
  },
  "permissions": {
    "allow": [
      "Bash(prettier:*)",
      "Bash(markdownlint:*)",
      "Bash(git:*)",
      "Bash(dotnet:*)",
      "Bash(npm:*)"
    ]
  }
}

MCP Server Configuration

Modern MCP servers configured for enhanced functionality:

• filesystem: File operations with directory access controls
• memory: Persistent conversation context and memory management
• sequential-thinking: Structured reasoning and problem-solving workflows
• context7: Advanced context management and intelligent retrieval

📚 Usage Examples

Common Development Workflows

Setting Up a New Project

# Navigate to your project directory
oss my-new-project

# Use Claude Code to initialize project structure
# Claude Code will automatically use appropriate agents based on project type

# Open in VSCode with all extensions and configuration
code .

# Start development with all tools configured

PowerShell Profile Features

# Quick navigation functions
oss [subdir]              # Navigate to ~/src/oss/[subdir]
work [subdir]             # Navigate to ~/src/ofm/[subdir]

# Visual Studio integration
sln                       # Open solution file in current directory

# VSCode extension management
backup-vs                 # Export currently installed extensions to repository

# Git configuration
Set-GitUser               # Interactive Git user configuration

# 1Password integration
Set-1PEnvVar -Key "API_KEY" -Value "secret123"  # Secure environment variable storage

Claude Code Agent Usage

# Agents automatically activate based on context and task
# Examples of agent specialization:

# C# development tasks → csharp agent
# Azure DevOps operations → azure-devops agent
# Documentation tasks → markdown agent
# Unit testing → mstest agent
# README management → readme-maintainer agent

Advanced Setup Scripts

Azure Service Principal Setup

.\settings\az\setup-azure-service-principal.ps1

• Interactive Azure CLI authentication and connection
• Service principal creation with Contributor role assignment
• 1Password credential storage for secure environment variables
• Connection testing and validation with detailed feedback

1Password Environment Vault

.\settings\1password\setup-environment-vault.ps1

• Secure environment variable management across Windows and WSL
• CLI integration setup with service account configuration
• Vault creation and permission management
• PowerShell and WSL integration for seamless access

📁 Directory Structure

new-windows-dev-pc/
├── 📄 install.ps1                         # Main installation script
├── 📄 configure.ps1                       # Configuration script  
├── 📄 LICENSE                             # MIT License
├── 📄 CLAUDE.md                           # Claude Code guidance
├── 📂 fonts/
│   └── 📦 CascadiaCode.zip               # Developer fonts with ligatures
├── 📂 installs/                          # Installation modules
│   ├── 📄 install-winget.ps1             # WinGet installation with fallbacks
│   ├── 📄 npm-global.ps1                 # Global npm packages
│   ├── 📄 vscode.ps1                     # VSCode extensions installer  
│   ├── 📄 winget.ps1                     # WinGet package installer
│   ├── 📄 wsl-tools.sh                   # WSL development environment
│   └── 📋 README.md                      # Installation documentation
├── 📂 prompts/                           # Development workflow prompts
│   └── 📄 npm-global-packages-management.md
└── 📂 settings/                          # Configuration files and scripts
    ├── 📂 1password/                     # Secure credential management
    │   └── 📄 setup-environment-vault.ps1
    ├── 📂 az/                            # Azure integration scripts
    │   └── 📄 setup-azure-service-principal.ps1
    ├── 📂 claude/                        # Claude Code configuration
    │   ├── 📄 configure-claude-windows-11.ps1  # Setup script
    │   ├── ⚙️ settings.json              # Windows configuration
    │   ├── ⚙️ settings-wsl.json          # WSL-optimized configuration
    │   ├── 📂 agents/                    # 9 specialized AI agents
    │   ├── 📂 config/                    # Configuration files
    │   ├── 📂 templates/                 # Project templates
    │   └── 📋 README.md                  # Claude Code documentation
    ├── 📂 etc/                           # System configuration
    │   ├── 📄 hosts                      # Network hosts configuration
    │   └── 📋 README.md                  # Hosts file management guide
    ├── 📂 git/                           # Git configuration
    │   ├── 📄 configure-git-windows.ps1  # Configuration script
    │   ├── ⚙️ .gitconfig                # Git settings with VSCode integration
    │   └── 📋 README.md                  # Git configuration guide
    ├── 📂 markdownlint/                  # Markdown linting
    │   ├── 📄 configure-markdownlint-windows.ps1
    │   └── ⚙️ .markdownlint.json        # Linting rules
    ├── 📂 npm/                           # NPM configuration
    │   └── 📄 global-packages            # Global package list
    ├── 📂 nuget/                         # NuGet configuration
    │   ├── 📄 configure-nuget-windows.ps1
    │   └── ⚙️ NuGet.Config               # Package sources
    ├── 📂 pwsh/                          # PowerShell configuration
    │   ├── 📄 configure-pwsh-windows.ps1 # Configuration script
    │   ├── ⚙️ Microsoft.PowerShell_profile.ps1  # Enhanced profile
    │   ├── 🎨 .theme.omp.json           # Oh My Posh theme
    │   ├── 📄 1p-env-vars.ps1            # 1Password integration
    │   └── 📋 README.md                  # PowerShell configuration guide
    ├── 📂 vscode/                        # VSCode configuration
    │   ├── 📄 configure-vscode-windows.ps1  # Configuration script
    │   ├── ⚙️ settings.json              # VSCode settings
    │   ├── ⚙️ keybindings.json           # Custom keybindings
    │   ├── 📄 extensions                 # Extension list (31+)
    │   └── 📋 README.md                  # VSCode configuration guide
    ├── 📂 windows-terminal/               # Windows Terminal configuration
    │   ├── 📄 configure-windows-terminal.ps1  # Configuration script
    │   ├── ⚙️ settings.json              # Terminal configuration
    │   └── 📋 README.md                  # Terminal configuration guide
    ├── 📂 wsl/                           # WSL-specific configuration
    │   ├── 📄 configure-1password-wsl.sh # 1Password CLI setup for WSL
    │   └── 📄 1p-env-vars.sh             # Environment variable loading
    └── 📂 visual-studio/                 # Visual Studio configuration
        └── ⚙️ .vsconfig                  # Workload configuration

🔍 Troubleshooting

Common Issues and Solutions

Advanced Troubleshooting Commands

# System diagnostics
Get-ExecutionPolicy                        # Check PowerShell execution policy
wsl --list --verbose                       # Check WSL status and version
winget --version                           # Verify WinGet installation

# Configuration validation  
Get-Item ~/.gitconfig | Select-Object Target    # Check Git config symlink
Test-Path $PROFILE                              # Verify PowerShell profile exists
code --list-extensions                          # List installed VSCode extensions

# Force reconfiguration
.\configure.ps1 -Force                     # Overwrite existing configurations

Detailed Documentation

Each component includes comprehensive documentation:

🤝 Contributing Guidelines

Development Workflow

1. Fork the Repository: Create your own fork for development
2. Create Feature Branch: Use descriptive branch names (feature/add-python-support)
3. Test Changes: Verify functionality across Windows 10/11 and WSL environments
4. Update Documentation: Ensure README files reflect your changes
5. Submit Pull Request: Provide clear description of changes and testing performed

Code Standards

PowerShell Scripts

• Use PascalCase for functions and $camelCase for variables
• Include comprehensive error handling with clear error messages
• Add help documentation with Get-Help compatible comments
• Test with PowerShell 5.1 and 7+ for compatibility

Documentation

• Follow CommonMark/GitHub Flavored Markdown standards
• Use consistent heading hierarchy and formatting
• Include code examples with syntax highlighting
• Update table of contents for structural changes

Configuration Files

• Validate JSON syntax before committing
• Use consistent indentation (2 spaces for JSON, 4 for PowerShell)
• Include comments where helpful (for non-JSON files)
• Test configuration changes in clean environment

Testing Guidelines

Minimum Testing Requirements

• Test on clean Windows 10 and Windows 11 installations
• Verify WSL integration works correctly
• Ensure all symbolic links are created properly
• Validate 1Password integration (if applicable)
• Test both fresh installations and updates

Regression Testing

• Verify existing functionality isn't broken
• Test edge cases and error conditions
• Validate rollback procedures work correctly
• Check cross-component interactions

Issue Reporting

When reporting issues, please include:

• Environment Details: Windows version, PowerShell version, WSL status
• Reproduction Steps: Clear steps to reproduce the issue
• Expected vs. Actual Behavior: What should happen vs. what does happen
• Error Messages: Full error text and stack traces
• Configuration: Relevant configuration files and settings

🚀 Ready to Get Started?

Transform your Windows development environment in just two commands:

# Step 1: Install all development tools and WSL environment
.\install.ps1

# Step 2: Configure everything for optimal development workflow  
.\configure.ps1

Result: A complete Windows + WSL development setup with Claude Code AI integration, 30+ development tools, 31+ VSCode extensions, and 9 specialized AI agents - all configured and ready to use! 🎉