If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/boxen/our-boxen shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 8y ago

• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 8y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live boxen/our-boxen repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/boxen/our-boxen.

What it runs against: a local clone of boxen/our-boxen — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in boxen/our-boxen | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 2983 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of boxen/our-boxen. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/boxen/our-boxen.git
#   cd our-boxen
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of boxen/our-boxen and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "boxen/our-boxen(\\.git)?\\b" \\
  && ok "origin remote is boxen/our-boxen" \\
  || miss "origin remote is not boxen/our-boxen (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "manifests/site.pp" \\
  && ok "manifests/site.pp" \\
  || miss "missing critical file: manifests/site.pp"
test -f "Puppetfile" \\
  && ok "Puppetfile" \\
  || miss "missing critical file: Puppetfile"
test -f "script/boxen" \\
  && ok "script/boxen" \\
  || miss "missing critical file: script/boxen"
test -f "config/boxen.rb" \\
  && ok "config/boxen.rb" \\
  || miss "missing critical file: config/boxen.rb"
test -f "hiera/common.yaml.example" \\
  && ok "hiera/common.yaml.example" \\
  || miss "missing critical file: hiera/common.yaml.example"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2983 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2953d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/boxen/our-boxen"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Boxen is a macOS provisioning framework that uses Puppet to automate development environment setup across a team or organization. It installs and configures developer tools, languages, package managers, and project-specific dependencies declaratively, replacing manual setup steps with reproducible infrastructure-as-code. This repository (our-boxen) is the template other organizations fork to create their own team-specific Boxen configurations. Monolithic template structure: manifests/site.pp is the Puppet entry point, modules/people and modules/projects contain reusable Puppet modules for user and project setup, hiera/ holds environment-specific configuration (YAML), script/ contains shell-based bootstrap tooling, and spec/ has RSpec tests for CLI and directory structure validation. Configuration flows through config/boxen.rb and config/basic.rb.

Engineering teams and organizations that need to standardize macOS developer machine setup across multiple engineers. They want to eliminate 'works on my machine' problems, onboard new engineers faster, and keep development environments consistent without manual installation steps.

Actively maintained but showing signs of maturity plateau. The repo has CI via .travis.yml, RSpec test suite in spec/, and Puppetfile dependency management. However, the lack of recent commit dates visible and the 'Copy me for your team' framing suggest this is a stable template rather than a rapidly evolving project. Production-ready for macOS teams willing to maintain Puppet manifests.

Heavily dependent on Ruby, Puppet ecosystem, and macOS-specific tooling (Xcode Command Line Tools requirement); breaking changes in Ruby versions or Puppet modules could impact all dependent installations. The codebase explicitly conflicts with existing rvm, rbenv, chruby, homebrew, and nvm installations, making it risky on pre-configured machines. Single-organization template means community support may be limited compared to standalone tools.

This is a template repository, so 'current work' is distributed across forks. The repo itself appears to be stable reference material rather than actively developed. Users are expected to fork this and customize it for their organization's needs (see docs/personal-configuration.md and docs/modules.md for extension patterns).

git clone https://github.com/boxen/our-boxen /opt/boxen/repo && cd /opt/boxen/repo && git remote rm origin && git remote add origin <your-fork-url> && git push -u origin master && ./script/boxen

Daily commands: ./script/boxen runs the full provisioning sequence after bootstrap. ./script/boxen-bootstrap handles initial setup. See script/ directory for entry points.

• manifests/site.pp — Primary Puppet manifest entry point that orchestrates all machine configuration and applies the full Boxen setup.
• Puppetfile — Declares all Puppet module dependencies and their versions; changes here affect entire team's environment provisioning.
• script/boxen — Main bootstrap and execution script that developers run to provision their machines; critical for understanding the provisioning workflow.
• config/boxen.rb — Core Boxen configuration file defining the provisioning behavior, paths, and system-level settings.
• hiera/common.yaml.example — Template for team-wide configuration variables that control which tools and services are installed on all machines.
• README.md — Documents setup requirements, conflicts to avoid, and getting-started instructions for all team members.
• Gemfile — Ruby gem dependencies for the Boxen framework and build/test tools; required for development environment.

