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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user