# 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 `AGENTS.md` (canon) with skill triggers + `CLAUDE.md` legacy pointer.

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

Мета в сервисе (решения 14/15): вики и таски проекта живут в **mappa**
(`using-wiki` / `using-tasks` v2 — mappa-тулы), файловый `.wiki/` / `.tasks/`
не создаётся. `setup-wiki` / `setup-tasks` умерли (нечего настраивать);
для проектов вне mappa файловый layout создаётся ad-hoc по канону
Karpathy / `.tasks/` (см. using-wiki/using-tasks, legacy-раздел).

## 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. |
| вики | mappa (`using-wiki`) | сущности `type=wiki` в сервисе; файловый layout — только вне mappa (легаси). |
| таски | mappa (`using-tasks`) | сущности `type=task` в сервисе; файловый `.tasks/` — только вне mappa (легаси). |
| `AGENTS.md` | `assets/AGENTS.md.template` | **Canon** — skill triggers (`use project wiki`, `use task management system`, 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. |
| `CLAUDE.md` | generated pointer | `Canon is AGENTS.md. Read AGENTS.md.` — legacy pointer for tooling that looks for the old name. |
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |

## Workflow

1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`,
   `AGENTS.md`, `CLAUDE.md`, `README.md` — and print a single summary block: what was
   found, what will be created, what will be skipped.
2. **Confirm.** One question, one confirmation. Nothing is written before the
   user agrees.
3. **Steps 1–5.** Create or skip each piece in order — git, README, вики/таски
   (mappa, см. using-wiki/using-tasks), `AGENTS.md` + `CLAUDE.md` pointer.
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
   `project-bootstrap`, `setup-interns`, and
   `using-interns` used.
5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list
   in `AGENTS.md`, look each up in an embedded `trigger → fulfiller` map,
   detect what's missing on this host (`~/.claude/skills/<name>/SKILL.md`
   for skills, `~/.claude/plugins/installed_plugins.json` for plugins),
   and print one chat-only block listing every missing fulfiller with a
   copy-pasteable install command. Prints a single ✅ line when nothing
   is missing. Never auto-installs, never modifies project files.
6. **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.
7. **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):**

```powershell
bash scripts/install.sh project-bootstrap
```

**Linux / macOS (bash):**

```bash
bash scripts/install.sh project-bootstrap
```

`install.sh` works on Windows under git-bash. A native `install.ps1` is
[planned](../../.tasks/STATUS.md) but not required.

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

## See also

- [`using-wiki`](../using-wiki/) — runtime policy for the mappa wiki (v2).
- [`using-tasks`](../using-tasks/) — runtime policy for the mappa task board (v2).
- [`mappa-vitya-project-discipline`](../mappa-vitya-project-discipline/)
  — vitya-flavored cross-project discipline (activated per-project by
  `mappa-bootstrap`, which selects the methodology flavor).
- [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) —
  pair behind the `delegate to interns when allowed` trigger; cheap-LLM
  delegation under a per-session permission grant.
- Karpathy's LLM Wiki gist:
  <https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>