Files

vitya 8c547d73af 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)

2026-05-05 21:21:19 +03:00

6.9 KiB

Raw Permalink Blame History

bootstrap-skill-deps-check

Goal

Refactor project-bootstrap Step 5.6 (single-skill superpowers plugin detector) into a single, generic Step 5.6 "Skill dependencies check" that walks the canonical CLAUDE.md template, looks up each trigger line against a trigger → fulfiller map, detects what's missing on the host, and prints one chat-only block with prioritized install commands. Replaces the per-skill Step 5.X shape (which doesn't scale: every new canonical trigger would need its own mirror section). Subsumes the deferred [bootstrap-recommend-projects-meta] task — that task was the seed of this generalization. Bumps project-bootstrap 1.6.0 → 1.7.0 (MINOR — adds capability without breaking existing flow).

Key files

skills/project-bootstrap/SKILL.md — replace Step 5.6 contents, bump version: 1.6.0 → 1.7.0
skills/project-bootstrap/README.md — Workflow Step 5.6 description + (optional) See also
skills/project-bootstrap/assets/CLAUDE.md.template — source of truth for the trigger list (no change here, but the new step reads from it)
skills/project-bootstrap/assets/skill-deps-map.md (or .json / inline in SKILL.md) — the trigger → fulfiller table; new file or inline section, decide during impl
.wiki/concepts/bootstrap-skill-deps-check.md — design rationale (why generic over per-skill mirrors, kind: skill vs plugin, MCP server caveat)
.tasks/STATUS.md — supersede [bootstrap-recommend-projects-meta]; mark this task active when started
dist/project-bootstrap.skill — rebuild after changes

Decisions log

2026-05-05: chose generic Step 5.6 over Step 5.7 mirror per missing-skill shape. Rationale: bootstrap-recommend-projects-meta (deferred task) + the analogous gap for setup-interns / using-interns / pulling-before-work / project-discipline would all need their own mirror sections — that's a 5×Step-5.X explosion. Single generic step reads the template (already canonical), maps each trigger to its fulfiller, prints one block.
2026-05-05: scope of detection is the canonical CLAUDE.md template's trigger lines. Don't try to detect arbitrary user-added lines — the project-bootstrap contract is "we own canonical triggers; non-canonical lines are user's responsibility".
2026-05-05: differentiate kind: skill (install via bash scripts/install.sh <name>) from kind: plugin (install via /plugin install <name>@<marketplace>). The install-command line in the chat block differs between the two; one mapping table that flags kind keeps the recommendation block honest.
2026-05-05: MCP-server-backed skills (using-context7, using-projects-meta, using-interns) — only check the using-X policy skill. If MCP isn't registered, the using-X Prerequisites pointer fires setup-X at first use; bootstrap doesn't need to duplicate that detection. Keeps the Step simple.
2026-05-05: hard rule from current Step 5.6 (never auto-install) carries over verbatim. Slash-commands aren't callable from a skill; silently mutating ~/.claude/skills/ is overreach. Recommendation only — chat block with copy-pasteable commands.

Open questions

Storage of the map: inline in SKILL.md (simplest, single source of truth), or separate assets/skill-deps-map.md / .json (cleaner, programmatically parseable)? Inline probably fine for MVP — the table is short.
When the user pinned a non-canonical platform line (e.g. we're on Linux on a Windows host), the platform-line check is already handled in Step 5 idempotent merge. Step 5.6 should ignore the platform line entirely — same dependency (active-platform skill) regardless of which platform.
How to handle a CLAUDE.md the user has removed canonical triggers from on purpose? Step 5.6 reads from CLAUDE.md (the actual project file), not from template, so removed lines silently skip the check — correct behavior. Verify in implementation.
Optional polish: print a one-line "✅ all skill dependencies satisfied" when nothing is missing, to make the silent-success case visible. Probably worth it; very low cost.

Completed steps

2026-05-05: read skills/project-bootstrap/SKILL.md + README to confirm scope (Step 5.6 located lines 349-389; README Workflow item 5).
2026-05-05: wrote .wiki/concepts/bootstrap-skill-deps-check.md design page (rationale, skill/plugin kind, MCP-server caveat, source-of-truth invariant).
2026-05-05: replaced SKILL.md Step 5.6 in place with generic trigger → fulfiller map (9 rows) + algorithm + recommendation block. Hard rule "never auto-install" preserved verbatim. ✅ all-satisfied case prints one line.
2026-05-05: bumped SKILL.md version: 1.6.0 → 1.7.0 (MINOR per project-discipline Rule 3 — adds capability, absorbs prior single-skill detector cleanly).
2026-05-05: updated README.md Workflow Step 5.6 description to match the new shape.
2026-05-05: rebuilt dist/project-bootstrap.skill via scripts/build.sh, reinstalled to ~/.claude/skills/project-bootstrap/ via scripts/install.sh; verified installed version: 1.7.0.
2026-05-05: updated .wiki/index.md (added concept entry) and .wiki/log.md (ingest + decision lines).
2026-05-05: closed sibling [bootstrap-recommend-projects-meta] 🟢 in same commit (closed by absorption — note in commit message).

Notes

Triggers in current template (2026-05-05) and their fulfillers — initial seed for the map:

Trigger	Fulfiller	Kind	Install
`talk like a caveman`	`caveman`	skill	`bash scripts/install.sh caveman`
`use superpowers`	`superpowers@claude-plugins-official`	plugin	`/plugin install superpowers@claude-plugins-official`
`use project wiki`	`using-wiki`	skill	`bash scripts/install.sh using-wiki`
`use task management system`	`using-tasks`	skill	`bash scripts/install.sh using-tasks`
`check across all projects`	`using-projects-meta`	skill	`bash scripts/install.sh using-projects-meta`
`pull remote before work`	`pulling-before-work`	skill	`bash scripts/install.sh pulling-before-work`
`follow project discipline`	`project-discipline`	skill	`bash scripts/install.sh project-discipline`
`delegate to interns when allowed`	`using-interns`	skill	`bash scripts/install.sh using-interns`
`we're on Windows` / `we're on Linux` / `we're on macOS`	`active-platform`	skill	`bash scripts/install.sh active-platform`

Detection paths: ~/.claude/skills/<name>/SKILL.md for skills; ~/.claude/plugins/installed_plugins.json (plugins.<name>) for plugins. Both paths identical on Windows / Linux / macOS under ~.
Once shipped, close [bootstrap-recommend-projects-meta] with a note pointing at the commit that absorbed it.
Versioning per project-discipline Rule 3: 1.6.0 → 1.7.0 (MINOR — adds capability, doesn't break the existing Step-5.6 superpowers detector since it absorbs it cleanly).

6.9 KiB Raw Permalink Blame History Unescape Escape