---

name: repo-init description: Initialize a new repository with standard scaffolding - git, gitignore, CLAUDE.md, justfile, mise, and beads. Use when starting a new project or setting up an existing repo for Claude Code workflows.

Repository Initialization

Scaffold a new or existing repository with standard project infrastructure.

Related skills:

• just-pro - Build system patterns and templates
• mise - Tool version management
• go-pro, rust-pro, typescript-pro - Language-specific setup (run after repo-init)

What This Skill Does

Creates universal scaffolding that works across all project types:

| File | Purpose | |------|---------| | .gitignore | Standard ignores + language-specific patterns | | CLAUDE.md | Project conventions for Claude Code | | justfile | Build system skeleton | | .mise.toml | Tool version pinning (empty, ready for mise use) | | .beads/ | Issue tracking database | | .envrc.example | Environment variable template |

Flow

1. Gather context (language, project type)
2. Create scaffolding
3. Initialize beads
4. Point to language skill for next steps

---

Step 1: Gather Context

Before scaffolding, clarify:

1. Project language(s): Go, Rust, TypeScript, Python, or multi-language?
2. Project type: Library, CLI, web app, API, monorepo?
3. Existing files: Is this a fresh repo or adding to existing code?

Use AskUserQuestion if unclear from context.

---

Step 2: Git Setup

# Initialize git if needed
git init

# Create .gitignore with common patterns

.gitignore Templates

Each language skill provides a comprehensive .gitignore in its references/ directory. These include common patterns (.env, .envrc, .DS_Store, Thumbs.db, IDE files) plus language-specific ignores.

Copy from the appropriate language skill:

| Language | Source | |----------|--------| | Go | go-pro/references/gitignore → .gitignore | | Rust | rust-pro/references/gitignore → .gitignore | | TypeScript | typescript-pro/references/gitignore → .gitignore | | Python | python-pro/references/gitignore → .gitignore |

For multi-language repos: Start with the primary language's gitignore, then merge patterns from others as needed.

Minimal fallback (if language skill unavailable):

# Environment
.env
.env.local
.env.*.local
.envrc

# OS
.DS_Store
Thumbs.db

# IDE
.idea/
.vscode/

# Build (customize per language)
dist/
build/
target/
node_modules/
__pycache__/

---

Step 3: CLAUDE.md

Create project conventions file for Claude Code:

# Project Name - Claude Instructions

## Overview

Brief description of what this project does.

## Development

```bash
just setup    # First-time setup
just check    # Run all quality gates

Conventions

• [Add project-specific patterns here]
• [Coding standards, naming conventions, etc.]

Architecture

• [Key directories and their purposes]
• [Important abstractions]

Keep it minimal initially. Add conventions as they emerge.

---

## Step 4: Justfile Skeleton

```just
# Project Build System
# Usage: just --list

default:
    @just --list

# First-time setup
setup:
    mise trust
    mise install
    @echo "Ready. Run 'just check' to verify."

# Quality gates - add language-specific checks
check:
    @echo "Add fmt, lint, test recipes"

# Remove build artifacts
clean:
    @echo "Add clean commands"

For language-specific recipes, see:

• just-pro skill references (package-go.just, package-rust.just, etc.)

---

Step 5: Mise Configuration

Create empty .mise.toml ready for tool pinning:

[tools]
# Add tools with: mise use <tool>@<version>
# Examples:
# node = "22"
# go = "1.25"
# rust = "1.83"
# just = "latest"

---

Step 6: Beads Initialization

bd init -q

This creates .beads/ directory with issue tracking database.

For teams, consider:

• bd init --team - Interactive team workflow setup
• bd init --stealth - Personal use without affecting collaborators

---

Step 7: Environment Template

Create .envrc.example (committed) as template for .envrc (gitignored):

# Copy to .envrc and fill in values
# cp .envrc.example .envrc && direnv allow

# Mise integration
if command -v mise &> /dev/null; then
  eval "$(mise hook-env -s bash)"
fi

# Project-specific environment
# export DATABASE_URL="postgres://localhost/myapp"
# export API_KEY=""

---

Step 8: Next Steps

After scaffolding, point user to language-specific setup:

| Language | Next Step | |----------|-----------| | Go | Invoke go-pro skill, run go mod init, copy .golangci.yml | | Rust | Invoke rust-pro skill, run cargo init, copy clippy.toml | | TypeScript | Invoke typescript-pro skill, run npm init | | Multi-language | Follow each lang skill for respective packages |

---

Quick Reference

# Full init sequence
git init
# Create .gitignore, CLAUDE.md, justfile, .mise.toml, .envrc.example
bd init -q
mise use just@latest
# Then follow language skill for specifics

Monorepo Variant

For monorepos, the root gets:

• Root justfile with module imports (see just-pro monorepo patterns)
• Root .mise.toml with shared tooling
• Single .beads/ at root

Each package gets:

• Package-local justfile
• Language-specific configs (Cargo.toml, package.json, etc.)