@tekmidian/pai 0.6.1 → 0.6.2

package/ARCHITECTURE.md

@@ -103,14 +103,15 @@ The interactive wizard walks through 14 steps:
 4. CLAUDE.md template installation
 5. PAI skill installation
 6. Steering rules installation
-7. Hook system deployment
-8. TypeScript hook compilation
-9. Claude Code settings configuration
-10. Daemon installation
-11. MCP server registration
-12. Directory creation
-13. Initial indexing
-14. Verification
+7. MCP skill stub symlinks
+8. Hook system deployment
+9. TypeScript hook compilation
+10. Claude Code settings configuration
+11. Daemon installation
+12. MCP server registration
+13. Directory creation
+14. Initial indexing
+15. Verification
 
 ### 4. Install the Daemon
 
@@ -642,6 +643,68 @@ The build script compiles each `.ts` hook to a self-contained `.mjs` module usin
 
 ---
 
+## Skill Stub System
+
+PAI's 18 MCP prompts are exposed to Claude Code as discoverable skills via auto-generated SKILL.md files. This bridges the gap between MCP prompts (protocol-level, invoked via `prompts/get`) and Claude Code's skill scanner (filesystem-based, scans `~/.claude/skills/`).
+
+### How It Works
+
+```
+Source (TypeScript)              Build                    Claude Code
+─────────────────               ─────                    ──────────
+src/daemon-mcp/prompts/*.ts  → dist/skills/<Name>/    → ~/.claude/skills/<Name>/
+src/daemon-mcp/prompts/        SKILL.md                  (symlink)
+  custom/*.ts (gitignored)
+```
+
+1. **Source of truth**: TypeScript files in `src/daemon-mcp/prompts/`. Each exports `{ description, content }`.
+2. **Build**: `node scripts/build-skill-stubs.mjs --sync` extracts content and generates `dist/skills/<TitleCase>/SKILL.md` with YAML frontmatter.
+3. **Sync**: The `--sync` flag creates/updates symlinks in `~/.claude/skills/`. Runs automatically on every `bun run build`.
+4. **Discovery**: Claude Code scans `~/.claude/skills/<Name>/SKILL.md` at session start, loads descriptions, and auto-invokes matching skills.
+
+**Important**: Skills MUST be at `~/.claude/skills/<Name>/SKILL.md` (one level deep). Subdirectories like `~/.claude/skills/user/<Name>/` are NOT discovered by Claude Code's scanner.
+
+### Adding a New Skill
+
+**Built-in (shipped with PAI):**
+
+1. Create `src/daemon-mcp/prompts/my-skill.ts`:
+   ```typescript
+   export const mySkill = {
+     description: "What the skill does",
+     content: `## My Skill
+
+   USE WHEN user says 'trigger phrase', 'another trigger', ...
+
+   ### Instructions
+   ...your skill content here...`,
+   };
+   ```
+2. Add export to `src/daemon-mcp/prompts/index.ts`:
+   ```typescript
+   export { mySkill } from "./my-skill.js";
+   ```
+3. Run `bun run build` — generates the stub AND syncs the symlink.
+
+**Custom (user-created, survives `git pull`):**
+
+1. Create `src/daemon-mcp/prompts/custom/my-local-skill.ts` (same format as above).
+2. Run `bun run build` — custom prompts are picked up automatically.
+
+The `custom/` directory is gitignored (only `.gitkeep` is tracked), so your local skills survive PAI updates.
+
+### Updating After Changes
+
+Symlinks point to `dist/skills/`, so any `bun run build` automatically updates what Claude Code sees. No manual steps needed.
+
+If you reorganize prompts (rename, delete, add), the build script regenerates all stubs and the `--sync` flag updates symlinks accordingly. Stale symlinks pointing to removed stubs are cleaned up automatically.
+
+### Setup Integration
+
+`pai setup` (Step 7) runs the same symlink logic interactively, asking before creating symlinks. It also cleans up legacy symlinks from the old `~/.claude/skills/user/` location.
+
+---
+
 ## Templates
 
 PAI ships three templates used during setup and customizable for your workflow.
@@ -854,6 +917,7 @@ bun run lint     # tsc --noEmit
 | `dist/daemon/index.mjs` | Daemon server |
 | `dist/daemon-mcp/index.mjs` | MCP shim (stdio → daemon socket) |
 | `dist/hooks/*.mjs` | Compiled lifecycle hooks |
+| `dist/skills/<Name>/SKILL.md` | Generated skill stubs (symlinked to ~/.claude/skills/) |
 
 ### Source Structure
 
