@papi-ai/skills 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @papi-ai/skills
+
+The canonical, versioned bundle of PAPI's shareable Claude Code skills. Projects
+**install** this package instead of copying skill files, so they pick up fixes by
+bumping a pinned version rather than silently drifting from forked copies.
+
+## What's in the bundle
+
+Nine ship-ready skills (the PAPI-internal skills — `bootstrap-project`,
+`friction-promote`, `patch-notes`, `support-debug` — are intentionally **not** shipped):
+
+**Generic engineering (eager):** `check-mcp`, `pr-reviewer`,
+`deployment-completeness-audit`, `playwright-skill`
+
+**Cycle methodology (lazy / trigger-loaded):** `papi-plan`, `papi-build`,
+`papi-idea`, `papi-strategy`, `papi-advanced`
+
+The authoritative inventory + checksums live in [`manifest.json`](./manifest.json),
+regenerated from the skill content on `prepack`.
+
+## Install into a project
+
+```bash
+npx @papi-ai/skills install /path/to/project        # symlink (copy fallback)
+npx @papi-ai/skills install /path/to/project --copy  # force copy, no symlinks
+npx @papi-ai/skills install /path/to/project --force # overwrite a diverged skill
+```
+
+Each packaged skill is symlinked into `<project>/.claude/skills/<name>`. Where
+symlinks are unsupported (some Windows / restricted filesystems) it copies instead.
+
+## Pinned versioning
+
+Published as `@papi-ai/skills@0.1.0`. A project pinned to `0.1.0` keeps that exact
+content when `0.2.0` ships — upgrades are explicit (`npm i @papi-ai/skills@latest`
+then re-run the installer), never silent.
+
+## Local overrides
+
+A skill placed in `<project>/.claude/skills.local/<name>` is an intentional
+override: the installer never touches it and PAPI's stale-fork detection never
+flags it. Use this to customise a skill without fighting the package.
+
+## Stale-fork detection
+
+`orient` (with `deep_housekeeping: true`) compares the project's `.claude/skills/`
+against this manifest and surfaces any skill whose content has diverged from the
+pinned registry, offering replacement. It prompts — it never auto-overwrites.
+
+```js
+import { detectStaleForks } from '@papi-ai/skills/manifest';
+const forks = detectStaleForks('/path/to/project'); // [{ name, packagedChecksum, localChecksum }]
+```

