start-right

What this skill does

# Start Right

Complete repository initialization and scaffolding for new projects with production-ready CI/CD workflows, validation checks, and automated releases.

## Overview

This skill provides end-to-end repository setup for solo developers, automating everything from git initialization to production deployment workflows. It handles project type detection, appropriate tooling configuration, GitHub repository creation, branch protection, validation checks, git hooks, and comprehensive GitHub Actions workflows.

## Workflow Decision Tree

When a user requests repo initialization/scaffolding:

1. **Determine project type** → Detect or ask user for project type (node/typescript/react/rust/python/go/docker/skill)
2. **Gather preferences** → Ask about:
   - Repository visibility (public/private)
   - Organization (if applicable)
   - Validation checks to enable (format, lint, type-check, test, build, integration-test)
   - Git hooks preference (husky for Node.js projects, lefthook for others)
   - Release strategy (npm, github-pages, vercel, docker, binary, pypi, crates.io, skill)
3. **Execute scaffolding** → Run setup scripts in order
4. **Verify and report** → Confirm all components are configured correctly

## Scaffolding Process

### Step 1: Prerequisites Check

Before starting, verify:
- Git is installed
- GitHub CLI (gh) is installed and authenticated
- Current directory is the intended project location
- Directory is empty or contains minimal files

```bash
# Check prerequisites
git --version
gh --version
gh auth status
```

If prerequisites are missing, provide installation instructions:
- **Git**: `brew install git` (macOS) or system package manager
- **GitHub CLI**: `brew install gh` or from https://cli.github.com
- **Authentication**: `gh auth login`

### Step 2: Git Initialization

Initialize git repository with main as default branch:

```bash
python3 scripts/init_git_repo.py <repo-name> [--private] [--org <org>] [--type <project-type>]
```

**Options**:
- `--private`: Create private repository (default: public)
- `--org <n>`: Create under organization
- `--type <type>`: Project type for appropriate .gitignore (node, python, rust, go)

This script:
- Initializes git with `main` branch
- Creates appropriate `.gitignore` file
- Creates GitHub repository
- Sets up remote connection

### Step 3: Tooling Configuration

Set up linting, formatting, and type checking based on project type:

```bash
python3 scripts/setup_tooling.py [project-type]
```

If project type is not specified, it will be auto-detected.

This creates configuration files like:
- **Node/TypeScript**: `.eslintrc.json`, `.prettierrc.json`, `tsconfig.json`
- **Python**: `.flake8`, `.black.toml`, `mypy.ini`
- **Rust**: `rustfmt.toml`

After running, **install the necessary dependencies**:
- **Node**: `npm install --save-dev eslint prettier typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin`
- **Python**: `pip install black flake8 mypy pytest`
- **Rust**: Tools are built-in to cargo

### Step 4: Git Hooks Setup

Configure pre-commit and pre-push hooks:

```bash
python3 scripts/setup_git_hooks.py [--husky|--lefthook] --checks format,lint,type-check,test,build
```

**Hook tool selection**:
- `--husky`: For Node.js projects (recommended, requires npm)
- `--lefthook`: Universal, works with any project type

**Checks configuration**:
- **Pre-commit**: format, lint, type-check (fast checks)
- **Pre-push**: test, build (slower checks)
- Customize with `--checks` flag

This script:
- Installs the git hooks tool
- Creates hook configuration files
- Sets up hooks to run appropriate validation checks
- Updates package.json scripts (if Node.js project)

### Step 5: GitHub Actions Workflows

Generate comprehensive CI/CD workflows:

```bash
python3 scripts/generate_workflows.py --checks format,lint,type-check,test,build --release <release-type>
```

**Release types** (choose based on project):
- `npm`: npm package publication
- `github-pages`: Static site to GitHub Pages
- `docker`: Container image to GitHub Container Registry
- `binary`: Compiled binaries for multiple platforms
- `skill`: Claude Code skill (no deployment)
- `pypi`: Python package to PyPI
- `vercel`: Skip (Vercel handles deployment automatically)

This creates:
1. **pr-validation.yml**: Runs validation checks on PRs to main
2. **main-ci-cd.yml**: Runs on merge to main, includes:
   - All validation checks
   - Automatic version bumping
   - Git tagging
   - Calls release workflow
3. **release.yml**: Reusable workflow for deployment (if release type specified)

**Workflow features**:
- PR validation runs subset of fast checks
- Main branch validation runs ALL checks including integration tests
- Automatic semantic versioning
- GitHub Releases with auto-generated notes
- Project-specific optimizations (caching, parallel jobs)

### Step 6: Branch Protection Rules

Configure branch protection to enforce PR workflow:

```bash
python3 scripts/setup_branch_protection.py build,test
```

Pass comma-separated list of required status checks (matching GitHub Actions job names).

This script configures:
- **Direct pushes to main**: Blocked
- **Pull requests**: Required
- **Status checks**: Must pass before merge (if configured)
- **Squash merging**: Enabled (enforced)
- **Merge commits**: Disabled
- **Rebase merging**: Disabled
- **Auto-delete branches**: Enabled after merge

### Step 7: Initial Commit and Verification

Create initial commit and push to main:

```bash
git add .
git commit -m "chore: initial repository scaffolding"
git push -u origin main
```

Verify setup:
- Check GitHub repository exists and is configured correctly
- Verify branch protection rules are active
- Confirm workflows are present in `.github/workflows/`
- Test git hooks by making a small change

## Interactive Setup Flow

For best user experience, guide users through the process interactively:

### Phase 1: Information Gathering

Ask the user:

1. **Repository name**: What should the repository be named?
2. **Visibility**: Public or private repository?
3. **Organization**: Create under an organization? (optional)
4. **Project type**: What type of project is this?
   - Node.js / JavaScript
   - TypeScript
   - React / Next.js
   - Python
   - Rust
   - Go
   - Docker container
   - Claude Code skill
   - Other / Generic
5. **Validation checks**: Which checks should run?
   - Format checking (recommended: pre-commit)
   - Linting (recommended: pre-commit)
   - Type checking (recommended: pre-commit for TypeScript/Python)
   - Unit tests (recommended: pre-push)
   - Build verification (recommended: PR and main)
   - Integration tests (recommended: main branch only)
6. **Git hooks**: Set up pre-commit and pre-push hooks?
   - Yes (recommended)
   - No
7. **Release strategy**: How will this project be released?
   - Provide options based on project type (see [Release Strategies](#release-strategies))

### Phase 2: Execution

Execute the scaffolding scripts in order, showing progress:

```
🚀 Initializing repository...
✅ Git initialized with main branch
✅ Created .gitignore
✅ Created GitHub repository: username/repo-name (public)
✅ Configured remote origin

🔧 Setting up tooling...
✅ Created .eslintrc.json
✅ Created .prettierrc.json
✅ Created tsconfig.json

🪝 Configuring git hooks...
✅ Installed husky
✅ Created pre-commit hook (format, lint)
✅ Created pre-push hook (test, build)

⚙️  Generating GitHub Actions workflows...
✅ Created pr-validation.yml
✅ Created main-ci-cd.yml
✅ Created release.yml (npm)

🔒 Configuring branch protection...
✅ Enabled branch protection for main
✅ Configured squash merge only
✅ Enabled auto-delete branches

📝 Creating initial commit...
✅ Initial commit created and pushed
```

### Phase 3: Post-Setup Instructions

Provide next steps to the user:

```
✅ Repository scaffolding complete!

Your repository is ready at: https://github.com/username/repo-name

Next steps:
1. Install dependencies:
   npm install

2. Install d