dev-setup: Zero to Productive in 5 Minutes

Transform developer onboarding from days to minutes.

🎯 Goal

Reduce developer environment setup time from 2-5 days to 30 minutes total with developers productive in just 5 minutes.

Current Reality (Manual Setup)

Day 1: Install tools, configure shell                   (4-6 hours)
Day 2: Setup Node, Python, package managers              (3-4 hours)
Day 3: Clone repos, install deps, configure IDE          (4-6 hours)
Day 4: Git config, SSH keys, authenticate services       (2-3 hours)
Day 5: Troubleshoot "works on my machine" issues         (3-5 hours)
──────────────────────────────────────────────────────────────────
TOTAL: 2-5 DAYS of wasted developer time ❌

With dev-setup (Automated)

Minute 0-5:   Critical tools → Developer can code       ✅ PRODUCTIVE
Minute 5-15:  Full dev stack (background)               ✅ COMPLETE
Minute 15-30: Polish & optional tools (background)      ✅ PROFESSIONAL
──────────────────────────────────────────────────────────────────
TOTAL: 30 MINUTES, productive after 5 ✓

✨ Features

⚡ Parallel Installation: 8+ concurrent tasks, ~8x speedup
📦 Incremental Stages: Stage 1 (5min critical) → Stage 2 (10min full) → Stage 3 (15min polish)
🔒 Version Locking: Brewfile.lock.json + versions.lock = zero "works on my machine"
✅ Verification: devsetup verify checks all tools match expected versions
🔄 Idempotent: Safe to re-run, skips existing tools
🎨 Rich UI: Progress bars, colors, clear status indicators
🚀 Background Execution: Keep working while installation completes

🏗️ Architecture

Three-Stage Progressive Setup

┌──────────────────────────────────────────────────────────────┐
│ STAGE 1: CRITICAL PATH (5 min) - BLOCKING                    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │
│ ✓ Homebrew                                                   │
│ ✓ Git + SSH                                                  │
│ ✓ Node + pnpm (parallel)                                     │
│ ✓ Python + uv (parallel)                                     │
│ ✓ Zed/VS Code (parallel)                                     │
│ ✓ Shell config                                               │
│                                                              │
│ 👨‍💻 DEVELOPER CAN NOW CODE                                    │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ STAGE 2: FULL STACK (10 min) - BACKGROUND                    │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │
│ ⚡ All Homebrew packages (8 parallel)                         │
│ ⚡ Zsh plugins (6 parallel clones)                            │
│ ⚡ Flutter wrapper + git config                               │
│ ⚡ Starship prompt configuration                              │
│                                                              │
│ 👨‍💻 Developer continues working...                            │
└──────────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────────┐
│ STAGE 3: POLISH (15 min) - BACKGROUND                        │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │
│ ⚡ Nerd Fonts                                                 │
│ ⚡ Optional AI CLIs (Claude, Codex, Gemini)                   │
│ ⚡ Docker, Kubernetes tools                                   │
│                                                              │
│ 🎉 Complete professional environment                         │
└──────────────────────────────────────────────────────────────┘

Tech Stack

Language: Go 1.21+ (single binary, fast, concurrent)
CLI Framework: Cobra (professional CLI with subcommands)
Config Format: YAML (stages) + TOML (versions.lock)
Package Manager: Homebrew (with Brewfile for declarative deps)
Parallel Execution: Goroutines + semaphore pattern (8 concurrent max)

📦 What Gets Installed

Stage 1: Critical (5 min)

Homebrew (if missing)
Git with basic config
Node.js + pnpm (parallel)
Python + uv (parallel)
Zed editor (parallel)
Shell PATH configuration

Stage 2: Full Stack (10 min, background)

Dev tools: git-lfs, wget, jq, ripgrep, fd, bat, eza
Starship prompt with Nerd Font symbols
Zsh plugins: completions, syntax highlighting, autosuggestions, history search
Flutter wrapper: flutterw command
Git config templates: Review before applying

Stage 3: Polish (15 min, background)

Hack Nerd Font: For proper icon display
AI CLIs: Claude Code, Codex, Gemini (best-effort)
Docker Desktop (optional, large download)
Modern CLI tools: fzf, tree, htop, tldr

🚀 Quick Start

One-Line Install

curl -fsSL https://raw.githubusercontent.com/rkinnovate/dev-setup/main/bootstrap.sh | bash

Or Clone and Build

git clone https://github.com/rkinnovate/dev-setup
cd dev-setup
make install
devsetup install

📖 Usage

Commands

# Install complete environment (3 stages)
devsetup install

