feat(project-bootstrap): generic Step 5.6 skill-deps check

Collapse Step 5.6 from a single-skill detector (only the
superpowers@claude-plugins-official plugin) into a generic
`trigger -> fulfiller` table walker that scales to every canonical
CLAUDE.md trigger.

Inline 9-row map in SKILL.md covers: caveman, superpowers (kind: plugin),
using-wiki, using-tasks, using-projects-meta, pulling-before-work,
project-discipline, using-interns, active-platform. The `kind` flag
(skill | plugin) drives which install command is emitted in the chat-only
recommendation block. Detection paths: ~/.claude/skills/<name>/SKILL.md
for skills, plugins.<id> in ~/.claude/plugins/installed_plugins.json
for plugins.

Algorithm: read project's CLAUDE.md -> match each non-comment line vs
map (substring + tolower, mirrors Step 5 idempotent merge) -> for each
canonical match check disk -> print one chat block listing every missing
fulfiller with copy-pasteable install commands, OR a single
"all dependencies satisfied" line. User-custom lines and removed
canonical lines are silently skipped. Hard rule "never auto-install"
preserved verbatim.

version: 1.6.0 -> 1.7.0 (MINOR per project-discipline Rule 3 -- adds
capability, absorbs prior superpowers-only detector cleanly).

Closes [bootstrap-skill-deps-check] (.tasks/STATUS.md done).
Closes [bootstrap-recommend-projects-meta] by absorption -- the deferred
mirror task was the seed of this generalization; the generic walker now
handles using-projects-meta along with everything else, no per-skill
mirror needed.

Design rationale at .wiki/concepts/bootstrap-skill-deps-check.md:
- why generic over per-skill mirrors (5x mirror explosion)
- skill vs plugin kind distinction
- MCP-server-backed skills (only check using-X policy skill;
  setup-X self-fires via Prerequisites pointer)
- source-of-truth invariant: SKILL map + assets/CLAUDE.md.template
  must stay in sync (a future CI lint could enforce)
This commit is contained in:
2026-05-05 21:21:19 +03:00
parent 2f7943f06f
commit 8c547d73af
8 changed files with 206 additions and 47 deletions

View File