• Boxen Framework (script/boxen) (Ruby, Thor gem, Boxen gem) — Entry point that manages pre-checks, loads configuration, invokes Puppet, and reports results.
  • Failure mode: Provisioning halts; developer receives error message and must resolve conflicts (e.g., existing rvm, GitHub username with dash)
• undefined — undefined

Add a new project to provision on all machines

1. Define the project class in the projects module manifest (modules/projects/manifests/all.pp)
2. Add the project class to the site manifest includes (manifests/site.pp)
3. Add an RSpec test to verify the project setup (spec/localhost/packages_spec.rb)
4. Document the project configuration in the modules documentation (docs/modules.md)

Add team-wide configuration variable

1. Copy hiera/common.yaml.example to hiera/common.yaml and add your variable (hiera/common.yaml.example)
2. Reference the variable in your Puppet manifest using Hiera lookup (manifests/site.pp)
3. Document the new configuration option in personal-configuration (docs/personal-configuration.md)

Add a new Puppet module dependency

1. Declare the module and version in Puppetfile (Puppetfile)
2. Run librarian-puppet install to resolve dependencies (Puppetfile)
3. Include the module in site.pp or a custom module manifest (manifests/site.pp)
4. Add tests for the new module's configuration (spec/localhost/directories_spec.rb)

Add user-specific customization

1. Create a user YAML file in hiera/users/ directory (hiera/users/README.md)
2. Define person-specific classes or variables in the user file (modules/people/manifests/.gitkeep)
3. Reference the user configuration in site.pp with hiera lookups (manifests/site.pp)

• Puppet — Industry-standard infrastructure-as-code framework for declarative machine configuration; integrates with Boxen ecosystem.
• Hiera — Hierarchical data lookup system built into Puppet; enables team-wide and per-user configuration without code duplication.
• Ruby/Bundler — Boxen framework is Ruby-based; Bundler manages gem dependencies reproducibly across team machines.
• Homebrew — Package manager optimized for macOS development tools; Boxen uses it to install and manage software packages.
• RSpec/ServerSpec — Testing frameworks that verify configuration was applied correctly; ensures predictable machine state.

• Boxen requires Xcode Command Line Tools to be pre-installed

  • Why: Reduces bootstrap complexity; Xcode tools are fundamental for macOS development.
  • Consequence: Developers must manually install Xcode before running Boxen, adding a manual step.

• Uses Puppet and Hiera rather than simpler shell scripts

  • Why: Enables declarative, idempotent configuration that scales across teams; easier to maintain complex setups.
  • Consequence: Steeper learning curve; requires understanding Puppet DSL and Hiera hierarchy.

• Bundles all Puppet modules and gems in vendor/ directory

  • Why: Ensures reproducible builds and offline functionality; reduces dependency on external networks.
  • Consequence: Larger repository size; requires manual updates to gem and module versions.

• Separate hiera/users/ for per-user configuration

  • Why: Allows individual developers to customize their setup without modifying shared configuration.
  • Consequence: Configuration scattered across multiple files; requires discipline to document personal overrides.

• Does not manage Linux or Windows systems; macOS only
• Does not provide real-time provisioning or auto-remediation; runs as batch jobs
• Does not handle user authentication or secrets management
• Does not provide a GUI; command-line driven
• Does not manage application-level configuration; only infrastructure and tools
• Does not support existing rvm, rbenv, or chruby installations

Boxen requires Xcode Command Line Tools pre-installed and will fail if rvm/rbenv/chruby/homebrew/nvm already exist. GitHub usernames with dashes (-) may cause issues. The repo assumes /opt/boxen/ directory ownership by the current user (see bootstrap command). Hiera config lookup is strict—typos in hiera/users/<username>.yaml won't error but will silently use defaults. Puppet manifests in modules/ must follow Puppet 3.x syntax if using older Boxen versions.

