Universal Agent Bootstrap

Install a reusable Cursor guardrail rule pack into any project before AI-assisted coding.

This is a setup kit for Cursor users who want practical guardrails before AI-assisted coding: design-first rules, test-first implementation, code review checks, red-team prompts, debugging discipline, and minimalism defaults.

The guardrails are model-agnostic by default. They work in Cursor whether you use OpenAI GPT/Codex models, Anthropic Claude models, or another model provider. The repo includes an optional Claude Code settings template, but the core value is the Cursor rule set and gated workflow.

What This Changes On Your Machine

The default bootstrap is intentionally explicit:

• Installs or reuses local code-quality CLIs: pre-commit, black, ruff, and bandit.
• Copies seven Cursor project rules into a target project’s .cursor/rules/ folder.
• Does not configure model credentials by default.
• Does not require Claude Code. If you use Claude Code too, opt in with ./bootstrap.sh --project /path/to/your-project --with-claude.

Cursor project rules are intentionally project-local. For personal global preferences, use Cursor Settings > Rules and paste your preferred guidance there.

New to the Terminal?

If you've never used a terminal before:

• Mac: Press Cmd + Space, type "Terminal", press Enter
• Windows: Use WSL. Plain cmd.exe will not run bootstrap.sh, and Git Bash may not expose python3.

The terminal is where you'll type the commands below. Each command goes on one line — press Enter after each one.

Prerequisites

Before running, make sure you have:

• Python 3.11+ — Check: python3 --version
• Git — Check: git --version
• Cursor IDE — Download here
• GitHub CLI (gh) — Install instructions (needed for creating projects later)
• pipx — Optional but recommended for installing CLI tools safely: brew install pipx

If Python isn't installed, download it here.

Quick Start

Copy and paste these commands one at a time into your terminal:

Step 1: Download this repo to your computer

git clone https://github.com/KangaKode/universal-agent-bootstrap.git ~/universal-agent-bootstrap

Step 2: Go into the folder you just downloaded

cd ~/universal-agent-bootstrap

(cd means "change directory" — it's how you navigate folders in the terminal. ~ means your home folder.)

Step 3: Install the guardrails into a project

./bootstrap.sh --project /path/to/your-project

Optional, only if you also use Claude Code:

./bootstrap.sh --project /path/to/your-project --with-claude

--with-claude writes a reference file to ~/.claude/settings.bootstrap-template.json. It does not activate Claude Code settings or write credentials.

What to Expect

The script takes about 30 seconds. You'll see:

1. [OK] python3 found — Confirms Python is installed
2. [OK] pipx found or [WARN] pipx not found — Installs code quality tools only when safe
3. [OK] Installed rule: worker-gate.mdc — Copies safety rules into the target project
4. Bootstrap Complete — You're done

Green [OK] means success. Yellow [WARN] means something was skipped (usually fine). Red [ERROR] means something failed.

If pipx is not installed, the script skips automatic CLI tool installation instead of modifying managed Python environments. The Cursor rules still install. For the cleanest tool setup, install pipx first:

brew install pipx              # macOS/Homebrew
sudo apt install pipx          # Ubuntu/WSL
python3 -m pipx ensurepath

Verify It Worked

Run this command to list the installed rules:

ls /path/to/your-project/.cursor/rules/

(ls means "list" — it shows files in a folder)

You should see 7 files:

code-reviewer.mdc  debugger.mdc  expert-review.mdc  minimalist.mdc  red-team.mdc  test-first.mdc  worker-gate.mdc

What Gets Installed

What	Where	Purpose
7 Cursor project rules	<project>/.cursor/rules/	Safety guardrails for that project
pre-commit	User-level Python CLI	Code quality checker
black, ruff, bandit	User-level Python CLIs	Formatting, linting, security scanning
Claude Code settings template	~/.claude/settings.bootstrap-template.json	Optional reference config; copied only with --with-claude and not activated

Cursor project rules live inside each repository at .cursor/rules/, which makes the guardrails visible, reviewable, and version-controlled.

The 7 Rules (Plain English)

Rule	What It Does
worker-gate	Stops coding until design docs are ready
red-team	Blocks known security risks
code-reviewer	Enforces code quality basics
debugger	Structured troubleshooting process
expert-review	Full review protocol before releases
minimalist	Prevents overbuilding
test-first	Requires tests before behavioral implementation changes

These rules are project-local. Once copied into a project, they apply when Cursor works in that project.

Why Two Repos?

flowchart TD
    bootstrap[universal-agent-bootstrap] --> machine[Your Laptop]
    template[universal-agent-workflow-template] --> project[One Project]
    machine --> allProjects[All Projects]

Loading

• Bootstrap (this repo) = reusable installer for project guardrails.
• Template = project starter files. Clone once per new project.

Starting a New Project

After bootstrap is complete, create a new project from the template:

Option A: Using GitHub CLI (recommended)

gh repo create my-project \
  --template KangaKode/universal-agent-workflow-template \
  --clone

cd my-project
make install
~/universal-agent-bootstrap/bootstrap.sh --project .

Option B: Using GitHub website

1. Go to the template repo in your organization
2. Click the green "Use this template" button
3. Name your new repo and create it
4. Clone your new repo and run make install

Then open the project in Cursor. The safety rules are part of that project.

Non-Engineer POCs

Use the workflow template for non-engineer POCs that engineers need to review and take over. The bootstrap keeps existing projects safer; the template carries the full POC workflow:

• Start Here
• Engineer handoff template
• Vibe-coding smells checklist
• Completed example

When to Run Bootstrap Again

• You create a new project that does not already include .cursor/rules/
• You want to update a project to the latest rule pack
• Your project’s .cursor/rules/ folder was deleted

To update existing rules, delete or move the old project rules first:

rm .cursor/rules/*.mdc
~/universal-agent-bootstrap/bootstrap.sh --project .

Troubleshooting

"python3: command not found"

Install Python 3.11+ from python.org.

"permission denied: ./bootstrap.sh"

Make it executable:

chmod +x bootstrap.sh
./bootstrap.sh --project /path/to/your-project

"pipx: command not found"

The Cursor rules still install without pipx. Install pipx if you also want the script to install pre-commit, black, ruff, and bandit.

Rules aren't showing up in Cursor

1. Verify they exist: ls .cursor/rules/
2. Restart Cursor completely (quit and reopen)
3. Rules apply to Agent mode, not regular chat

Safe Delivery Flow

Once bootstrap is complete, every project follows this flow:

1. Describe what you want to build
2. Design — Create design docs first (Worker Gate enforces this)
3. Review — Run expert panel on design
4. Implement — Write or update tests before behavioral code changes
5. Verify — Pass pre-commit and CI checks
6. Ship

Optional Extended Packs

Keep the default bootstrap small and universal. Larger Cursor setups belong in the project template by default, or in explicit opt-in packs later:

• Agents — specialist .cursor/agents/ definitions for review, security, architecture, testing, infrastructure, and other focused work.
• Skills — reusable .cursor/skills/ workflows for richer project-specific automation.
• Claude Code — optional reference settings via --with-claude.

For a full starter project with agents, skills, hooks, CI, and workflow docs, use the workflow template linked below.

Links

• Template repo: KangaKode/universal-agent-workflow-template
• Cursor IDE: cursor.com