repo-init

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.)