# Fast mode (Stage 1 only - 5 minutes)
devsetup install --fast

# Skip optional tools (Stages 1 & 2 only)
devsetup install --skip-optional

# Preview what would be installed
devsetup install --dry-run

# Verify environment matches versions.lock
devsetup verify

# Auto-fix any mismatches
devsetup verify --fix

# Run diagnostics
devsetup doctor

# Check installation status
devsetup status

# Update versions.lock with current versions
devsetup update --capture-versions

# Show version
devsetup --version

After Installation

Restart Terminal: source ~/.zshrc or close/reopen terminal
Verify: devsetup verify

Set Git Identity:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Switch Terminal Font: Set to "Hack Nerd Font" for proper icons
Authenticate AI CLIs (if installed):
```
claude auth
codex login
gemini login
```

🔐 Environment Consistency

Version Locking

All dependencies are version-locked for exact reproducibility:

Homebrew packages: Brewfile + Brewfile.lock.json
Git repositories: versions.lock (commit SHAs or tags)
Custom tools: versions.lock (version pinned)

Verification

# Check all tools match expected versions
devsetup verify

# Output:
✓ git@2.43.0
✓ node@20.10.0
✗ pnpm@8.11.0 (expected: 8.10.5)  # Mismatch!

Environment verification FAILED (1 error)
Run 'devsetup verify --fix' to repair

Fixing Mismatches

devsetup verify --fix
# Automatically reinstalls mismatched tools to correct versions

📊 Performance

Time Breakdown

Stage	Time	Blocking	What Happens
Stage 1	5 min	✅ Yes	Install critical tools - developer can code after
Stage 2	10 min	❌ No	Full dev stack installs in background
Stage 3	15 min	❌ No	Polish/optional tools install in background
Total	30 min	5 min	Productive in 5 minutes ✓

Speedup Techniques

Parallel Execution: 8 concurrent tasks (8x speedup)

# tasks with same parallel_group run simultaneously
parallel_group: "homebrew-tools"

Shallow Git Clones: --depth=1 (5x faster)

git clone --depth=1 --single-branch <repo>

Background Stages: Developer works while Stages 2 & 3 complete
Idempotency: Skip already-installed tools (instant on re-run)

🛠️ Development

Project Structure

dev-setup/
├── cmd/
│   └── devsetup/
│       └── main.go              # CLI entry point
├── internal/
│   ├── config/
│   │   ├── models.go            # Config structs
│   │   └── loader.go            # YAML/TOML parsing
│   ├── installer/
│   │   ├── parallel.go          # Parallel executor (core engine)
│   │   └── installer.go         # Stage orchestrator
│   ├── ui/
│   │   └── progress.go          # Progress bars, colors
│   └── verify/
│       └── checker.go           # Version verification
├── configs/
│   ├── stage1.yaml              # Critical path (5 min)
│   ├── stage2.yaml              # Full stack (10 min)
│   └── stage3.yaml              # Polish (15 min)
├── Brewfile                     # Homebrew packages
├── Brewfile.lock.json           # Homebrew version lock
├── versions.lock                # Non-Homebrew version lock
├── bootstrap.sh                 # One-line installer
├── Makefile                     # Build automation
└── go.mod                       # Go dependencies

Build Commands

# Build for current architecture
make build

# Build for all architectures
make build-all

# Install to ~/.local/bin
make install

# Run tests
make test

# Run linter
make lint

# Clean build artifacts
make clean

# Build and run
make run

# Build and dry-run
make dry-run

Adding New Tools

To Brewfile (Homebrew packages):

# In Brewfile
brew "newtool"

# Then lock version:
brew bundle dump --force
git add Brewfile.lock.json

To Stage Config (Custom installs):

# In configs/stage2.yaml
- name: "Install custom tool"
  command: |
    curl -fsSL https://example.com/install.sh | sh
  parallel_group: "custom-tools"
  required: false
  timeout: 60s

To versions.lock (Version tracking):

# In versions.lock
[tools.newtool]
version = "1.2.3"
installer = "https://example.com/install.sh"
verify_command = "newtool --version"

🔒 Package Manager Policy

⚠️ STRICTLY ENFORCED ⚠️

Language	Required	Forbidden
Python	`uv`	pip, pipenv, poetry, conda
Node.js	`pnpm`	npm, yarn, bun

Lockfiles:

Python: uv.lock
Node.js: pnpm-lock.yaml

📝 Configuration Files

Stage Configuration (YAML)

name: "Stage Name"
timeout: 300s
parallel: true