@@ -885,6 +949,7 @@ src/
 ├── daemon-mcp/
 │   ├── instructions.ts     # MCP server instructions (~1.5KB routing table)
 │   ├── prompts/            # 18 on-demand skill prompts
+│   │   └── custom/         # User-created prompts (gitignored)
 │   ├── resources/          # 11 reference resources (pai:// URIs)
 │   └── index.ts            # MCP shim entry point (stdio → socket)
 ├── hooks/

package/dist/cli/index.mjs

@@ -15,7 +15,7 @@ import { t as PaiClient } from "../ipc-client-CoyUHPod.mjs";
 import { a as expandHome, i as ensureConfigDir, n as CONFIG_FILE$2, o as loadConfig, t as CONFIG_DIR } from "../config-BuhHWyOK.mjs";
 import { t as createStorageBackend } from "../factory-Ygqe_bVZ.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir, platform, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
@@ -4310,6 +4310,18 @@ function getDistHooksDir() {
 	for (const candidate of candidates) if (existsSync(join(candidate, "stop-hook.mjs"))) return candidate;
 	return fromModule;
 }
+function getDistDir() {
+	const moduleDir = new URL(".", import.meta.url).pathname;
+	const fromModule = join(moduleDir, "..", "..", "..");
+	const candidates = [
+		fromModule,
+		join(process.cwd(), "dist"),
+		join(homedir(), "dev", "ai", "PAI", "dist"),
+		join("/", "usr", "local", "lib", "node_modules", "@tekmidian", "pai", "dist")
+	];
+	for (const candidate of candidates) if (existsSync(join(candidate, "skills"))) return candidate;
+	return fromModule;
+}
 function getStatuslineScript() {
 	const candidates = [
 		join(process.cwd(), "statusline-command.sh"),
@@ -4685,6 +4697,89 @@ async function stepAiSteeringRules(rl) {
 	return true;
 }
 
+//#endregion
+//#region src/cli/commands/setup/steps/07-skill-stubs.ts
+/**
+* Step 7: Install PAI MCP skill stubs to ~/.claude/skills/.
+*
+* Each PAI MCP prompt has a SKILL.md stub generated at build time
+* (dist/skills/<Name>/SKILL.md). This step symlinks (macOS/Linux) or
+* copies (Windows) them into Claude Code's skill discovery directory.
+*
+* Skills MUST live at ~/.claude/skills/<Name>/SKILL.md (top level),
+* NOT under a user/ subdirectory — Claude Code only scans one level deep.
+*
+* Symlinks keep the stubs in sync — rebuilding PAI updates them automatically.
+* Existing non-symlink directories with the same name are never overwritten.
+*/
+async function stepSkillStubs(rl) {
+	section("Step 7: MCP Skill Stubs");
+	line$1();
+	line$1("  PAI MCP prompts need SKILL.md stubs so Claude Code can discover them.");
+	line$1("  Stubs are symlinked from dist/skills/ — rebuilding PAI keeps them in sync.");
+	line$1();
+	const distSkills = join(getDistDir(), "skills");
+	if (!existsSync(distSkills)) {
+		console.log(c.warn("dist/skills/ not found — run `bun run build` first."));
+		return false;
+	}
+	const skillNames = readdirSync(distSkills).filter((name) => {
+		return existsSync(join(join(distSkills, name), "SKILL.md"));
+	});
+	if (skillNames.length === 0) {
+		console.log(c.warn("No skill stubs found in dist/skills/."));
+		return false;
+	}
+	console.log(c.dim(`  Found ${skillNames.length} skill stubs to install.`));
+	line$1();
+	if (!await promptYesNo(rl, `Symlink ${skillNames.length} PAI skill stubs to ~/.claude/skills/?`, true)) {
+		console.log(c.dim("  Skipping skill stub installation."));
+		return false;
+	}
+	const targetBase = join(homedir(), ".claude", "skills");
+	mkdirSync(targetBase, { recursive: true });
+	const oldUserBase = join(targetBase, "user");
+	if (existsSync(oldUserBase)) for (const name of skillNames) {
+		const oldTarget = join(oldUserBase, name);
+		if (existsSync(oldTarget) && lstatSync(oldTarget).isSymbolicLink()) unlinkSync(oldTarget);
+	}
+	const useSymlinks = platform() !== "win32";
+	let installed = 0;
+	let skipped = 0;
+	let updated = 0;
+	for (const name of skillNames) {
+		const source = resolve(join(distSkills, name));
+		const target = join(targetBase, name);
+		if (existsSync(target) && !lstatSync(target).isSymbolicLink()) {
+			console.log(c.dim(`  SKIP ${name} (existing user skill, not a symlink)`));
+			skipped++;
+			continue;
+		}
+		if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+			if (resolve(readlinkSync(target)) === source) {
+				installed++;
+				continue;
+			}
+			unlinkSync(target);
+			updated++;
+		}
+		if (useSymlinks) symlinkSync(source, target);
+		else {
+			mkdirSync(target, { recursive: true });
+			copyFileSync(join(source, "SKILL.md"), join(target, "SKILL.md"));
+		}
+		installed++;
+	}
+	line$1();
+	const method = useSymlinks ? "symlinked" : "copied";
+	if (updated > 0) console.log(c.ok(`${installed} stubs ${method}, ${updated} updated, ${skipped} skipped (user skills).`));
+	else {
+		console.log(c.ok(`${installed} skill stubs ${method} to ~/.claude/skills/.`));
+		if (skipped > 0) console.log(c.dim(`  ${skipped} skipped (existing user skills not managed by PAI).`));
+	}
+	return true;
+}
+
 //#endregion
 //#region src/cli/commands/setup/steps/08-hooks.ts
 /** Step 7: Shell lifecycle hooks installation (pre-compact, session-stop, statusline). */
@@ -5317,7 +5412,7 @@ async function stepInitialIndex(rl) {
 //#endregion
 //#region src/cli/commands/setup/steps/15-verify.ts
 /** Step 13: Setup summary — displays all configuration choices made during setup. */
-function stepSummary(configUpdates, claudeMdGenerated, paiSkillInstalled, aiSteeringRulesInstalled, hooksInstalled, tsHooksInstalled, settingsPatched, daName, daemonInstalled, mcpRegistered) {
+function stepSummary(configUpdates, claudeMdGenerated, paiSkillInstalled, aiSteeringRulesInstalled, skillStubsInstalled, hooksInstalled, tsHooksInstalled, settingsPatched, daName, daemonInstalled, mcpRegistered) {
 	section("Setup Complete");
 	line$1();
 	console.log(chalk.green("  PAI Knowledge OS is configured!"));
@@ -5331,6 +5426,7 @@ function stepSummary(configUpdates, claudeMdGenerated, paiSkillInstalled, aiStee
 	console.log(chalk.dim("  CLAUDE.md:        ") + chalk.cyan(claudeMdGenerated ? "~/.claude/CLAUDE.md (generated)" : "(unchanged)"));
 	console.log(chalk.dim("  PAI skill:        ") + chalk.cyan(paiSkillInstalled ? "~/.claude/skills/PAI/SKILL.md (installed)" : "(unchanged)"));
 	console.log(chalk.dim("  Steering rules:   ") + chalk.cyan(aiSteeringRulesInstalled ? "~/.claude/skills/PAI/AI-STEERING-RULES.md (installed)" : "(unchanged)"));
+	console.log(chalk.dim("  Skill stubs:      ") + chalk.cyan(skillStubsInstalled ? "18 MCP prompt stubs symlinked to ~/.claude/skills/" : "(unchanged)"));
 	console.log(chalk.dim("  Hooks (shell):    ") + chalk.cyan(hooksInstalled ? "pai-pre-compact.sh, pai-session-stop.sh (installed)" : "(unchanged)"));
 	console.log(chalk.dim("  Hooks (TS):       ") + chalk.cyan(tsHooksInstalled ? "14 .mjs hooks installed to ~/.claude/Hooks/" : "(unchanged)"));
 	console.log(chalk.dim("  Assistant name:   ") + chalk.cyan(daName));
@@ -5394,6 +5490,7 @@ async function runSetup() {
 		const claudeMdGenerated = await stepClaudeMd(rl);
 		const paiSkillInstalled = await stepPaiSkill(rl);
 		const aiSteeringRulesInstalled = await stepAiSteeringRules(rl);
+		const skillStubsInstalled = await stepSkillStubs(rl);
 		const hooksInstalled = await stepHooks(rl);
 		const tsHooksInstalled = await stepTsHooks(rl);
 		const daName = await stepDaName(rl);
@@ -5409,7 +5506,7 @@ async function runSetup() {
 		line$1();
 		console.log(chalk.green("  Configuration saved."));
 		await stepInitialIndex(rl);
-		stepSummary(allUpdates, claudeMdGenerated, paiSkillInstalled, aiSteeringRulesInstalled, hooksInstalled, tsHooksInstalled, settingsPatched, daName, daemonInstalled, mcpRegistered);
+		stepSummary(allUpdates, claudeMdGenerated, paiSkillInstalled, aiSteeringRulesInstalled, skillStubsInstalled, hooksInstalled, tsHooksInstalled, settingsPatched, daName, daemonInstalled, mcpRegistered);
 	} finally {
 		rl.close();
 	}