skillwiki 0.2.0-beta.24 → 0.2.0-beta.26

package/dist/cli.js

@@ -1009,6 +1009,20 @@ async function runInstall(input) {
     installed.push(dst);
     if (r.data.backupPath) backed_up.push(r.data.backupPath);
   }
+  const binSrc = join4(input.skillsRoot, "bin", "skillwiki");
+  try {
+    await stat4(binSrc);
+    const binDst = join4(input.target, "bin", "skillwiki");
+    if (!input.dryRun) {
+      const r = await atomicCopyWithBackup(binSrc, binDst);
+      if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
+      installed.push(binDst);
+      if (r.data.backupPath) backed_up.push(r.data.backupPath);
+    } else {
+      installed.push(binDst);
+    }
+  } catch {
+  }
   const manifest_path = join4(input.target, "wiki-manifest.json");
   if (!input.dryRun) await writeManifest(manifest_path, { installed, backed_up });
   const hintLines = [
@@ -1631,7 +1645,7 @@ function hasDuplicateFrontmatter(body) {
   return false;
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter"];
+var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "missing_overview"];
 var INFO_ORDER = ["bridges", "low_confidence_single_source", "page_structure", "topic_map_recommended"];
 async function runLint(input) {
   const buckets = {};
@@ -1681,6 +1695,7 @@ async function runLint(input) {
     const orphanedPages = [];
     const structFlags = [];
     const dupFrontmatter = [];
+    const noOverview = [];
     for (const page of scan.data.typedKnowledge) {
       const text = await readPage(page);
       const split = splitFrontmatter(text);
@@ -1690,13 +1705,13 @@ async function runLint(input) {
       if (isLegacyCitationStyle(body)) legacyPages.push(page.relPath);
       if (hasOrphanedCitations(body)) orphanedPages.push(page.relPath);
       const bodyLines = body.split("\n").filter((l) => l.trim().length > 0).length;
+      const hasOverview = /^## Overview/m.test(body);
+      if (!hasOverview) noOverview.push(page.relPath);
       if (bodyLines < STRUCT_MIN_BODY_LINES) {
-        const hasOverview = /^## Overview/m.test(body);
         const hasRelated = /^## (Related|Relationships)/m.test(body);
         const sectionCount = (body.match(/^## /gm) ?? []).length;
-        if (!hasOverview || !hasRelated || sectionCount < STRUCT_MIN_SECTIONS) {
+        if (!hasRelated || sectionCount < STRUCT_MIN_SECTIONS) {
           const reasons = [];
-          if (!hasOverview) reasons.push("no Overview");
           if (!hasRelated) reasons.push("no Related or Relationships");
           if (sectionCount < STRUCT_MIN_SECTIONS) reasons.push(`only ${sectionCount} sections`);
           structFlags.push(`${page.relPath}: ${bodyLines} lines, ${reasons.join(", ")}`);
@@ -1707,6 +1722,7 @@ async function runLint(input) {
     if (orphanedPages.length > 0) buckets.orphaned_citations = orphanedPages;
     if (structFlags.length > 0) buckets.page_structure = structFlags;
     if (dupFrontmatter.length > 0) buckets.duplicate_frontmatter = dupFrontmatter;
+    if (noOverview.length > 0) buckets.missing_overview = noOverview;
   }
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
@@ -2321,6 +2337,71 @@ ${migratedBody}${newFooter}`;
   };
 }
 
+// src/commands/frontmatter-fix.ts
+import { writeFile as writeFile8 } from "fs/promises";
+function isoToday() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function fixFrontmatter(rawFm) {
+  const additions = [];
+  if (!/^created:/m.test(rawFm)) additions.push(`created: ${isoToday()}`);
+  if (!/^updated:/m.test(rawFm)) additions.push(`updated: ${isoToday()}`);
+  if (!/^tags:/m.test(rawFm)) additions.push("tags: []");
+  if (!/^sources:/m.test(rawFm)) additions.push("sources: []");
+  if (!/^provenance:/m.test(rawFm)) additions.push("provenance: research");
+  if (additions.length === 0) return rawFm;
+  return rawFm.trimEnd() + "\n" + additions.join("\n") + "\n";
+}
+function removeOrphanTagsLines(body) {
+  return body.split("\n").filter((line) => !/^tags:\s*\[/.test(line.trim())).join("\n");
+}
+async function runFrontmatterFix(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const fixed = [];
+  const skipped = [];
+  let unchanged = 0;
+  for (const page of scan.data.typedKnowledge) {
+    const text = await readPage(page);
+    const split = splitFrontmatter(text);
+    if (!split.ok) {
+      skipped.push(page.relPath);
+      continue;
+    }
+    const { rawFrontmatter, body } = split.data;
+    const newFm = fixFrontmatter(rawFrontmatter);
+    const newBody = removeOrphanTagsLines(body);
+    const newText = `---
+${newFm}
+---
+${newBody}`;
+    if (newText === text) {
+      unchanged++;
+      continue;
+    }
+    if (!input.dryRun) {
+      await writeFile8(page.absPath, newText, "utf8");
+    }
+    fixed.push(page.relPath);
+  }
+  const exitCode = fixed.length > 0 ? ExitCode.MIGRATION_APPLIED : ExitCode.OK;
+  const hintLines = [`scanned: ${fixed.length + skipped.length + unchanged}`];
+  if (fixed.length > 0) hintLines.push(`fixed: ${fixed.length}`);
+  if (skipped.length > 0) hintLines.push(`skipped (parse error): ${skipped.length}`);
+  if (unchanged > 0) hintLines.push(`unchanged: ${unchanged}`);
+  if (input.dryRun && fixed.length > 0) hintLines.push("(dry run \u2014 no files written)");
+  return {
+    exitCode,
+    result: ok({
+      scanned: fixed.length + skipped.length + unchanged,
+      fixed,
+      skipped,
+      unchanged,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+
 // src/commands/update.ts
 import { execSync as execSync2 } from "child_process";
 import { readFileSync as readFileSync3 } from "fs";
@@ -2532,6 +2613,11 @@ program.command("migrate-citations [vault]").description("migrate ^[raw/...] mar
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }));
 });
+program.command("frontmatter-fix [vault]").description("fix common frontmatter issues on typed-knowledge pages").option("--dry-run", "preview changes without writing", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runFrontmatterFix({ vault: v.vault, dryRun: !!opts.dryRun }));
+});
 program.command("update").description("update skillwiki CLI to the latest version").option("--tag <tag>", "npm dist-tag", "beta").action(async (opts) => emit(await runUpdate({
   home: process.env.HOME ?? "",
   distTag: opts.tag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.24",
+  "version": "0.2.0-beta.26",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.24",
+  "version": "0.2.0-beta.26",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
   "author": {

package/skills/bin/skillwiki

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# skillwiki CLI wrapper — delegates to npx so the CLI is available
+# automatically when this plugin is enabled (Claude Code adds bin/ to PATH).
+set -euo pipefail
+exec npx -y skillwiki@beta "$@"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.0-beta.24",
+  "version": "0.2.0-beta.26",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-decide/SKILL.md

@@ -13,7 +13,7 @@ Standard four + project context.
 
 ## Steps
 1. Compose the ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`. Frontmatter: kind=decision, status=in-progress or completed, project link.
-2. `npx skillwiki validate <adr>`. If non-zero, STOP.
+2. `skillwiki validate <adr>`. If non-zero, STOP.
 3. **Generalization check.** If the decision applies beyond this project, create a `concepts/` page with `provenance: project` (or `mixed` if research-informed).
 4. Apply writes: ADR → (optional) concept page → vault `index.md` → vault `log.md` and project `log.md`.
 

package/skills/proj-distill/SKILL.md

@@ -31,7 +31,7 @@ When reading retros as source material:
 2. **Step 2 — Generate.** Compose the vault concept page with
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
-   `npx skillwiki validate`.
+   `skillwiki validate`.
 3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source
    compound entry. For retro-sourced distillation, skip backlink (log.md
    entries are append-only) and instead add `sources:` citing the vault

package/skills/proj-work/SKILL.md

@@ -16,7 +16,7 @@ Standard four + project context (project README, last ~5 work logs).
 1. Determine `kind:` (feature | issue | refactor | decision) and slug.
 2. Create folder `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
 3. Override default output paths for any nested skill: `spec.md`, `plan.md`, and `log.md` are written here, not at vault root.
-4. Validate work-item frontmatter via `npx skillwiki validate <spec.md>`. If non-zero, STOP.
+4. Validate work-item frontmatter via `skillwiki validate <spec.md>`. If non-zero, STOP.
 5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
 6. Append vault `log.md` entry on creation and on each status transition.
 

package/skills/using-skillwiki/SKILL.md

@@ -100,3 +100,23 @@ skillwiki supports named wiki profiles for working with multiple vaults. Set `WI
 - `skillwiki --wiki <name> lint` — override per-command
 
 **Project-local override:** Place a `./skillwiki/.env` in a project root to bind that project to a specific wiki. Skills will use it automatically when running from that directory.
+
+## PRD Bridge — Redirect Spec/Plan Output to Vault
+
+When skillwiki is installed, **all spec and plan documents must land in the vault**, not in repo-local directories like `docs/superpowers/`. This applies to any PRD/design skill (superpowers:brainstorming, superpowers:writing-plans, CodeStable, AIDE, Hermes, etc.).
+
+**Rule:** Before a PRD skill writes a spec or plan file, redirect its save path:
+1. Resolve the vault path: `skillwiki path`
+2. If the cwd is inside a project (check for `projects/{slug}/` via `skillwiki path --init-time` or look for `./skillwiki/.env`), use that project's work directory
+3. Create or locate the work item via `proj-work`, which emits redirect paths for `spec.md` and `plan.md`
+4. Pass those vault paths to the PRD skill as its save location
+
+**Concrete overrides for superpowers:**
+- `superpowers:brainstorming` step 6: override `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` → vault work-item `spec.md` path from `proj-work`
+- `superpowers:writing-plans` header: override `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` → vault work-item `plan.md` path from `proj-work`
+
+Both skills say "User preferences for spec location override this default" — the vault work-item path IS the override.
+
+**If no project context exists** (standalone vault, not inside a project), save specs/plans directly under the vault root with the PRD skill's default naming, e.g. `<vault>/specs/YYYY-MM-DD-<slug>.md`.
+
+**Never create `docs/superpowers/` in any repo.**

package/skills/wiki-audit/SKILL.md

@@ -19,7 +19,7 @@ Standard four reads.
 
 ## Steps
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
-1. `npx skillwiki audit <page>`. Read the JSON report.
+1. `skillwiki audit <page>`. Read the JSON report.
 2. Reason over the report:
    - For each unresolved marker: suggest ingesting the missing source or correcting the path.
    - For each `unused_sources` entry: suggest adding a body marker or removing from `sources:`.

package/skills/wiki-crystallize/SKILL.md

@@ -22,7 +22,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 1. Identify type: entity / concept / comparison / query / summary.
 2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible.
-4. `npx skillwiki validate <page>`. If non-zero, STOP.
+4. `skillwiki validate <page>`. If non-zero, STOP.
 5. Apply writes: page → `index.md` → `log.md`.
 
 ## Stop conditions

package/skills/wiki-ingest/SKILL.md

@@ -23,11 +23,11 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 
 ## Steps (in order — N6, N7, N8)
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
-1. **Guard.** For each URL: run `npx skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
+1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
-3. **Hash.** Write the raw file (frontmatter + body). Run `npx skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
+3. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
 4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers).
-5. **Validate.** For each generated page: run `npx skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
+5. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
 6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
 7. **Confidence flag.** If only one source is cited, set `confidence: low`.
 

package/skills/wiki-query/SKILL.md

@@ -20,8 +20,8 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 ## Steps
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
-2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `npx skillwiki graph build <vault>`.
-3. **Compute overlap.** `npx skillwiki overlap <vault>`.
+2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.
+3. **Compute overlap.** `skillwiki overlap <vault>`.
 4. **Score candidates** in prompt using the 4 signals:
    - Direct wikilink: 3.0×
    - Source overlap: 4.0× (read from overlap output)