package/bin/install.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// @papi-ai/skills installer.
+//
+// Installs the pinned skill bundle into a project's .claude/skills/ by
+// symlinking each packaged skill (with a copy fallback where symlinks are
+// unsupported, e.g. some Windows / restricted filesystems).
+//
+// Precedence: a skill present in <project>/.claude/skills.local/ is an
+// intentional override and is never touched. An already-installed skill whose
+// content has diverged is NOT clobbered unless --force is passed.
+//
+// Usage:
+//   papi-skills install <project-dir> [--copy] [--force] [--quiet]
+//   node bin/install.mjs <project-dir> [--copy] [--force] [--quiet]
+
+import {
+  existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync, realpathSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadManifest, listPackagedSkills, checksumSkillDir, PACKAGE_ROOT } from '../lib/manifest.mjs';
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args[0] === 'install') args.shift(); // tolerate the verb form
+  const flags = new Set(args.filter((a) => a.startsWith('--')));
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const projectDir = resolve(positional[0] ?? process.cwd());
+  const forceCopy = flags.has('--copy');
+  const force = flags.has('--force');
+  const quiet = flags.has('--quiet');
+
+  const manifest = loadManifest();
+  const skillsDir = join(projectDir, '.claude', 'skills');
+  const overrideDir = join(projectDir, '.claude', 'skills.local');
+  mkdirSync(skillsDir, { recursive: true });
+
+  const log = quiet ? () => {} : (m) => console.log(m);
+  const summary = { linked: 0, copied: 0, upToDate: 0, overridden: 0, diverged: 0 };
+
+  for (const name of listPackagedSkills()) {
+    const src = join(PACKAGE_ROOT, 'skills', name);
+    const dest = join(skillsDir, name);
+
+    if (existsSync(join(overrideDir, name))) {
+      summary.overridden++;
+      log(`  ↪ ${name} — skipped (local override in .claude/skills.local/)`);
+      continue;
+    }
+
+    if (existsSync(dest)) {
+      const st = lstatSync(dest);
+      if (st.isSymbolicLink()) {
+        // Already a managed symlink — refresh if it points elsewhere.
+        try {
+          if (realpathSync(dest) === realpathSync(src)) { summary.upToDate++; log(`  = ${name} — up to date (linked)`); continue; }
+        } catch { /* dangling link — fall through to re-link */ }
+      } else if (st.isDirectory()) {
+        const matches = checksumSkillDir(dest) === skillEntry(manifest, name)?.checksum;
+        if (matches) { summary.upToDate++; log(`  = ${name} — up to date`); continue; }
+        if (!force) {
+          summary.diverged++;
+          log(`  ! ${name} — diverged from registry; not overwritten. Move to .claude/skills.local/ to keep, or re-run with --force.`);
+          continue;
+        }
+      }
+      rmSync(dest, { recursive: true, force: true });
+    }
+
+    if (forceCopy) {
+      cpSync(src, dest, { recursive: true });
+      summary.copied++;
+      log(`  + ${name} — copied`);
+      continue;
+    }
+
+    try {
+      symlinkSync(src, dest, 'dir');
+      summary.linked++;
+      log(`  → ${name} — linked`);
+    } catch {
+      // Symlinks unsupported on this platform/filesystem — copy instead.
+      cpSync(src, dest, { recursive: true });
+      summary.copied++;
+      log(`  + ${name} — copied (symlink unsupported)`);
+    }
+  }
+
+  log(
+    `\n@papi-ai/skills@${manifest.packageVersion} → ${skillsDir}\n` +
+    `  linked ${summary.linked} · copied ${summary.copied} · up-to-date ${summary.upToDate} · ` +
+    `overridden ${summary.overridden} · diverged ${summary.diverged}`,
+  );
+  if (summary.diverged > 0 && !force) process.exitCode = 0; // informational, not a failure
+}
+
+function skillEntry(manifest, name) {
+  return manifest.skills.find((s) => s.name === name);
+}
+
+// Run only when invoked directly, not when imported.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv);
+}

package/lib/manifest.d.ts

@@ -0,0 +1,33 @@
+// Hand-written types for the ESM helpers in manifest.mjs.
+// Lets TypeScript consumers (the MCP server's orient path) import with types.
+
+export const PACKAGE_ROOT: string;
+export const MANIFEST_SCHEMA_VERSION: number;
+
+export interface SkillManifestEntry {
+  /** Skill directory name, e.g. "pr-reviewer". */
+  name: string;
+  /** Where the skill is loaded from in a project. */
+  kind: 'eager' | 'lazy';
+  /** Short, stable content checksum of the packaged skill directory. */
+  checksum: string;
+}
+
+export interface SkillsManifest {
+  schemaVersion: number;
+  /** Pinned package version, e.g. "0.1.0". */
+  packageVersion: string;
+  generatedAt: string;
+  skills: SkillManifestEntry[];
+}
+
+export interface StaleFork {
+  name: string;
+  packagedChecksum: string;
+  localChecksum: string;
+}
+
+export function checksumSkillDir(skillDir: string): string;
+export function loadManifest(packageRoot?: string): SkillsManifest;
+export function listPackagedSkills(packageRoot?: string): string[];
+export function detectStaleForks(projectDir: string, packageRoot?: string): StaleFork[];

package/lib/manifest.mjs