• Infrastructure as Code (IaC) via Puppet — Boxen's entire design relies on declaring system state in Puppet manifests rather than shell scripts—understanding Puppet resources, classes, and modules is essential to customizing your Boxen
• Hiera (Hierarchical Configuration) — Boxen uses Hiera to separate configuration data (YAML) from Puppet code, enabling per-user and per-org customization without modifying manifests—critical for team adoption
• Facter (System Facts) — Boxen uses Facter to detect system properties (OS version, hostname, custom facts in facts.d/) and conditionally apply Puppet resources—understanding facts enables environment-aware provisioning
• Idempotent Provisioning — Boxen is designed to run repeatedly without side effects—each Puppet resource should produce the same system state regardless of how many times it runs, making incremental updates safe
• Puppetfile Dependency Resolution — Like Gemfile for Puppet, Puppetfile pins versions of Puppet modules and their transitive dependencies—understanding version constraints prevents compatibility issues when forking
• System Package Manager Abstraction — Boxen abstracts Homebrew, system packages, and language-specific package managers (Gems, npm) through Puppet modules—allows portable declarations across team members with different prior installs

• boxen/boxen — Core Boxen Ruby gem that our-boxen depends on—contains the Puppet runner and CLI logic
• boxen/puppet-boxen — Foundation Puppet module providing boxen resource types and base OS utilities that other modules extend
• boxen/puppet-homebrew — Puppet module for Homebrew package management—commonly included in Boxen configs to install brew packages
• boxen/boxen-web — Web UI for managing Boxen runs and distribution across team machines—complements this repo for team adoption
• github/linguist — GitHub's language detection tool—Boxen repos often use it to validate polyglot environments (Ruby, Shell, Puppet, etc.)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for script/boxen-bootstrap and script/boxen workflows

The spec/ directory has tests for CLI, directories, git, hub, packages, and services, but there are no tests for the core bootstrap and boxen scripts themselves. These are critical entry points that new contributors will modify. Adding specs would catch regressions in the bootstrap flow and document expected behavior.

• [ ] Create spec/localhost/bootstrap_spec.rb to test script/boxen-bootstrap execution and artifact creation
• [ ] Create spec/localhost/boxen_script_spec.rb to test script/boxen idempotency and manifest application
• [ ] Add specs to verify that Puppetfile.lock is properly resolved after bootstrap
• [ ] Update spec/spec_helper.rb with helpers for shell script execution if needed

Add comprehensive Hiera configuration documentation and validation specs

The hiera/common.yaml.example file exists but there's no documented schema or validation. New contributors won't know what keys are valid, required, or what values they should contain. The docs/personal-configuration.md mentions Hiera but doesn't explain the structure. This creates friction for org adoption.

• [ ] Create hiera/common.yaml with documented examples and comments for all supported keys (homebrew packages, apps, services, etc.)
• [ ] Add hiera/schema.yaml documenting the expected structure and types for each configuration key
• [ ] Create spec/localhost/hiera_config_spec.rb to validate that hiera files follow the schema
• [ ] Update docs/personal-configuration.md with Hiera configuration reference section linking to the schema

Add GitHub Actions CI workflow to validate Puppet manifests and run test suite on PRs

The .travis.yml file exists (suggesting legacy CI), but there's no modern GitHub Actions workflow. New contributors won't get immediate feedback when submitting PRs, and the CI status is unclear. This repo is designed to be forked by teams, so a working CI template is essential.

• [ ] Create .github/workflows/test.yml that runs 'bundle exec rake' (Rakefile likely contains test tasks)
• [ ] Add linting step using puppet-lint against manifests/ directory
• [ ] Add validation step for Puppetfile syntax using bundler
• [ ] Update README.md with CI badge and note about how teams should configure CI in their forks

