Framework Evolution: Architecture Improvements and Mission Clarity

How progressive disclosure and mission-driven design transformed onboarding from manual multi-step process into platform-specific automation that handles prerequisite installation, system optimization, and framework configuration.

Chris Groves

Chris Groves

— 6 min read
Framework evolution: Progressive disclosure from simple setup to complex architecture

The Setup Problem

Framework onboarding used to require reading multiple pages of documentation before running any commands. Users had to understand symlink architecture, directory structures, and file locations before they could begin. The setup guide started with concepts rather than action, creating unnecessary friction between download and first use.

This violated core principles of progressive disclosure in user experience design. Research shows users benefit from initially simplified feedback that helps them build working mental models. Technical details should reveal gradually based on need, not front-loaded as prerequisites.

The documentation also suffered from mission drift. The About page listed features and capabilities but buried the fundamental question: why does this exist? Product positioning research consistently shows mission-driven messaging creates stronger connection than feature lists. The human brain remembers purpose and emotion, not technical specifications.

Progressive Disclosure in Practice

The solution restructures onboarding around action, not explanation. The new flow centers on /setup - a single command that orchestrates platform detection, prerequisite installation, and framework configuration. Users make strategic decisions ("Add Windows Defender exclusions? Y/N"), Claude handles technical implementation.

This reflects the core philosophy embedded throughout the framework: Claude does technical work, you make strategic choices. Self-service automation research demonstrates this pattern reduces friction while improving satisfaction. Users maintain control through decision points but avoid manual technical operations.

The documentation now follows progressive disclosure patterns:

  • Quick start - Immediate action with minimal context
  • Command reference - What /setup does and why
  • Architecture docs - Deep technical details for customization

This mirrors onboarding automation best practices where users track progress at their own pace without dependency on support. Each layer reveals more detail, but the previous layer remains functional on its own.

Cross-Platform Setup Automation

Framework accessibility requires platform-agnostic deployment. The automated setup handles Windows, Linux, and macOS with platform-specific optimizations while maintaining consistent user experience.

Windows Setup Scripts

PowerShell automation for WSL2 installation and optimization:

Script 01: 01-install-wsl.ps1

  • Enables Windows Subsystem for Linux feature
  • Enables Virtual Machine Platform feature
  • Forces restart to complete installation

Script 02: 02-install-ubuntu-and-harden.ps1

  • Installs Ubuntu 24.04 LTS with progress tracking
  • Generates .wslconfig with system-specific optimizations (50% RAM, N-2 processors)
  • Optionally adds Windows Defender exclusions for WSL directories
  • Configures WSL2 as default version

Script 03: 03-install-prerequisites.ps1

  • Installs git, curl, unzip, ca-certificates
  • Installs Bun JavaScript runtime
  • Installs GitHub CLI and git-lfs
  • Configures PATH for local binaries

Script 04: 04-install-docker.ps1 (Optional)

  • Downloads and installs Docker Desktop
  • Configures WSL2 backend integration
  • Provides post-install configuration instructions

All scripts can be downloaded and run directly from GitHub without cloning the repository first. Each script checks prerequisites, prompts for confirmation, backs up existing configurations, and provides clear next steps.

Linux Setup Scripts

Bash automation with multi-distribution support:

Script 01: 01-install-prerequisites.sh

  • Auto-detects distribution (Ubuntu, Debian, RHEL, Fedora, Arch)
  • Installs system packages via appropriate package manager
  • Installs Bun JavaScript runtime
  • Installs GitHub CLI and git-lfs
  • Configures shell PATH

Script 02: 02-install-docker.sh (Optional)

  • Installs Docker Engine (native daemon, no GUI)
  • Installs Docker Compose plugin
  • Adds user to docker group
  • Configures Docker to start on boot

Script 03: 03-optimize-system.sh (Optional)

  • Increases file watch limits (prevents "too many open files")
  • Optimizes Docker daemon settings (log rotation, storage driver)
  • Configures swap settings for development workloads
  • Sets system limits for files and processes

Linux scripts handle package manager detection automatically (apt/dnf/yum/pacman) and adapt to distribution-specific requirements while maintaining identical workflows.

macOS Setup Scripts

Bash automation with architecture detection:

Script 01: 01-install-prerequisites.sh

  • Detects and installs Homebrew if missing
  • Installs git via Homebrew
  • Installs Bun JavaScript runtime
  • Installs GitHub CLI and git-lfs
  • Configures shell PATH

Script 02: 02-install-docker.sh (Optional)

  • Detects Apple Silicon vs Intel architecture
  • Offers Docker Desktop (GUI) or Colima (CLI) options
  • Handles architecture-specific configurations
  • Provides platform-appropriate installation paths

macOS scripts detect Homebrew presence and install if needed, ensuring consistent developer experience across both Apple Silicon and Intel architectures.

The /setup Command

