bootstrap-project

What this skill does

# Project Bootstrap

Ensure a project has CI, pre-commit hooks, CLAUDE.md, and framework best practices configured. Detect what exists, add what's missing.

## Workflow

### 1. Detect Project State

Read `package.json` to determine:
- Package manager (check for `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`/`bun.lock`, `package-lock.json`)
- Existing scripts (`lint`, `test`, `build`, `typecheck`, `format`)
- Existing devDependencies (`husky`, `lint-staged`, `eslint`, `prettier`, `vitest`, `jest`)
- Framework (`next`, `react`, `vue`, `svelte`)

Check for existing config:
- `.github/workflows/ci.yml` — CI already configured?
- `.husky/` — Husky already initialized?
- Vercel skills already installed?

Report findings to user before making changes.

### 2. GitHub CI Workflow

Ensure `.github/workflows/ci.yml` exists with jobs for **lint**, **typecheck**, **test with coverage**, and **build**.

Read [references/ci-workflow.md](references/ci-workflow.md) for the template and adaptation guide.

If a CI workflow already exists, diff it against requirements and only add missing steps. Do not overwrite existing workflows — merge into them.

Configure coverage thresholds in the test runner config (e.g., `vitest.config.ts`, `jest.config.ts`). LLM coding agents generate tests alongside code, so enforce high thresholds:

| Metric | Threshold |
|--------|-----------|
| Statements | 80% |
| Branches | 80% |
| Functions | 80% |
| Lines | 80% |

CI must **fail** if coverage drops below these thresholds. See [references/ci-workflow.md](references/ci-workflow.md) for configuration examples.

Add a separate `coverage-report` job that posts a coverage summary comment on pull requests. This runs after the main CI job and uses `davelosert/vitest-coverage-report-action` (Vitest) or `MishaKav/jest-coverage-comment` (Jest). See [references/ci-workflow.md](references/ci-workflow.md) for the template and coverage reporter configuration.

### 3. Husky Pre-commit

Ensure husky and lint-staged are installed and configured with checks for **lint**, **format**, and **typecheck**.

Read [references/husky-precommit.md](references/husky-precommit.md) for setup instructions.

Key decisions:
- Include tests in pre-commit only if they run in <30s; otherwise CI-only
- Typecheck runs as a separate hook step (not inside lint-staged)
- lint-staged handles per-file lint + format

### 4. Claude Code Hook Guard

Ensure `.claude/settings.json` has a `PreToolCall` hook that blocks `--no-verify` and `--no-gpg-sign` in git commands. This prevents AI agents from bypassing pre-commit hooks.

Read [references/claude-code-hooks.md](references/claude-code-hooks.md) for the configuration.

If `.claude/settings.json` already exists, merge the hooks into it — do not overwrite existing settings.

Also add a rule to the project's `CLAUDE.md` (create if it doesn't exist) reinforcing the instruction:

```
NEVER use --no-verify or --no-gpg-sign with git commands. Pre-commit hooks must always run. If a hook fails, fix the underlying issue instead of bypassing it.
```

### 5. Initialize CLAUDE.md

Generate a project-level `CLAUDE.md` that gives Claude (and other AI agents) the context they need to work effectively in this codebase. If `CLAUDE.md` already exists, merge new sections into it — do not overwrite existing content.

**Gather context first:**
- Read `package.json` for project name, description, scripts, and dependencies
- Read `README.md` (if it exists) for project purpose and setup instructions
- Read `docs/PRD.md` and `docs/ARCHITECTURE.md` (if they exist) for domain and design context
- Scan the top-level directory structure and key source directories to understand the layout
- Check for frameworks, ORMs, and major libraries in dependencies

**Write the following sections:**

1. **Project overview** — One-paragraph description of what this project is, its purpose, and its primary technology stack.

2. **Architecture** — Brief summary of the architecture (monolith, monorepo, client-server, etc.), key directories, and how they relate. Reference `docs/ARCHITECTURE.md` if it exists rather than duplicating it.

3. **Key commands** — List the common development commands (`dev`, `build`, `test`, `lint`, `typecheck`, `format`) with the correct package manager prefix. Only include commands that actually exist in `package.json` scripts.

4. **Code style and conventions** — Note any conventions visible from the codebase: naming patterns (kebab-case files, PascalCase components), import style (absolute vs relative), test file location (`__tests__/` vs co-located `.test.ts`), and any linter/formatter config.

5. **Rules** — Mandatory rules for AI agents working in this repo. Always include the hook guard rule from step 4. Add any other rules derived from the project's linter config or existing `CLAUDE.md` content.

Keep the file concise — aim for under 80 lines. Prefer short bullet points over prose. Do not include information that's already obvious from file names or standard framework conventions.

### 6. Vercel Best Practices

Install Vercel's agent skills for framework-specific guidance.

Read [references/vercel-best-practices.md](references/vercel-best-practices.md) for details.

Skip if the project doesn't use Vercel or a Vercel-supported framework.

### 7. Verify

After setup, verify everything works:

```bash
# Pre-commit hook fires correctly
git add -A && git commit --dry-run

# CI workflow is valid YAML
cat .github/workflows/ci.yml | python3 -c "import sys, yaml; yaml.safe_load(sys.stdin)"

# Scripts exist and run
<run-command> lint
<run-command> test
<run-command> build
```

Report results to user.

## Missing Tooling

If the project lacks lint/format/test tooling, suggest and install sensible defaults:

| Tool | Default | When |
|------|---------|------|
| Linter | `eslint` | No linter configured |
| Formatter | `prettier` | No formatter configured |
| Test runner | `vitest` | No test runner configured |
| Typecheck | `tsc --noEmit` | TypeScript project, no typecheck script |

Ask the user before installing new tooling — do not assume.