@@ -59,10 +59,13 @@ projects bootstrapped at different times debuggable.
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
`project-bootstrap`, `setup-wiki`, `setup-tasks`, `project-discipline`,
`setup-interns`, and `using-interns` used.
5. **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.
5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list
in `CLAUDE.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.

View File

@@ -1,6 +1,6 @@
---
name: project-bootstrap
version: 1.6.0
version: 1.7.0
description: >
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.
@@ -346,47 +346,94 @@ If a delegated setup-skill is unavailable on this machine (e.g. user installed o
---
## Step 5.6 — Recommend `superpowers` plugin (chat-only, never auto-install)
## Step 5.6 — Skill dependencies check (chat-only, never auto-install)
The `CLAUDE.md` template just written contains `use superpowers` as a trigger.
That trigger is a no-op unless the official `superpowers` plugin is installed
on the host. On a fresh machine the plugin is often absent, and the user
won't know the trigger is silently dead. Detect and recommend.
The `CLAUDE.md` template just written contains canonical trigger lines.
Each one is a no-op unless the corresponding skill or plugin is installed
on the host. On a fresh machine these are often absent, and the user
won't know the trigger is silently dead. Detect what's missing on this
machine and print one informational block in chat — never write into any
project file, never auto-install.
Read `~/.claude/plugins/installed_plugins.json`. The path is identical on
Windows / Linux / macOS — `~` resolves correctly under git-bash too.
### Trigger → fulfiller map
Look for the key `superpowers@claude-plugins-official` under `plugins`.
Two outcomes:
Source of truth for this map is the canonical `assets/CLAUDE.md.template`.
When a new trigger is added there, also add a row here in the same commit.
Mismatch between template and map → silent gaps in the recommendation.
- **Installed** — say nothing. Skip to Step 6.
- **Missing** (key absent, or the JSON file itself doesn't exist) — print
this block in chat exactly once. Do **not** write it into any project file:
| Trigger line in `CLAUDE.md` | Fulfiller | Kind | Detection path | Install command |
|---|---|---|---|---|
| `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` |
| `use superpowers` | `superpowers@claude-plugins-official` | plugin | key `plugins["superpowers@claude-plugins-official"]` in `~/.claude/plugins/installed_plugins.json` | `/plugin install superpowers@claude-plugins-official` |
| `use project wiki` | `using-wiki` | skill | `~/.claude/skills/using-wiki/SKILL.md` | `bash scripts/install.sh using-wiki` |
| `use task management system` | `using-tasks` | skill | `~/.claude/skills/using-tasks/SKILL.md` | `bash scripts/install.sh using-tasks` |
| `check across all projects` | `using-projects-meta` | skill | `~/.claude/skills/using-projects-meta/SKILL.md` | `bash scripts/install.sh using-projects-meta` |
| `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` |
| `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` |
| `delegate to interns when allowed` | `using-interns` | skill | `~/.claude/skills/using-interns/SKILL.md` | `bash scripts/install.sh using-interns` |
| `we're on Windows` / `we're on Linux` / `we're on macOS` | `active-platform` | skill | `~/.claude/skills/active-platform/SKILL.md` | `bash scripts/install.sh active-platform` |
```
Recommended: install the official `superpowers` plugin
### Algorithm
CLAUDE.md now contains `use superpowers`, but that trigger is a no-op
until the plugin is installed. With it, every session auto-loads
brainstorming, planning, code-review, debugging, and TDD skills.
1. Read the project's `CLAUDE.md` (just-written or pre-existing). Extract
every non-empty, non-comment line — these are the active triggers for
THIS project. The user may have removed canonical lines on purpose;
respect that — only check what's actually in the file.
2. Match each line against the trigger column above using `trim` + `tolower`
substring (same matching as Step 5 idempotent merge). Lines that don't
match any row are user-custom — skip silently. The platform line matches
the `active-platform` row regardless of which platform is pinned.
3. For each matched canonical line, check the detection path:
- `kind: skill` → does `~/.claude/skills/<name>/SKILL.md` exist?
- `kind: plugin` → does `~/.claude/plugins/installed_plugins.json` contain
the plugin key under `plugins`? (Treat malformed JSON as "missing" and
continue — don't crash the bootstrap over a detection edge case.)
4. Collect every fulfiller that's missing. Two outcomes:
Install (run inside Claude Code):
/plugin install superpowers@claude-plugins-official
- **All present** — print one line:
Source: https://github.com/anthropics/claude-plugins-official
```
✅ all skill dependencies satisfied — every CLAUDE.md trigger has its fulfiller on this host.
```
After install + Claude Code restart, the trigger picks it up.
```
Skip to Step 6.
**Hard rule — never auto-install.** Slash commands aren't callable from a
skill, and silently mutating user-level plugin state without consent is
overreach. The recommendation is informational. The user can install it
later, ignore it entirely, or remove the `use superpowers` line from
`CLAUDE.md` if they prefer a leaner setup.
- **Some missing** — print one block in chat exactly once. Do **not**
write it into any project file:
If the JSON file is malformed (rare), treat as "missing" and print the
recommendation. Do not crash the bootstrap over a plugin-detection edge
case — the file isn't ours to fix here.
```
Recommended: install the following to fulfill CLAUDE.md triggers
The triggers below are present in CLAUDE.md but their fulfillers are
missing on this machine — they're silently no-ops until installed:
trigger fulfiller (kind)
<trigger-line> <fulfiller> (<kind>)
<trigger-line> <fulfiller> (<kind>)
Install (run inside Claude Code or terminal):
<install command 1>
<install command 2>
After install + (for plugins) a Claude Code restart, the triggers pick
them up.
```
### Notes
- **MCP-server-backed skills** (`using-context7`, `using-projects-meta`,
`using-interns`) — only the `using-X` policy skill is checked here. If
the MCP isn't registered, the `using-X` Prerequisites pointer fires
`setup-X` at first use; bootstrap doesn't duplicate that detection.
- The `~/.claude/skills/` and `~/.claude/plugins/` paths resolve identically
on Windows / Linux / macOS — `~` works under git-bash too.
- **Hard rule — never auto-install.** Slash commands aren't callable from a
skill, and silently mutating user-level skill / plugin state without
consent is overreach. The recommendation is informational. The user can
install some / all / none of the recommendations, or remove canonical
lines from `CLAUDE.md` to lean the project's trigger set down.
## Step 6 — Commit