merge: v2.5.3 — npx autoskills recommender for /v:onboard

Author: copeus

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-v",
       "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert + Context7 library validator), disjoint partitioning, manifest-driven multi-backend dispatch (Claude + Codex + Antigravity + Cursor), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, narrow Sonnet exception)",
-      "version": "2.5.2",
+      "version": "2.5.3",
       "source": "./",
       "author": {
         "name": "Oleg",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-v",
   "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert advisor + library/doc validator via Context7), disjoint file partitioning, manifest-driven multi-backend dispatch (Claude + headless Codex + Antigravity + Cursor workers), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode for multi-feature builds, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall\u2192action bridge), and batched parallel dispatch (Opus default, Sonnet for narrow junior-task carve-out), plus /v:onboard — a project-onboarding command that builds a citation-verified knowledge base + AGENTS.md/CLAUDE.md bridge behind a human gate. Auto-intercepts brainstorming \u2192 writing-plans \u2192 execution transitions.",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "author": {
     "name": "Oleg",
     "email": "copeus@gmail.com"

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to **superpowers-v (Compound V)** are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning.
 
+## [2.5.3] — 2026-07-05
+
+### Added — `npx autoskills` recommender for `/v:onboard`
+
+- **Third-party skill discovery.** `/v:onboard` now recommends [`npx autoskills`](https://www.autoskills.sh/) when a project manifest is detected — a new `recommend-autoskills` subcommand in `scripts/compound-v-onboard.py` flags applicability (`package.json`, `pyproject.toml`, `requirements.txt`, `Gemfile`, `go.mod`, `Cargo.toml`, `composer.json`, `pom.xml`, `build.gradle`, or a top-level `*.tf`), with the marker file as **evidence**; an unknown repo yields `applicable: false` (no false recommendation).
+- **Present-only, gated `--dry-run`, never auto-installs.** In DIAGNOSE, onboarding surfaces the recommendation and — **behind a human confirm** — runs the **preview** `npx autoskills --dry-run` through the process-group timeout supervisor with `stdin </dev/null` (the v2.5.0 external-launch invariant), to show *which* skills it would install. The real install stays the user's own action (autoskills has its own confirm + SHA-256 verification).
+- **Auto-trigger-degradation caution.** Because mass-installing overlapping skills degrades auto-triggering across the whole skill set (the onboarding **Skills stance**), the recommendation always carries a loud caution to review the dry-run and prefer a focused subset.
+- **Built with TDD, dogfooded, cross-model Codex-verified.** 5 selftest checks (manifest → applicable + evidence + `--dry-run` command; empty → not applicable; `pyproject.toml` → applicable; a top-level `main.tf` → applicable with the filename as evidence; a *directory* named `*.tf` → not applicable). Dogfood on superpowers-v itself (no standard manifest) → `applicable: false` — the negative path. **Codex cross-model verification** (the model that writes ≠ the model that checks) caught **two** real bugs in the Terraform branch — the evidence was the literal `"*.tf"` instead of the actual filename, and a *directory* named `foo.tf` was a false positive — **both accepted and fixed**, each with added selftest coverage.
+
 ## [2.5.2] — 2026-07-03
 
 ### Added

commands/v-onboard.md

@@ -33,5 +33,7 @@ indexing is [`/v:memory-refresh`](v-memory-refresh.md).
 When the pipeline (or refresh) finishes, report what was written, what the doctor recommended
 (advisory — including **MCP / external-tool recommendations** via `recommend-mcp`: CLI-over-MCP so a
 `github.com` remote yields the `gh` CLI not a GitHub MCP, least-privilege flags pre-filled, plus any
-lethal-trifecta warning with its remedy), whether an `.mcp.json` diff was written (**only** on
-confirmation, merged additively), and that `/v:memory-refresh` re-indexed the committed docs.
+lethal-trifecta warning with its remedy; **plus third-party skills via `npx autoskills`** —
+present-only, a gated `--dry-run` preview, never auto-installed), whether an `.mcp.json` diff was
+written (**only** on confirmation, merged additively), and that `/v:memory-refresh` re-indexed the
+committed docs.

docs/superpowers/plans/2026-07-05-v2.5.3-autoskills.md

@@ -0,0 +1,127 @@
+# `npx autoskills` recommender (v2.5.3) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:test-driven-development for the toolkit task.
+
+**Goal:** `/v:onboard` recommends `npx autoskills` (present-only) for a recognizable stack, previews it behind a gated `--dry-run`, and cautions about auto-trigger degradation — never auto-installs.
+
+**Architecture:** A small `recommend-autoskills` subcommand + `recommend_autoskills()` detector in `scripts/compound-v-onboard.py`; prose wiring in `onboarding.md` (DIAGNOSE + §11) and `v-onboard.md`.
+
+**Tech Stack:** Python 3.9 stdlib, Markdown docs, JSON version files.
+
+## Global Constraints
+- **Never auto-install** — onboarding runs at most `npx autoskills --dry-run`, only behind a human confirm; the real install is the user's action.
+- **External `npx` is untrusted** — any invocation goes through `compound-v-run-with-timeout.py` with `stdin </dev/null` (the v2.5.0 launch invariant).
+- **Auto-trigger caution always surfaced** (overlapping skills degrade triggering — onboarding §11).
+- **Deterministic + evidence-cited** — cite the marker file; unknown repo ⇒ `applicable: false`.
+- **Version lockstep:** `plugin.json` + `marketplace.json` → `2.5.3`.
+
+## File Partition
+| Task | Files |
+|---|---|
+| T1 | `scripts/compound-v-onboard.py` (detector + subcommand + selftest) |
+| T2 | `skills/compound-v/onboarding.md`, `commands/v-onboard.md` |
+| T3 | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `CHANGELOG.md` |
+
+---
+
+### Task 1: `recommend_autoskills()` detector + subcommand
+**Files:** Modify `scripts/compound-v-onboard.py`
+
+**Interfaces (Produces):** `recommend_autoskills(repo) -> {applicable: bool, evidence: str|None, command: str|None, caution: str|None}`; CLI `recommend-autoskills --repo .`.
+
+- [ ] Step 1: Add constants + function (near the MCP recommender helpers):
+
+```python
+AUTOSKILLS_MARKERS = ("package.json", "pyproject.toml", "requirements.txt", "Gemfile",
+                      "go.mod", "Cargo.toml", "composer.json", "pom.xml", "build.gradle")
+AUTOSKILLS_CAUTION = ("autoskills installs multiple stack skills; overlapping skill descriptions "
+                      "can degrade auto-triggering across your WHOLE skill set (onboarding Skills "
+                      "stance). Review the --dry-run and prefer a focused subset before installing.")
+
+
+def recommend_autoskills(repo):
+    """`npx autoskills` applicability: any recognizable project manifest means it can match stack
+    skills. Present-only — the gated --dry-run + the user-run install are the onboarding walk's job.
+    Returns {applicable, evidence, command, caution}."""
+    ev = None
+    for marker in AUTOSKILLS_MARKERS:
+        if os.path.isfile(os.path.join(repo, marker)):
+            ev = marker
+            break
+    if ev is None:
+        try:
+            if any(f.endswith(".tf") for f in os.listdir(repo)):
+                ev = "*.tf"
+        except OSError:
+            pass
+    if ev is None:
+        return {"applicable": False, "evidence": None, "command": None, "caution": None}
+    return {"applicable": True, "evidence": ev,
+            "command": "npx autoskills --dry-run", "caution": AUTOSKILLS_CAUTION}
+```
+
+- [ ] Step 2: Add the subcommand in `build_parser` (after `recommend-mcp`):
+
+```python
+    sp = sub.add_parser("recommend-autoskills"); sp.add_argument("--repo", default=".")
+    sp.add_argument("--json", action="store_true")
+```
+
+and in `main` (before the help fallback):
+
+```python
+    if args.cmd == "recommend-autoskills":
+        print(json.dumps(recommend_autoskills(os.path.abspath(args.repo)), indent=2))
+        return 0
+```
+
+- [ ] Step 3: Selftest (append inside the recommend-mcp `try:` block or a fresh tempdir):
+
+```python
+        # --- recommend-autoskills (v2.5.3) ---
+        d8 = tempfile.mkdtemp()
+        try:
+            with open(os.path.join(d8, "package.json"), "w") as fh:
+                fh.write("{}")
+            r8 = recommend_autoskills(d8)
+            check("autoskills: package.json -> applicable, evidence, --dry-run command",
+                  r8["applicable"] and r8["evidence"] == "package.json"
+                  and r8["command"] == "npx autoskills --dry-run" and r8["caution"])
+        finally:
+            shutil.rmtree(d8, ignore_errors=True)
+        d8b = tempfile.mkdtemp()
+        try:
+            with open(os.path.join(d8b, "pyproject.toml"), "w") as fh:
+                fh.write("[project]\n")
+            check("autoskills: pyproject.toml -> applicable",
+                  recommend_autoskills(d8b)["applicable"] is True)
+            os.remove(os.path.join(d8b, "pyproject.toml"))
+            check("autoskills: empty repo -> not applicable",
+                  recommend_autoskills(d8b)["applicable"] is False)
+        finally:
+            shutil.rmtree(d8b, ignore_errors=True)
+```
+
+- [ ] Step 4: `python3 scripts/compound-v-onboard.py --selftest` → OK. CLI smoke on this repo → `applicable: false`. Commit.
+
+---
+
+### Task 2: Onboarding wiring
+**Files:** Modify `skills/compound-v/onboarding.md`, `commands/v-onboard.md`
+
+- [ ] In `onboarding.md` DIAGNOSE (next to the MCP recommender): add the autoskills recommendation — run `recommend-autoskills`; if applicable, surface it + the caution, and **behind a human confirm** run `npx autoskills --dry-run` **through `compound-v-run-with-timeout.py` with `</dev/null`** to preview the skills; **never** the install form; decline ⇒ just recommend the user run it themselves. Add the §11 note that autoskills is the recommended third-party-skill path (present-only + cautioned).
+- [ ] In `v-onboard.md`: extend the finish-report line to mention the autoskills recommendation (present-only, gated `--dry-run`, never auto-installed).
+- [ ] `lint-frontmatter.py` clean. Commit.
+
+---
+
+### Task 3: Version + CHANGELOG + release
+**Files:** `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `CHANGELOG.md`
+
+- [ ] Full regression (all script selftests + lint + CI lockstep) green.
+- [ ] Dogfood `recommend-autoskills` on superpowers-v (→ `applicable: false`, the negative path).
+- [ ] Codex cross-model verify (detector + gated-runner invariants; supervised + `</dev/null`).
+- [ ] Both versions → `2.5.3`; `CHANGELOG.md` `[2.5.3]`. Commit, merge `--no-ff` to main, verify, push, CI green.
+
+## Self-Review
+Spec §4.1 → T1; §4.2/§4.3 → T2; §5 invariants → T1 (evidence, applicable-false) + T2 (supervisor/`</dev/null`, never-install, caution); §6 → T1 selftest + T3 dogfood/Codex; §7 out-of-scope respected. No placeholders. `recommend_autoskills` return shape consistent across T1/T2.

docs/superpowers/specs/2026-07-05-v2.5.3-autoskills-design.md

@@ -0,0 +1,76 @@
+# `npx autoskills` recommender for `/v:onboard` (design, v2.5.3)
+
+**Status:** approved for build (2026-07-05). A sibling of the v2.5.1 MCP recommender — same
+present-only / human-gate ethos, applied to third-party skills.
+
+## 1. What it is
+A DIAGNOSE-step component of `/v:onboard`: when the repo has a recognizable project manifest,
+onboarding **recommends** the third-party skill installer [`npx autoskills`](https://www.autoskills.sh/)
+and — **behind a human confirm** — runs `npx autoskills --dry-run` (a preview, no install) to show
+*which* skills it would install, surfacing a **caution** about auto-trigger degradation. Onboarding
+**never installs** skills itself; the real `npx autoskills` is the user's own gated action.
+
+## 2. Why
+Onboarding already recommends MCP tools (v2.5.1) and which *existing* superpowers-v skills fit
+(§11). `autoskills` extends the "right tools for this stack" story to **third-party skills** —
+detects the stack, matches an audited (SHA-256-verified) registry, installs on confirm. Surfacing
+it (present-only) completes the onboarding tooling picture without us running untrusted code
+unprompted.
+
+## 3. The tension this must respect (responsible doctor)
+The onboarding **Skills stance** (`onboarding.md` §11) deliberately avoids bulk skill generation:
+*"overlapping descriptions degrade auto-triggering across the user's entire skill set."* `autoskills`
+mass-installs skills — the exact risk. So this component **recommends + cautions**, it does not
+auto-install: it must loudly warn that installing many overlapping skills can hurt auto-triggering
+and advise reviewing the `--dry-run` and preferring a focused subset. The user decides.
+
+## 4. Components
+
+### 4.1 Applicability detector — `compound-v-onboard.py recommend-autoskills`
+Deterministic, stdlib. `recommend_autoskills(repo) -> {applicable, evidence, command, caution}`.
+`applicable: true` when a recognizable project manifest exists (evidence = the marker file):
+`package.json`, `pyproject.toml`, `requirements.txt`, `Gemfile`, `go.mod`, `Cargo.toml`,
+`composer.json`, `pom.xml`, `build.gradle`, or any top-level `*.tf`. No manifest ⇒
+`applicable: false` (honest — an empty/unknown repo yields nothing). `command` is the **preview**
+form `npx autoskills --dry-run`; `caution` is the auto-trigger-degradation warning from §3.
+
+### 4.2 Gated `--dry-run` runner (onboarding prose)
+In DIAGNOSE, when applicable: surface the recommendation + caution. **Behind a human confirm**
+(external code!), run `npx autoskills --dry-run` **through the process-group timeout supervisor
+with `stdin </dev/null`** (`compound-v-run-with-timeout.py` — the v2.5.0 launch invariant applies
+to `npx` too), and surface the previewed skill list. If the user declines the confirm, just print
+the recommendation ("run `npx autoskills` yourself when ready"). **Never** run the install form.
+
+### 4.3 Onboarding wiring
+`skills/compound-v/onboarding.md` (DIAGNOSE, next to the MCP recommender) + `commands/v-onboard.md`
+(the finish report). The Skills-stance §11 gains a note that autoskills is the recommended path for
+third-party stack skills, present-only + cautioned.
+
+## 5. Invariants (non-negotiable)
+1. **Never auto-install.** Onboarding runs at most `--dry-run` (a preview), only behind a human
+   confirm; the real install is the user's own action (autoskills has its own confirm + SHA-256).
+2. **External `npx` is untrusted** — any invocation runs under the timeout supervisor with
+   `stdin </dev/null` (the v2.5.0 launch invariant), never bare.
+3. **Auto-trigger caution always surfaced** (§3) — recommending mass skill-install without the
+   degradation warning would contradict §11.
+4. **Deterministic + evidence-cited** — the detector cites the marker file; an unknown repo yields
+   `applicable: false` (no invented recommendation).
+5. **Present-only in DIAGNOSE** (advisory / non-writing) — consistent with the doctor step.
+
+## 6. Verification
+- **`compound-v-onboard.py --selftest`** (the `recommend_autoskills` cases): a repo with
+  `package.json` → applicable + evidence `package.json`; a repo with `pyproject.toml` → applicable;
+  an empty repo → `applicable: false`, no command.
+- **Dogfood on superpowers-v itself:** it has **no** standard manifest → `applicable: false` (the
+  negative path — no false recommendation, just like the MCP recommender emitted no false MCPs).
+- **Codex cross-model verification** of the detector + the gated-runner invariants (supervisor +
+  `</dev/null`, never auto-install).
+- Full regression (existing selftests + lint + CI version-lockstep) stays green.
+
+## 7. Out of scope (2.5.3)
+- Auto-installing skills or running `npx autoskills` without `--dry-run` / without a confirm.
+- Parsing/curating autoskills' registry ourselves (we defer to its audited registry + SHA-256).
+- Path-scoped `.claude/rules/*.md` writer (still a future item).
+
+## 8. Version
+**v2.5.3** (patch — an onboarding fast-follow; `plugin.json` + `marketplace.json` in lockstep).