@@ -0,0 +1,102 @@
+// @papi-ai/skills — shared manifest helpers.
+//
+// Single source of truth for: the manifest schema, version comparison, and
+// stale-fork detection. Both consumers import from here so the schema is
+// defined exactly once (bin/install.mjs and the server's orient path).
+
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** Package root = parent of this lib/ directory. */
+export const PACKAGE_ROOT = dirname(HERE);
+
+export const MANIFEST_SCHEMA_VERSION = 1;
+
+/**
+ * Compute a stable content checksum for a single skill directory.
+ * Hashes every file's relative path + bytes in sorted order so the result is
+ * deterministic across machines and independent of filesystem ordering.
+ */
+export function checksumSkillDir(skillDir) {
+  const hash = createHash('sha256');
+  const files = [];
+  walk(skillDir, skillDir, files);
+  files.sort();
+  for (const rel of files) {
+    hash.update(rel);
+    hash.update('\0');
+    hash.update(readFileSync(join(skillDir, rel)));
+    hash.update('\0');
+  }
+  return hash.digest('hex').slice(0, 16);
+}
+
+function walk(root, dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    // Never let machine-local cruft influence the checksum.
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    if (entry.name.startsWith('.temp-execution-')) continue;
+    if (entry.name === 'package-lock.json') continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, out);
+    } else if (entry.isFile()) {
+      out.push(abs.slice(root.length + 1));
+    }
+  }
+}
+
+/** Load and parse the package manifest. Throws if missing/malformed. */
+export function loadManifest(packageRoot = PACKAGE_ROOT) {
+  const raw = readFileSync(join(packageRoot, 'manifest.json'), 'utf8');
+  const manifest = JSON.parse(raw);
+  if (manifest.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    throw new Error(
+      `@papi-ai/skills manifest schemaVersion ${manifest.schemaVersion} != expected ${MANIFEST_SCHEMA_VERSION}`,
+    );
+  }
+  return manifest;
+}
+
+/** List the skill names that ship in the package. */
+export function listPackagedSkills(packageRoot = PACKAGE_ROOT) {
+  return loadManifest(packageRoot).skills.map((s) => s.name);
+}
+
+/**
+ * Detect skill forks in a project that have drifted from the packaged registry.
+ *
+ * For each packaged skill, if the project has a same-named skill under
+ * .claude/skills/ whose content checksum differs from the manifest, it is
+ * reported as a stale fork. Skills under .claude/skills.local/ are intentional
+ * overrides and are never reported.
+ *
+ * Fail-soft: returns [] on any filesystem error so callers (e.g. orient) never
+ * break on a missing or partial project layout.
+ *
+ * @returns {Array<{ name: string, packagedChecksum: string, localChecksum: string }>}
+ */
+export function detectStaleForks(projectDir, packageRoot = PACKAGE_ROOT) {
+  try {
+    const manifest = loadManifest(packageRoot);
+    const skillsDir = join(projectDir, '.claude', 'skills');
+    const localOverrideDir = join(projectDir, '.claude', 'skills.local');
+    const stale = [];
+    for (const skill of manifest.skills) {
+      const localPath = join(skillsDir, skill.name);
+      if (!existsSync(localPath) || !statSync(localPath).isDirectory()) continue;
+      // Intentional override — never flag.
+      if (existsSync(join(localOverrideDir, skill.name))) continue;
+      const localChecksum = checksumSkillDir(localPath);
+      if (localChecksum !== skill.checksum) {
+        stale.push({ name: skill.name, packagedChecksum: skill.checksum, localChecksum });
+      }
+    }
+    return stale;
+  } catch {
+    return [];
+  }
+}

