🐧 Penguin Ranch Bootstrap

The "Gold Standard" repository template for launching new projects.

Caution

AI AGENT INSTRUCTIONS: If you have been directed to this repository to learn about or apply "best practices" to an existing project, start with BEST_PRACTICES.md — a guided, tiered tour of the standards with direct links to every canonical file. The canonical files all live in the /templates directory, which contains the actual scaffolding that becomes a new downstream project. Do NOT examine the root-level files (such as install.sh, Makefile, etc.) to learn about project setup, as those files are strictly for managing the bootstrap repository itself.

This repository is designed to instantly bootstrap a fully configured project environment characterized by zero-host dependencies, secure-by-default workflows, and structural guardrails that enforce elite engineering practices. It is explicitly designed to be heavily supported by IDE-based AI Agents.

---

🌟 The Philosophy & Features (The "Why")

When you bootstrap a project using this template, you are receiving an environment intentionally restricted to prevent common developer mistakes. Here is why we made these decisions:

1. Devcontainer Only (Zero-Host Dependency)

The Problem: "It works on my machine!" The Solution: All work happens strictly inside a VS Code Devcontainer. Whether you are on macOS, Linux, or Windows (WSL), the moment you open this project, Docker spins up an identical, pre-configured Linux container. You never need to install Node, Python, or Go on your host computer again.

2. Secure by Default

The Problem: Accidentally committing API keys or unverified code. The Solution: The .env file is heavily .gitignored, and the pre-commit hook scans every staged change for secrets with gitleaks before the commit is allowed. Additionally, VS Code forwards your host's SSH agent into the Devcontainer, and Git is pre-configured for SSH Commit Signing whenever that agent is reachable — when it isn't, commits proceed unsigned rather than blocking you.

3. AI-Optimized Workflows

The Problem: Generative AI tools (like GitHub Copilot or Gemini) get confused easily and burn through their context "tokens" doing repetitive tasks. The Solution: This project includes an AGENTS.md file designed explicitly to be read by AI. It instructs the AI on our exact project constraints, architectural philosophy, and git branching strategies. Furthermore, the Gemini CLI (@google/gemini-cli) and Claude Code CLI (@anthropic-ai/claude-code) are installed globally inside the container, and make ai-context is provided to instantly bundle project metadata for an AI assistant—saving precious IDE tokens. Their state—conversation history, logins, and MCP/trust approvals—lives on per-project named Docker volumes, so it survives a container rebuild instead of resetting every time.

4. Structural Guardrails

We have implemented physical files that prevent bad habits:

• .editorconfig: Forces every IDE (even Vim) to use the exact same tab sizes, line endings, and whitespace rules.
• Makefile: A universal task runner. Whether the underlying project is npm, go, or pytest, developers only ever need to run make test or make run. Includes make doctor for instant environment health checks.
• CODEOWNERS: Automatically requires Tech Lead PR reviews for the living project docs (architecture decisions) and DevOps reviews for CI/CD changes.
• dependabot.yml: Pre-configured to open PRs that keep dependencies (GitHub Actions, Docker images, devcontainer features) up to date. Pair it with GitHub's Dependabot alerts (a repository setting) for vulnerability scanning — the shipped Trivy workflow covers scanning on PRs.

---

🧭 Already Have a Project?

The installer below is for brand-new, empty projects. If you have an existing codebase and just want to adopt the standards — or you're pointing an AI agent at this repo and telling it "use the best practices set by this repo" — use BEST_PRACTICES.md instead. It organizes everything here into three adoption tiers (drop-in guardrails → workflow automation → AI-native environment) so you can take exactly as much as you want, without the installer.

---

🚀 How to Use (Step-by-Step)

Prerequisites (On your Host Machine)

1. Install Docker Desktop.
2. Install Visual Studio Code.
3. Install the Claude Code extension (anthropic.claude-code) and the Dev Containers extension (ms-vscode-remote.remote-containers).

Step 1: Scaffold the Project

Open a standard terminal on your host machine (Mac/Linux) or Git Bash / WSL (Windows) and run:

# Create and move into your new project folder
mkdir my-new-idea && cd my-new-idea

# Initialize git
git init

# Run the bootstrap installer
curl -sSL https://raw.githubusercontent.com/penguinranch/bootstrap/main/install.sh | bash

Note for Windows Users: Command Prompt and PowerShell do not natively support running .sh bash scripts. You must execute the above curl command using Git Bash or WSL.

Step 2: Open the Project in VS Code

1. Open the folder in VS Code. When prompted to install the workspace's recommended extensions, accept — the scaffold ships a .vscode/extensions.json that includes the Claude Code extension.
2. An alert will appear prompting you to reopen the project in a Dev Container — hold off for now. The container should be configured for your stack first (next step).

Step 3: The AI Architecture Kickoff

Decide on your tech stack — the language and framework you choose determine how the container is configured. Open the Claude Code panel in VS Code and prompt it with exactly this text:

"I am starting a new project. Please completely read AGENTS.md for our workflow standards. Let's begin Phase 1: Discovery by discussing the goals and tech stack for this idea. Once we decide, please proceed with the following setup checklist: 1. Fill out docs/VISION.md (goals, non-goals, roadmap) and the Tech Stack section of docs/ARCHITECTURE.md. 2. Update the .devcontainer/ configuration (Dockerfile and devcontainer.json) for our chosen stack, and replace the {{PROJECT_NAME}} placeholders in devcontainer.json and the Makefile (APP_NAME) with the project name. 3. Configure the universal Makefile and setup dependabot.yml. 4. Rewrite README.md to describe this new project and how to run it."

Step 4: Open the Devcontainer

Once the AI has configured .devcontainer/, click Reopen in Container (or run Dev Containers: Reopen in Container from the command palette).

Wait a few minutes while Docker builds the Linux environment for your chosen stack.

Step 5: Initial Setup Scripts

Once VS Code reloads inside the container, open a new Terminal and run:

make setup

This will prompt you for your Git credentials and (optionally) your Gemini and Anthropic API keys so the CLI tooling works, then install the git hooks.

---

🚑 Troubleshooting

• The IDE Window is hung / The AI CLIs didn't install: Sometimes the automatic postCreateCommand hangs. Open a terminal inside the container and manually run make ai-tools to finish the installation.
• Git complains about missing user name and email: If the Devcontainer hangs after building, the startup health check might not have run to configure your Git profile from .env. You can fix this by running make doctor (which re-applies .env settings) or by running make setup again.
• Windows / WSL line-ending errors (bash scripts crashing): Windows uses CRLF format for new lines, which crashes Linux bash scripts. We have a .gitattributes file to prevent this, but if you still see \r errors, ensure your global git config is set: git config --global core.autocrlf false.

---

🛠 Developing the Bootstrap Template

If you are looking to contribute to or modify the bootstrap repository itself, please consult the root AGENTS.md file for architectural constraints, goals, and modification rules.