• Add RSpec test coverage for manifests/site.pp—currently spec/ only tests CLI and directories, not Puppet manifest logic. Start with spec/localhost/manifests_spec.rb.
• Create a docs/troubleshooting.md with common Boxen failures (Xcode conflicts, path issues, Hiera lookup problems) and solutions based on README warnings.
• Add a modules/projects/manifests/rails.pp example that installs Rails-specific tools (database, Redis, Elasticsearch). Currently docs/rails.md exists but no corresponding Puppet module.

This Boxen project template has a POOR security posture, primarily due

• High · Outdated Puppet Framework — vendor/cache/puppet-3.7.1.gem, Puppetfile. The codebase uses Puppet 3.7.1, which is severely outdated and no longer receives security updates. Puppet 3.x reached end-of-life in December 2016. This version contains known security vulnerabilities that could be exploited to compromise system configurations. Fix: Upgrade to Puppet 7.x or later (currently maintained versions). Review the Puppet upgrade guide for compatibility changes.
• High · Outdated Dependencies with Known Vulnerabilities — vendor/cache/ (multiple gems), Gemfile.lock. Multiple dependencies are severely outdated and have known security vulnerabilities: json-2.1.0 (CVE-2013-0269 and others), aws-sdk-core-2.0.46, puppet-lint-0.3.2, and others from 2014-2015. These packages are no longer maintained and contain exploitable flaws. Fix: Run 'bundle audit' to identify all vulnerable dependencies. Update Gemfile with latest versions and regenerate Gemfile.lock. Establish a dependency update policy.
• High · Bundled Vendor Cache in Version Control — vendor/cache/. The vendor/cache directory contains pre-downloaded gem files checked into git. This increases the risk of accidentally committing modified malicious copies and makes it difficult to audit which versions are truly being used. This is an anti-pattern for Ruby projects. Fix: Remove vendor/cache from git history using 'git rm --cached vendor/cache' and add to .gitignore. Use 'bundle install --deployment' in CI/CD instead. Use Dependabot or Renovate for automated dependency updates.
• Medium · Potential Credential Exposure in Hiera Configuration — hiera/ directory. The hiera/common.yaml.example and hiera/users/ directories are present. If actual hiera YAML files (non-.example) contain credentials, API keys, or passwords, they could be exposed. Hiera is commonly used for storing sensitive data. Fix: Ensure all actual hiera YAML files (not .example versions) are listed in .gitignore. Use environment variables or a secrets management system (Vault, AWS Secrets Manager) for sensitive data instead of YAML files.
• Medium · Insufficient Input Validation in Puppet Templates — modules/projects/templates/shared/nginx.conf.erb. The nginx.conf.erb template uses ERB (Embedded Ruby) without visible sanitization. If user input is passed to this template, it could allow injection of malicious nginx configuration directives. Fix: Review the template and ensure all user-controlled variables are properly escaped using <%= h variable %> or similar. Validate nginx configuration before applying. Use static templates where possible.
• Medium · Outdated RSpec and Test Infrastructure — .rspec, vendor/cache/rspec*, vendor/cache/mocha-1.1.0.gem. The test infrastructure uses rspec-3.2.0 (released 2014) and mocha-1.1.0. These outdated test dependencies may have unpatched security issues and lack modern testing capabilities. Fix: Update rspec, mocha, and puppetlabs_spec_helper to current versions. Review test output for deprecation warnings.
• Low · Exposed Example Configuration Files — hiera/common.yaml.example, facts.d/example.yaml. Example configuration files (hiera/common.yaml.example, facts.d/example.yaml) are present. While marked as examples, they may contain patterns that reveal system architecture or configuration approach. Fix: Ensure example files do not contain sensitive patterns or real hostnames. Document what should NOT go in these files.
• Low · Missing Security Documentation — Repository root. No security.md or SECURITY.md file found to document security policies, vulnerability reporting procedures, or security best practices for contributors. Fix: Create a SECURITY.md file with: vulnerability disclosure process, security contact information, supported versions for security updates, and security best practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.