After platform prerequisites are installed, the /setup command completes framework configuration:

  1. Detects platform (Windows/WSL, macOS, Linux)
  2. Optimizes WSL2 configuration (Windows only)
  3. Validates framework structure
  4. Creates .env from template
  5. Configures privacy settings (disables telemetry)
  6. Creates symlinks to ~/.claude (backs up existing files)
  7. Installs dependencies
  8. Runs health check
  9. Marks installation complete

The command is idempotent - safe to run multiple times. It detects existing configurations and only makes necessary changes. Users can verify installation with /setup --check or repair issues with /setup --repair.

Complete step-by-step installation instructions for each platform are available in the Setup Guide. Rather than manually copying commands, the guide provides platform-specific scripts that can be downloaded and executed directly from GitHub.

This approach mirrors enterprise software deployment best practices where automation removes manual configuration errors while maintaining user control. Scripts handle technical complexity while users make strategic decisions.

Mission Before Features

The About page transformation moved from feature enumeration to mission articulation. The new structure:

Why - Democratizing access to consulting expertise
How - Modular skills and specialized agents
What - Specific capabilities and commands

This follows Simon Sinek's "Start With Why" principle, validated by McKinsey research showing mission-aligned messaging outperforms feature-focused alternatives by 30%. Companies like Tesla demonstrate this pattern: environmental mission attracts buyers, performance retains them.

The framework's mission centers on access over revenue. Traditional consulting creates artificial scarcity through hourly billing and exclusive engagements. This framework inverts the model—democratizing expertise through productized services that anyone can deploy.

AI enables this shift. Where boutique firms previously served enterprise clients exclusively, AI-driven consulting platforms now deliver Fortune 500 methodologies at significantly lower cost. The framework takes this further—open source distribution with zero licensing fees.

Documentation as Code

Framework documentation lives in version control alongside implementation. Changes to capabilities require corresponding documentation updates in the same commit. This documentation-as-code approach keeps content synchronized with reality.

The pattern prevents documentation drift—the common problem where guides describe systems that no longer exist. By treating documentation with the same rigor as code (pull requests, reviews, automated validation), accuracy becomes enforced rather than aspirational.

Markdown enables this workflow. Every major development platform supports it natively. Documentation changes review like code changes, with diffs showing exactly what information updated. The Git history becomes the changelog, eliminating manual version tracking.

Content Creation Workflow

The /write command transformed content development into a structured five-phase process with quality gates at each stage. Rather than freeform drafting, content follows a consistent workflow:

Phase 1 - RESEARCH: Gather and validate 10+ sources before drafting begins
Phase 2 - DRAFT: Apply brand voice templates and content standards
Phase 3 - QA: Automated review must achieve 5.0/5.0 rating to proceed
Phase 4 - VISUALS: Optional image generation for supporting graphics
Phase 5 - OUTPUT: Export to requested format (Markdown, HTML, etc.)

Each phase includes gates that prevent advancement until criteria are met. If QA scores below 5.0, content returns to revision. This enforces quality standards automatically rather than relying on manual review.

The implementation follows the productized consulting model—standardized workflow prevents scope creep while delivering repeatable results. Each content piece follows identical steps, eliminating variability and potential errors.

Implementation Pattern: Quick Wins First

The refresh prioritized visible improvements over internal refactoring:

Immediate impact changes:

  • Platform-specific setup scripts replacing manual installation steps
  • Single /setup command for framework configuration
  • Mission-focused About page replacing feature list
  • Automated Ghost publishing removing manual CMS work

Deferred optimization:

  • Internal code restructuring
  • Performance improvements
  • Advanced features

This reflects customer onboarding research showing early value delivery increases retention. Users experience benefits immediately rather than waiting for complete overhauls. Technical debt gets addressed, but not at the cost of user-facing improvements.

The pattern also demonstrates pragmatic incrementalism. Perfect internal architecture provides no value if users abandon the framework before discovering it. Ship improvements that matter to adoption, then refine underlying systems.

Key Takeaways

Progressive disclosure works: Start with action, reveal complexity based on need. The setup flow gets users operational before explaining architecture.

Platform-specific automation removes barriers: Tailored scripts for Windows, Linux, and macOS handle platform differences while maintaining consistent patterns. Users get optimized experiences without manual troubleshooting.

Mission before features: Why you exist creates stronger connection than what you offer. The About page leads with democratizing access, not capability lists.

Automate the technical, preserve the decisions: Setup scripts handle implementation, users control strategic choices. This pattern scales across the framework.

Documentation is code: Version control prevents drift. Changes to capabilities require corresponding documentation updates in the same commit.

Quick wins drive adoption: Ship user-facing improvements before internal refactoring. Early value delivery increases engagement.

The framework continues evolving toward its core mission: making sophisticated consulting methodologies accessible to anyone who needs them. These changes remove friction from that path.

The Intelligence Adjacent framework is free and open source. If this helped you, consider joining as a Lurker (free) for methodology guides, or becoming a Contributor ($5/mo) for implementation deep dives and to support continued development.

Sources

User Onboarding & Automation

Progressive Disclosure

Mission-Driven Positioning

Developer Documentation

Democratizing Consulting

Productized Services

Infrastructure Automation

Read more