vr-setup

name	vr-setup
description	Interactive setup wizard for new users who cloned this boilerplate project. Checks prerequisites, installs dependencies, configures environment, and introduces the research pipeline.
user-invocable	true

Vibe Research - Project Setup Wizard

Guide the user through the initial setup of this research pipeline project after cloning.

Process

Run each step sequentially. If a step fails, explain the issue clearly and help the user resolve it before proceeding.

Step 1: Welcome

Print the following welcome message:

# Vibe Research - Setup Wizard

Welcome! This wizard will help you set up the AI research pipeline.
The following steps will be performed:

  1. Check prerequisites (Python, uv, git)
  2. Install Python dependencies
  3. Configure environment variables
  4. Set up pre-commit hooks
  5. Configure branch protection (recommended)
  6. Verify directory structure
  7. Introduction to pipeline skills

Step 2: Check Prerequisites

Check each prerequisite and report the result:

1. Python 3.12+: Run python3 --version. If the version is below 3.12, warn the user and suggest installing Python 3.12+ (e.g., via pyenv or the official installer).
2. uv: Run uv --version. If not installed, instruct the user to install it:
   • curl -LsSf https://astral.sh/uv/install.sh | sh
3. git: Run git --version. This should already be available since they cloned the repo.

If any prerequisite is missing, stop and help the user install it. Do not proceed until all prerequisites are satisfied.

Step 3: Install Dependencies

Run uv sync to install all Python dependencies. If it fails, help diagnose the issue (e.g., Python version mismatch, network issues).

Step 4: Configure Environment Variables

1. Check if .env already exists.
2. If not, copy .env.example to .env:
   • cp .env.example .env
3. Show the user the contents of .env.example and explain each variable:
   • OPENAI_API_KEY - For OpenAI API calls (optional, only if experiments use OpenAI models)
   • ANTHROPIC_API_KEY - For Anthropic API calls (optional, only if experiments use Anthropic models)
   • WANDB_API_KEY / WANDB_PROJECT - For experiment tracking with Weights & Biases (optional)
   • HF_TOKEN - For downloading models/datasets from HuggingFace (optional)
4. Ask the user which API keys they want to configure now. For each key, ask for the value and write it to .env.
5. If the user wants to skip this step, that is fine - they can configure it later.

Step 5: Set Up Pre-commit Hooks

Run make setup (or manually: uv run pre-commit install && uv run pre-commit install --hook-type commit-msg) to set up git hooks. Explain briefly what pre-commit does:

• Automatically runs ruff (linter + formatter) on staged Python files
• Checks YAML/JSON/TOML/Python syntax and validates symlinks
• Prevents committing large files (>10MB), private keys, or hardcoded secrets (gitleaks)
• Strips Jupyter notebook outputs before commit (nbstripout)
• Lints YAML files (yamllint)
• Enforces commit message convention (conventional-pre-commit)
• Blocks direct commits to main branch

Step 6: Configure Branch Protection (Recommended)

Explain to the user that enabling GitHub branch protection ensures CI checks pass before merging to main. Guide them to set it up:

1. Go to Settings > Branches > Add branch protection rule on GitHub
2. Set Branch name pattern to main
3. Enable Require status checks to pass before merging
4. Search and add pre-commit as a required status check
5. Enable Require branches to be up to date before merging

Or use the GitHub CLI:

gh api repos/<owner>/<repo>/branches/main/protection -X PUT --input - <<'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["pre-commit"]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": null,
  "restrictions": null
}
EOF

This step is optional but strongly recommended. If the user skips it, CI will still run but won't block merges.

Step 7: Verify Directory Structure

Ensure the following directories exist (create if missing):

• experiments/
• papers/
• figures/
• data/ (should have .gitkeep)
• scripts/

Step 8: Pipeline Introduction

Print the following summary of available research pipeline skills:

# Setup Complete!

## Available Pipeline Skills

This project provides an AI-powered research pipeline with the following skills:

| Command              | Description                                      |
|----------------------|--------------------------------------------------|
| /vr-brainstorm          | Brainstorm research ideas and hypotheses          |
| /vr-literature-review   | Survey prior work and analyze research gaps       |
| /vr-experiment-plan     | Design experiment variables, metrics, baselines   |
| /vr-run-experiment      | Write and execute experiment code                 |
| /vr-make-figures        | Generate publication-quality figures              |
| /vr-write-paper         | Write a paper in LaTeX format                     |
| /vr-peer-review         | Self-review from a top-venue reviewer perspective |
| /vr-rebuttal            | Write rebuttals to reviewer comments              |
| /vr-pipeline            | Run the full pipeline end-to-end                  |

## Quick Start

To start a new research project, try:

  /vr-brainstorm <your-research-topic>

Or run the full pipeline:

  /vr-pipeline <your-research-topic>

## Useful Commands

- Run an experiment:  uv run python experiments/<name>/run.py
- Generate figures:   uv run python experiments/<name>/analysis.py
- Compile paper:      cd papers/<name> && latexmk -pdf main.tex

Notes

• Be friendly and encouraging throughout the setup process
• If the user's system is already partially set up (e.g., dependencies already installed), acknowledge it and skip redundant steps
• Always confirm successful completion of each step before moving to the next