package/manifest.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": 1,
+  "packageVersion": "0.1.0",
+  "generatedAt": "2026-05-25T12:07:27.744Z",
+  "skills": [
+    {
+      "name": "check-mcp",
+      "kind": "eager",
+      "checksum": "e5fe53aca9b35e1e"
+    },
+    {
+      "name": "deployment-completeness-audit",
+      "kind": "eager",
+      "checksum": "3740d59f520cbe24"
+    },
+    {
+      "name": "papi-advanced",
+      "kind": "lazy",
+      "checksum": "81cc81ee3f702979"
+    },
+    {
+      "name": "papi-build",
+      "kind": "lazy",
+      "checksum": "bb0b7107ab8c6b08"
+    },
+    {
+      "name": "papi-idea",
+      "kind": "lazy",
+      "checksum": "ae5da6393e14fcd5"
+    },
+    {
+      "name": "papi-plan",
+      "kind": "lazy",
+      "checksum": "6b9a42f263fa409e"
+    },
+    {
+      "name": "papi-strategy",
+      "kind": "lazy",
+      "checksum": "5b2c55da2b0f4545"
+    },
+    {
+      "name": "playwright-skill",
+      "kind": "eager",
+      "checksum": "1e8dcd223b968a85"
+    },
+    {
+      "name": "pr-reviewer",
+      "kind": "eager",
+      "checksum": "836d46ee9fc4b994"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@papi-ai/skills",
+  "version": "0.1.0",
+  "description": "PAPI's shareable Claude Code skill bundle — single source of truth, installed (not copied) into projects with pinned versioning",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    "./manifest": {
+      "types": "./lib/manifest.d.ts",
+      "default": "./lib/manifest.mjs"
+    },
+    "./manifest.json": "./manifest.json"
+  },
+  "bin": {
+    "papi-skills": "./bin/install.mjs"
+  },
+  "files": [
+    "skills",
+    "lib/manifest.mjs",
+    "lib/manifest.d.ts",
+    "bin/install.mjs",
+    "manifest.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build:manifest": "node scripts/build-manifest.mjs",
+    "prepack": "node scripts/build-manifest.mjs",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "papi",
+    "claude-code",
+    "skills",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cathalos92/papi-ui.git",
+    "directory": "packages/skills"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/skills/check-mcp/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: check-mcp
+description: Verify the PAPI MCP server is running and healthy. Use when the user says "check mcp", "is papi running", "mcp status", or at the start of any session that needs PAPI tools. Also use proactively if PAPI MCP tools are expected but not appearing in the available tools list.
+---
+
+# Check MCP Server Health
+
+Run these steps in order and report the result clearly.
+
+## Step 1: Read config
+Read `.mcp.json` from the project root. Extract the server command, args, and env vars.
+
+If `.mcp.json` doesn't exist, stop and report: "No MCP server configured. Create .mcp.json to connect PAPI."
+
+## Step 2: Check build artifact
+Verify the file referenced in `args` exists on disk (e.g., `ls <path>`).
+
+If missing, report: "Server build artifact not found at <path>. Rebuild with: `npm run build --workspace=packages/adapter-md && npm run build --workspace=packages/server`"
+
+## Step 3: Test-spawn the server
+Run the server briefly with the configured env vars to check for startup crashes:
+
+```bash
+cd <parent-dir-of-server> && <ENV_VARS> node <path-to-index.js> 2>&1 &; sleep 2; kill %1 2>/dev/null; wait 2>/dev/null
+```
+
+- If it produces an error (like "Project root required"), report the exact error and suggest the fix.
+- If no output (clean start), the server binary is healthy.
+
+## Step 4: Check Claude Code connection
+Look at the available tools list. If PAPI MCP tools (like `mcp__papi__*`) are present, the server is connected. If not, tell the user:
+
+"PAPI MCP server binary is healthy but not connected to Claude Code. Reload the VS Code window (Cmd+Shift+P -> Developer: Reload Window) to reconnect."
+
+## Step 5: Report
+Summarize with one of:
+- **Healthy**: Server configured, binary starts clean, tools available
+- **Healthy but disconnected**: Binary works, but Claude Code needs a window reload
+- **Misconfigured**: Explain what's wrong (wrong env var name, missing artifact, crash on start)
+- **Not configured**: No .mcp.json found