claude-skills/skills/project-bootstrap/SKILL.md

name, description

name

description

project-bootstrap

Initializes or upgrades a project in the current folder: git, .gitignore, README.md, .wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers. Use this skill when the user says "initialize project", "bootstrap", "setup project", "upgrade project", "add wiki", "add tasks", "start project", "set everything up", or launches the agent in a new or existing folder and wants to configure the workspace. Trigger even if the user just says "let's start a project" or "set it all up".

Project Bootstrap

Sets up a complete working environment for a monorepo project in one pass. Operates in two modes: init (new project) and upgrade (existing project).

---

Step 0 — Detect mode

Check what already exists in the current directory:

ls -la
git rev-parse --git-dir 2>/dev/null && echo "git:yes" || echo "git:no"
[ -d .wiki ] && echo "wiki:yes" || echo "wiki:no"
[ -d .tasks ] && echo "tasks:yes" || echo "tasks:no"
[ -f CLAUDE.md ] && echo "claude:yes" || echo "claude:no"
[ -f README.md ] && echo "readme:yes" || echo "readme:no"

Show the user a summary in one block — what was found, what will be created:

Found:   ✅ git  ❌ .wiki  ✅ .tasks  ❌ CLAUDE.md  ✅ README.md
Create:        .wiki             CLAUDE.md
Skip:    git (exists)  .tasks (exists)  README.md (exists)

Ask one question: "Looks right? Shall we proceed?" — and wait for confirmation. Create nothing before confirmation.

---

Step 1 — Git

If git is not initialized:

git init

If .gitignore does not exist — create from template assets/.gitignore.template. If it exists — leave it untouched.

---

Step 2 — README.md

If it does not exist — create a minimal one:

# <project folder name>

## About
<!-- Describe the project here -->

## Quick start
<!-- Instructions for running the project -->

If it exists — leave it untouched.

---

Step 3 — .wiki/

If .wiki/ already exists — skip it, notify the user.

If it does not exist — create the canonical Karpathy LLM-Wiki layout (gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). The wiki-maintainer skill expects exactly this shape; do not invent your own names.

.wiki/
  CLAUDE.md          ← schema: project-specific wiki conventions
  index.md           ← catalog of all pages (by type), updated on every ingest
  log.md             ← append-only op log: ## [YYYY-MM-DD] op | desc
  overview.md        ← single human-readable project overview
  raw/
    README.md        ← raw/ is immutable; this file documents that
  entities/          ← entity pages (people, services, modules) — empty .gitkeep
  concepts/          ← concept / design decision pages — empty .gitkeep
  packages/          ← package pages — empty .gitkeep
  sources/           ← one summary per ingested source — empty .gitkeep

Page-level workflow (ingest, query, lint) and file formats are owned by the wiki-maintainer skill. Bootstrap only lays the skeleton; the skill takes over from there.

.wiki/CLAUDE.md (schema)

# Wiki Schema — <project name>

Project-specific wiki conventions. Read this before any wiki operation.

This wiki follows Karpathy's LLM Wiki pattern:
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**

The `wiki-maintainer` skill enforces the workflow and file formats. This
file overrides the skill where they conflict.

## Page types

- `entities/` — discrete things the project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; frontmatter carries `ingested:` and `raw_path:`.
- `overview.md` — single project-wide overview.

## Naming

- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.

## Domain conventions

<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->

.wiki/index.md

# Wiki Index

Catalog of all wiki pages. One line per page, organized by type. The agent updates this on every ingest.

## Overview

- [overview.md](overview.md) — project overview

## Entities

<!-- (none yet) -->

## Concepts

<!-- (none yet) -->

## Packages

<!-- (none yet) -->

## Sources

<!-- (none yet) -->

.wiki/log.md

# Wiki Log

Append-only operation log. One entry per operation. Format:

\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`

Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.

Parseable: `grep "^## \[" .wiki/log.md | tail -20`.

---

## [<today's date>] init | bootstrap empty wiki via project-bootstrap

.wiki/overview.md

# <project name> — overview

<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->

.wiki/raw/README.md

# Raw Sources

**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.

Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.

For large or path-sensitive sources that live outside the repo, register them here:

\`\`\`
- short-name → /absolute/path/to/source
\`\`\`

The empty subdirectories (entities/, concepts/, packages/, sources/) each get a .gitkeep so git tracks them.

---

Step 4 — .tasks/

If .tasks/ already exists — skip it, notify the user.

If it does not exist — create the structure:

.tasks/
  STATUS.md     ← task board

Contents of STATUS.md:

# Task Board
_Updated: <today's date>_

<!-- Tasks will appear here as work progresses.
     Skill is activated by the phrase: use task management system -->

---

Step 5 — CLAUDE.md

If CLAUDE.md already exists — show its contents and ask: "CLAUDE.md already exists. Append skill triggers to the end, or leave as is?"

If it does not exist — create from template assets/CLAUDE.md.template.

Template contents:

# CLAUDE.md
# Agent instructions. Each line is a trigger for an installed skill.

talk like a caveman
use superpowers
use project wiki
use task management system
we're on Windows

The we're on Windows line activates the active-platform skill and pins the project's default platform to Windows / PowerShell — so generated commands and README quick-starts use PS-native syntax. Bootstrapping on a Linux or macOS host? Substitute we're on Linux or we're on macOS instead.

---

Step 6 — Commit

git add .
git commit -m "chore: bootstrap project structure"

If the repo already had commits — commit only the files just created:

git add .wiki/ .tasks/ CLAUDE.md .gitignore README.md
git commit -m "chore: upgrade project structure"

---

Step 7 — Summary

Print a final report:

✅ Done! Created:
  .wiki/          — project wiki (Karpathy method)
  .tasks/         — task tracking system
  CLAUDE.md       — skill triggers
  .gitignore      — standard template
  README.md       — starter file

Skipped (already existed):
  git             — left untouched

Next step: describe the project in README.md and start your first task —
say "use task management system".

---

Rules

• Never overwrite existing files without explicit user confirmation
• Always show the plan first — one question, one confirmation
• Never invent details — if the project already exists, read what's there
• Commit only what was just created — do not touch the rest of the file tree
• Commit automatically after each successful step, no extra questions
• Push only after explicit user confirmation — ask "Push to remote?" and wait for "yes"