tasks:
  - name: "Task name"
    command: "shell command to run"
    parallel_group: "group-name"  # Empty = sequential
    required: true                 # Fail stage if fails
    timeout: 60s
    retry_count: 2
    condition: "command -v tool"   # Skip if condition fails

Version Lock (TOML)

[metadata]
schema_version = "1.0"
platform = "darwin"
updated = 2025-12-22T00:00:00Z

[homebrew.formulas]
git = { version = "2.43.0", tap = "homebrew/core" }

[git_repos.flutter-wrapper]
url = "https://github.com/user/repo"
commit = "abc123"
path = "~/.local/share/dev-setup/flutter-wrapper"
stage = 2

🎓 Key Concepts

Idempotency

All operations are safe to re-run:

devsetup install  # First run: installs everything
devsetup install  # Second run: skips existing, instant

Progressive Enhancement

Developer productive immediately, environment completes in background:

[5 min]  Stage 1 completes → Developer clones repos, starts coding
[15 min] Stage 2 completes → Full dev stack ready
[30 min] Stage 3 completes → Professional polish complete

Version Locking

Identical versions on all machines:

# Developer A (Monday):
git@2.43.0, node@20.10.0, pnpm@8.10.5

# Developer B (Friday):
git@2.43.0, node@20.10.0, pnpm@8.10.5  # Exact same!

🆘 Troubleshooting

Installation Issues

# Check what's wrong
devsetup doctor

# Re-run specific stage
devsetup install  # Idempotent, safe to re-run

# Verbose output
export DEBUG=1
devsetup install

Version Mismatches

# Identify mismatches
devsetup verify

# Fix automatically
devsetup verify --fix

Common Issues

"Homebrew not found": Ensure /opt/homebrew/bin or /usr/local/bin in PATH
"Permission denied": Homebrew install requires sudo password
"Network timeout": Check internet connection, retry with longer timeout
"Version mismatch": Run devsetup verify --fix

📈 Success Metrics

Before (Manual)

⏱️ Time to first commit: 2-5 days
💰 Cost per developer: $1,000-2,500
🐛 "Works on my machine" issues: Common
😫 Developer frustration: High

After (Automated)

⏱️ Time to first commit: 5 minutes ✅
💰 Cost per developer: $31 ✅
🐛 "Works on my machine" issues: Zero ✅
😊 Developer satisfaction: High ✅

ROI

Savings: $1,000-2,500 per developer
Team of 10 devs/year: $10K-25K saved
Development cost: ~$10K
Payback: First 4-10 developers

🤝 Contributing

See AGENTS.md for contribution guidelines including:

Coding standards
Documentation requirements
Commit message format (Conventional Commits)
Testing expectations

📄 License

MIT License - see LICENSE file for details.

🔗 Links

GitHub: https://github.com/rkinnovate/dev-setup
Issues: https://github.com/rkinnovate/dev-setup/issues
Releases: https://github.com/rkinnovate/dev-setup/releases

Built with ❤️ by RK Innovate

Transforming developer onboarding from days to minutes.

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
cmd/devsetup		cmd/devsetup
configs		configs
external		external
global_conf		global_conf
internal		internal
third-party		third-party
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
bootstrap.sh		bootstrap.sh
go.mod		go.mod
go.sum		go.sum

RKInnovate/dev-setup

Folders and files

Latest commit

History

Repository files navigation

dev-setup: Zero to Productive in 5 Minutes

🎯 Goal

Current Reality (Manual Setup)

With dev-setup (Automated)

✨ Features

🏗️ Architecture

Three-Stage Progressive Setup

Tech Stack

📦 What Gets Installed

Stage 1: Critical (5 min)

Stage 2: Full Stack (10 min, background)

Stage 3: Polish (15 min, background)

🚀 Quick Start

One-Line Install

Or Clone and Build

📖 Usage

Commands

After Installation

🔐 Environment Consistency

Version Locking

Verification

Fixing Mismatches

📊 Performance

Time Breakdown

Speedup Techniques

🛠️ Development

Project Structure

Build Commands

Adding New Tools

To Brewfile (Homebrew packages):

To Stage Config (Custom installs):

To versions.lock (Version tracking):

🔒 Package Manager Policy

📝 Configuration Files

Stage Configuration (YAML)

Version Lock (TOML)

🎓 Key Concepts

Idempotency

Progressive Enhancement

Version Locking

🆘 Troubleshooting

Installation Issues

Version Mismatches

Common Issues

📈 Success Metrics

Before (Manual)

After (Automated)

ROI

🤝 Contributing

📄 License

🔗 Links

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 2

Uh oh!

Languages

Packages