Files

vitya 68fe9a8c1c feat(project-bootstrap): v1.3.0 — idempotent CLAUDE.md merge on upgrade

Step 5 was binary on upgrade (append whole template / leave alone), so
projects bootstrapped before v1.2.0 silently missed new canonical triggers
(`check across all projects`, `we're on Windows`) on re-run. Now upgrade
reads existing CLAUDE.md, substring-diffs vs template, preserves a
deliberately-pinned platform line, and appends only missing lines after
explicit confirm. Re-runs are no-ops.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-30 15:06:06 +03:00

4.7 KiB

Raw Blame History

project-bootstrap

Initializes or upgrades a project workspace in one pass: git, .gitignore, README.md, .wiki/ (Karpathy's LLM Wiki layout), .tasks/ (per-task board), and CLAUDE.md with skill triggers.

Operates in two modes, picked automatically:

init — empty or near-empty folder. Creates everything from scratch.
upgrade — existing project. Detects what's already there, only fills the gaps. Never overwrites without explicit confirmation.

When it triggers

The skill auto-activates on phrases like:

"initialize project", "bootstrap", "setup project"
"upgrade project", "add wiki", "add tasks"
"start project", "set everything up"
"let's start a project", "init"

It also triggers when an agent is launched in a fresh folder that the user clearly intends to turn into a workspace.

Prerequisites

project-bootstrap does not lay out .wiki/ or .tasks/ by itself — it delegates to two companion skills, which must be installed on the machine running it:

setup-wiki — creates the canonical .wiki/ layout.
setup-tasks — creates the canonical .tasks/ layout.

If either is missing, project-bootstrap stops with a clear error rather than falling back to ad-hoc creation. This keeps layout drift between projects bootstrapped at different times debuggable.

What it creates

Path	Source	Notes
`.git/`	`git init`	Skipped if repo already initialized.
`.gitignore`	`assets/.gitignore.template`	Skipped if file exists.
`README.md`	minimal stub	Skipped if file exists.
`.wiki/`	delegated to `setup-wiki`	Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`.
`.tasks/`	delegated to `setup-tasks`	Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files.
`CLAUDE.md`	`assets/CLAUDE.md.template`	Skill triggers (`use superpowers`, `use project wiki`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops.
`.wiki/concepts/bootstrap-manifest.md`	generated	Records which skill versions initialized the project, so cross-project layout drift is debuggable.

Workflow

Detect mode. Inspect the current directory — git, .wiki/, .tasks/, CLAUDE.md, README.md — and print a single summary block: what was found, what will be created, what will be skipped.
Confirm. One question, one confirmation. Nothing is written before the user agrees.
Steps 1–5. Create or skip each piece in order — git, README, .wiki/, .tasks/, CLAUDE.md. Steps 3 and 4 delegate to the setup-skills.
Step 5.5. Write bootstrap-manifest.md recording the versions of project-bootstrap, setup-wiki, and setup-tasks used.
Step 5.6. Detect the official superpowers@claude-plugins-official plugin via ~/.claude/plugins/installed_plugins.json. If absent, print a one-time chat recommendation with the install command and upstream link. Never auto-installs, never modifies project files.
Commit. chore: bootstrap project structure for fresh repos, or chore: upgrade project structure adding only the new files for existing ones. Pushes only on explicit user request.
Summary. Final report — what was created, what was skipped, suggested next step.

Rules

Never overwrite an existing file without explicit user confirmation.
Always show the plan before touching the filesystem.
Never invent project details — read what's already there.
Commit only files just created — never touch the rest of the tree.
Push only after the user explicitly says so.

Install

From the repo root:

Windows (PowerShell):

bash scripts/install.sh project-bootstrap

Linux / macOS (bash):

bash scripts/install.sh project-bootstrap

install.sh works on Windows under git-bash. A native install.ps1 is planned but not required.

The skill installs to ~/.claude/skills/project-bootstrap/. Override the target with CLAUDE_SKILLS_DIR=/path bash scripts/install.sh ….

4.7 KiB Raw Blame History Unescape Escape