prizmkit 1.0.15 → 1.0.17

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.15",
-  "bundledAt": "2026-03-15T12:24:22.555Z",
-  "bundledFrom": "8b809a8"
+  "frameworkVersion": "1.0.17",
+  "bundledAt": "2026-03-15T14:53:53.793Z",
+  "bundledFrom": "527811d"
 }

package/bundled/dev-pipeline/lib/common.sh

@@ -32,9 +32,10 @@ log_success() { echo -e "${GREEN}[SUCCESS]${NC} $(date '+%Y-%m-%d %H:%M:%S') $*"
 #   PLATFORM
 #   PRIZMKIT_PLATFORM
 prizm_detect_cli_and_platform() {
+    local _raw_cli=""
+
     if [[ -n "${AI_CLI:-}" ]]; then
-        CLI_CMD="$AI_CLI"
-    # Read from .prizmkit/config.json if present
+        _raw_cli="$AI_CLI"
     elif [[ -f ".prizmkit/config.json" ]]; then
         _config_ai_cli=$(python3 -c "
 import json, sys
@@ -46,31 +47,33 @@ try:
 except: pass
 " 2>/dev/null || true)
         if [[ -n "$_config_ai_cli" ]]; then
-            CLI_CMD="$_config_ai_cli"
+            _raw_cli="$_config_ai_cli"
         elif [[ -n "${CODEBUDDY_CLI:-}" ]]; then
-            CLI_CMD="$CODEBUDDY_CLI"
+            _raw_cli="$CODEBUDDY_CLI"
         elif command -v cbc &>/dev/null; then
-            CLI_CMD="cbc"
+            _raw_cli="cbc"
         elif command -v claude &>/dev/null; then
-            CLI_CMD="claude"
+            _raw_cli="claude"
         else
             echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude)." >&2
             exit 1
         fi
     elif [[ -n "${CODEBUDDY_CLI:-}" ]]; then
-        CLI_CMD="$CODEBUDDY_CLI"
+        _raw_cli="$CODEBUDDY_CLI"
     elif command -v cbc &>/dev/null; then
-        CLI_CMD="cbc"
+        _raw_cli="cbc"
     elif command -v claude &>/dev/null; then
-        CLI_CMD="claude"
+        _raw_cli="claude"
     else
         echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude)." >&2
         exit 1
     fi
 
+    CLI_CMD="$_raw_cli"
+
     if [[ -n "${PRIZMKIT_PLATFORM:-}" ]]; then
         PLATFORM="$PRIZMKIT_PLATFORM"
-    elif [[ "$CLI_CMD" == *"claude"* ]]; then
+    elif [[ "$_raw_cli" == *"claude"* ]]; then
         PLATFORM="claude"
     else
         PLATFORM="codebuddy"

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.15",
+  "version": "1.0.17",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -335,43 +335,24 @@
     }
   },
   "external_skills": {
-    "registries": [
-      {
-        "name": "skills.sh",
-        "url": "https://skills.sh/registry.json",
-        "description": "Community skill registry"
-      }
-    ],
     "known": [
       {
-        "name": "find-skill",
-        "description": "Intelligent file and code search skill",
-        "source": "https://skills.sh/skills/find-skill/SKILL.md",
-        "registry": "skills.sh",
+        "name": "find-skills",
+        "description": "Helps discover and install agent skills by capability",
+        "repo": "https://github.com/vercel-labs/skills",
         "tags": [
           "search",
           "utility"
         ]
       },
       {
-        "name": "uiuxpromax",
+        "name": "ui-ux-pro-max",
         "description": "UI/UX design review and suggestions",
-        "source": "https://skills.sh/skills/uiuxpromax/SKILL.md",
-        "registry": "skills.sh",
+        "repo": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill",
         "tags": [
           "design",
           "frontend"
         ]
-      },
-      {
-        "name": "thinkthought",
-        "description": "Structured reasoning and problem decomposition",
-        "source": "https://skills.sh/skills/thinkthought/SKILL.md",
-        "registry": "skills.sh",
-        "tags": [
-          "reasoning",
-          "universal"
-        ]
       }
     ]
   }

package/bundled/skills/prizmkit-init/SKILL.md

@@ -39,44 +39,32 @@ BROWNFIELD WORKFLOW (existing project):
 4. Catalog dependencies (external packages)
 5. Count source files per directory
 
-**Step 2: State Assessment**
-2a. Run dependency analysis:
-  - Count outdated dependencies (if lockfile exists)
-  - Note any known vulnerability patterns
-
-2b. Scan for technical debt indicators:
-  - Count TODO/FIXME/HACK/XXX comments
-  - Identify large files (>500 lines)
-  - Check for test directories and coverage config
-
-2c. Generate `ASSESSMENT.md` in project root with findings
-
-**Step 3: Prizm Documentation Generation**
-3a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm:
+**Step 2: Prizm Documentation Generation**
+2a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm:
   - Create `.prizm-docs/` directory structure
   - Generate `root.prizm` (L0) with project meta and module index
   - Generate L1 docs for all discovered modules
   - Create `changelog.prizm`
   - Skip L2 (lazy generation)
 
-3b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
+2b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
 
-**Step 4: PrizmKit Workspace Initialization**
-4a. Create `.prizmkit/` directory:
+**Step 3: PrizmKit Workspace Initialization**
+3a. Create `.prizmkit/` directory:
   - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
   - `.prizmkit/specs/` (empty)
 
-**Step 5: Hook & Settings Configuration (Platform-Specific)**
+**Step 4: Hook & Settings Configuration (Platform-Specific)**
 
 **If platform is CodeBuddy (or both):**
-5a-cb. Read or create `.codebuddy/settings.json`
-5b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
-5c-cb. Preserve any existing hooks
+4a-cb. Read or create `.codebuddy/settings.json`
+4b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
+4c-cb. Preserve any existing hooks
 
 **If platform is Claude Code (or both):**
-5a-cl. Read or create `.claude/settings.json`
-5b-cl. Add `permissions` and `allowedTools` entries if needed
-5c-cl. Create `.claude/rules/prizm-documentation.md` with glob-scoped rules:
+4a-cl. Read or create `.claude/settings.json`
+4b-cl. Add `permissions` and `allowedTools` entries if needed
+4c-cl. Create `.claude/rules/prizm-documentation.md` with glob-scoped rules:
   ```yaml
   ---
   description: PrizmKit documentation rules
@@ -91,7 +79,7 @@ BROWNFIELD WORKFLOW (existing project):
   2. After changes, update affected `.prizm-docs/` files
   3. Follow Prizm doc format (KEY: value, not prose)
   ```
-5d-cl. Create `.claude/rules/prizm-commit-workflow.md` with commit-scoped rules:
+4d-cl. Create `.claude/rules/prizm-commit-workflow.md` with commit-scoped rules:
   ```yaml
   ---
   description: PrizmKit commit workflow enforcement
@@ -105,33 +93,33 @@ BROWNFIELD WORKFLOW (existing project):
   4. Stage .prizm-docs/ changes
   5. Use /prizmkit-committer for the complete workflow
   ```
-5e-cl. Preserve any existing Claude settings and rules
+4e-cl. Preserve any existing Claude settings and rules
 
-**Step 6: Project Memory Update (Platform-Specific)**
+**Step 5: Project Memory Update (Platform-Specific)**
 
 **If platform is CodeBuddy (or both):**
-6a-cb. Read existing `CODEBUDDY.md` (or create if missing)
-6b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
-6c-cb. Do not duplicate if already present
+5a-cb. Read existing `CODEBUDDY.md` (or create if missing)
+5b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
+5c-cb. Do not duplicate if already present
 
 **If platform is Claude Code (or both):**
-6a-cl. Read existing `CLAUDE.md` (or create if missing)
-6b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
-6c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
-6d-cl. Do not duplicate if already present
+5a-cl. Read existing `CLAUDE.md` (or create if missing)
+5b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
+5c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
+5d-cl. Do not duplicate if already present
 
-**Step 7: Report**
-Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, assessment highlights, platform-specific configuration applied, next recommended steps.
+**Step 6: Report**
+Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, platform-specific configuration applied, next recommended steps.
 
 Include platform-specific guidance:
 - CodeBuddy: "Use `prizmkit.specify` to start your first feature"
 - Claude Code: "Use `/prizmkit-specify` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
-- Skip Steps 1-2 (no code to scan)
-- Step 3: Create minimal `.prizm-docs/` with just `root.prizm` skeleton
-- Steps 4-6: Same as brownfield
-- Step 7: Recommend starting with specify for first feature (platform-appropriate command format)
+- Skip Step 1 (no code to scan)
+- Step 2: Create minimal `.prizm-docs/` with just `root.prizm` skeleton
+- Steps 3-5: Same as brownfield
+- Step 6: Recommend starting with specify for first feature (platform-appropriate command format)
 
 ### Gradual Adoption Path
 After init, PrizmKit operates in phases:

package/bundled/templates/hooks/commit-intent-claude.json

@@ -10,6 +10,17 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" 2>/dev/null | grep -qE 'git (commit|merge|rebase)' 2>/dev/null; then DRIFT=$(sh .prizmkit/scripts/diff-prizm-docs.sh 2>/dev/null); if [ -n \"$DRIFT\" ]; then echo \"PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found after git operation:\"; echo \"$DRIFT\"; echo \"Please update affected .prizm-docs/ files using /prizmkit-prizm-docs.\"; fi; fi"
+          }
+        ]
+      }
     ]
   }
 }

package/bundled/templates/hooks/commit-intent-codebuddy.json

@@ -10,6 +10,17 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "TOOL_INPUT=\"${CLAUDE_TOOL_INPUT:-${CODEBUDDY_TOOL_INPUT:-}}\"; if echo \"$TOOL_INPUT\" | grep -qE 'git (commit|merge|rebase)' 2>/dev/null; then DRIFT=$(sh .prizmkit/scripts/diff-prizm-docs.sh 2>/dev/null); if [ -n \"$DRIFT\" ]; then echo \"PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found:\"; echo \"$DRIFT\"; echo \"Please update affected .prizm-docs/ files.\"; fi; fi"
+          }
+        ]
+      }
     ]
   }
 }

package/bundled/templates/hooks/diff-prizm-docs.sh

@@ -0,0 +1,158 @@
+#!/bin/sh
+# PrizmKit: diff-prizm-docs.sh
+# Outputs structural differences between .prizm-docs/ and source code.
+# Silent (exit 0) if no differences or if .prizm-docs doesn't exist.
+# POSIX sh only — no arrays, no bashisms.
+
+set -e
+
+ROOT_PRIZM=".prizm-docs/root.prizm"
+
+# 1. Exit silently if no root.prizm
+[ -f "$ROOT_PRIZM" ] || exit 0
+
+# 2. Detect language from LANG: field
+LANG_VAL=$(grep '^LANG:' "$ROOT_PRIZM" | head -1 | sed 's/^LANG:[[:space:]]*//' | tr '[:upper:]' '[:lower:]')
+
+case "$LANG_VAL" in
+  go)
+    FILE_PATTERN="*.go"
+    ;;
+  javascript|typescript|javascript/typescript|typescript/javascript)
+    FILE_PATTERN="*.ts *.tsx *.js *.jsx"
+    ;;
+  python)
+    FILE_PATTERN="*.py"
+    ;;
+  rust)
+    FILE_PATTERN="*.rs"
+    ;;
+  *)
+    FILE_PATTERN=""
+    ;;
+esac
+
+# Helper: count source files in a directory (maxdepth 1) by language
+count_source_files() {
+  _dir="$1"
+  [ -d "$_dir" ] || { echo 0; return; }
+  if [ -z "$FILE_PATTERN" ]; then
+    # All non-hidden files
+    find "$_dir" -maxdepth 1 -type f ! -name '.*' 2>/dev/null | wc -l | tr -d ' '
+  else
+    _count=0
+    for _pat in $FILE_PATTERN; do
+      _c=$(find "$_dir" -maxdepth 1 -type f -name "$_pat" 2>/dev/null | wc -l | tr -d ' ')
+      _count=$((_count + _c))
+    done
+    echo "$_count"
+  fi
+}
+
+# 3. Parse MODULE_INDEX from root.prizm
+# Extract lines between MODULE_INDEX: and next ALL-CAPS header or EOF
+# Each module line: "- src/auth: ..." -> source path is text before first ":" after "- "
+REGISTERED_PATHS=""
+_in_index=0
+while IFS= read -r line; do
+  case "$line" in
+    MODULE_INDEX:*)
+      _in_index=1
+      continue
+      ;;
+  esac
+  if [ "$_in_index" -eq 1 ]; then
+    # Check for next ALL-CAPS section header (word followed by colon, all uppercase letters)
+    _header=$(echo "$line" | grep '^[A-Z_][A-Z_]*:' || true)
+    if [ -n "$_header" ]; then
+      break
+    fi
+    # Extract source path from "- src/auth: ..."
+    case "$line" in
+      "- "*)
+        _path=$(echo "$line" | sed 's/^- //' | sed 's/:.*//')
+        if [ -n "$_path" ]; then
+          REGISTERED_PATHS="${REGISTERED_PATHS}${_path}
+"
+        fi
+        ;;
+    esac
+  fi
+done < "$ROOT_PRIZM"
+
+# 4. Check each registered module for drift
+echo "$REGISTERED_PATHS" | while IFS= read -r source_path; do
+  [ -z "$source_path" ] && continue
+
+  # Derive L1 prizm file path
+  l1_file=".prizm-docs/${source_path}.prizm"
+
+  if [ ! -f "$l1_file" ]; then
+    continue
+  fi
+
+  # Read declared FILES: count
+  declared=$(grep '^FILES:' "$l1_file" | head -1 | awk '{print $2}')
+  [ -z "$declared" ] && continue
+
+  # Count actual source files
+  actual=$(count_source_files "$source_path")
+
+  if [ "$actual" -gt 0 ] && [ "$declared" != "$actual" ]; then
+    echo "MODULE_DRIFT: $source_path | declared FILES: $declared | actual: $actual"
+  fi
+done
+
+# 5. Find orphan docs
+find .prizm-docs -name '*.prizm' 2>/dev/null | while IFS= read -r prizm_file; do
+  _basename=$(basename "$prizm_file")
+  case "$_basename" in
+    root.prizm|changelog.prizm|changelog-archive.prizm)
+      continue
+      ;;
+  esac
+
+  # Derive source path: remove .prizm-docs/ prefix and .prizm suffix
+  source_path=$(echo "$prizm_file" | sed 's|^\.prizm-docs/||' | sed 's|\.prizm$||')
+
+  if [ ! -d "$source_path" ]; then
+    echo "ORPHAN_DOC: $prizm_file | source dir missing"
+  fi
+done
+
+# 6. Find unregistered directories
+find . -mindepth 1 -maxdepth 3 -type d \
+  ! -path '*/.*' \
+  ! -path '*/node_modules/*' ! -path './node_modules' \
+  ! -path '*/vendor/*' ! -path './vendor' \
+  ! -path '*/dist/*' ! -path './dist' \
+  ! -path '*/build/*' ! -path './build' \
+  ! -path '*/__pycache__/*' ! -path './__pycache__' \
+  ! -path '*/target/*' ! -path './target' \
+  ! -path '*/tests/*' ! -path './tests' \
+  ! -path '*/__tests__/*' ! -path './__tests__' \
+  ! -path '*/.prizm-docs/*' ! -path './.prizm-docs' \
+  ! -path '*/.claude/*' ! -path './.claude' \
+  ! -path '*/.codebuddy/*' ! -path './.codebuddy' \
+  ! -path '*/dev-pipeline/*' ! -path './dev-pipeline' \
+  ! -path '*/coverage/*' ! -path './coverage' \
+  ! -path '*/.nyc_output/*' ! -path './.nyc_output' \
+  ! -path '*/out/*' ! -path './out' \
+  ! -path '*/tmp/*' ! -path './tmp' \
+  2>/dev/null | while IFS= read -r candidate; do
+  # Normalize: remove leading ./
+  candidate_clean=$(echo "$candidate" | sed 's|^\./||')
+
+  # Count source files
+  file_count=$(count_source_files "$candidate_clean")
+
+  if [ "$file_count" -ge 3 ]; then
+    # Check if registered in MODULE_INDEX
+    _match=$(echo "$REGISTERED_PATHS" | grep -Fx "$candidate_clean" || true)
+    if [ -z "$_match" ]; then
+      echo "UNREGISTERED: $candidate_clean | $file_count source files | not in MODULE_INDEX"
+    fi
+  fi
+done
+
+exit 0

package/bundled/templates/hooks/prizm-pre-commit.sh

@@ -6,7 +6,8 @@ PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
 # Only run in prizm projects
 [ -f "$PROJECT_ROOT/.prizm-docs/root.prizm" ] || exit 0
 
-VALIDATE_SCRIPT="$PROJECT_ROOT/dev-pipeline/scripts/validate-prizm-docs.sh"
+VALIDATE_SCRIPT="$PROJECT_ROOT/.prizmkit/scripts/validate-prizm-docs.sh"
+[ -f "$VALIDATE_SCRIPT" ] || VALIDATE_SCRIPT="$PROJECT_ROOT/dev-pipeline/scripts/validate-prizm-docs.sh"
 
 if [ -f "$VALIDATE_SCRIPT" ]; then
     sh "$VALIDATE_SCRIPT" --staged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/clean.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs-extra';
+import { loadMetadata, loadRulesMetadata } from './metadata.js';
 
 async function removePath(targetPath, dryRun) {
   if (!await fs.pathExists(targetPath)) {
@@ -13,6 +14,38 @@ async function removePath(targetPath, dryRun) {
   return { path: targetPath, removed: true };
 }
 
+/**
+ * Remove known PrizmKit files from a shared directory (skills, agents, rules, commands).
+ * Leaves user-created files untouched. Removes the parent dir if it becomes empty.
+ */
+async function removeKnownEntries(parentDir, entries, dryRun) {
+  const results = [];
+
+  for (const entry of entries) {
+    const abs = path.join(parentDir, entry);
+    if (!await fs.pathExists(abs)) continue;
+
+    if (dryRun) {
+      results.push({ path: abs, removed: false, reason: 'dry_run' });
+      continue;
+    }
+
+    await fs.remove(abs);
+    results.push({ path: abs, removed: true });
+  }
+
+  // Remove parent dir only if it now exists and is empty
+  if (!dryRun && await fs.pathExists(parentDir)) {
+    const remaining = await fs.readdir(parentDir);
+    if (remaining.length === 0) {
+      await fs.remove(parentDir);
+      results.push({ path: parentDir, removed: true, note: '(empty dir)' });
+    }
+  }
+
+  return results;
+}
+
 async function cleanGitignore(projectRoot, dryRun) {
   const gitignorePath = path.join(projectRoot, '.gitignore');
   if (!await fs.pathExists(gitignorePath)) {
@@ -48,30 +81,78 @@ export async function runClean(directory, options = {}) {
   console.log(`  预览模式: ${dryRun ? chalk.yellow('是') : chalk.green('否')}`);
   console.log('');
 
-  const targets = [
+  // Load metadata to know exactly which files PrizmKit owns
+  const [metadata, rulesMeta] = await Promise.all([
+    loadMetadata().catch(() => ({ skills: {}, external_skills: { known: [] } })),
+    loadRulesMetadata().catch(() => ({ rules: {} })),
+  ]);
+
+  const skillNames = Object.keys(metadata.skills);
+  const externalSkillNames = (metadata.external_skills?.known || []).map(s => s.name);
+  const allSkillNames = [...new Set([...skillNames, ...externalSkillNames])];
+
+  // Agent file names installed by PrizmKit
+  const agentFiles = [
+    'prizm-dev-team-coordinator.md',
+    'prizm-dev-team-dev.md',
+    'prizm-dev-team-pm.md',
+    'prizm-dev-team-reviewer.md',
+  ];
+
+  // Rule file names installed by PrizmKit (basename without category prefix)
+  const ruleFileNames = Object.keys(metadata_rules_to_filenames(rulesMeta));
+
+  const results = [];
+
+  // ── Full removes (100% PrizmKit-owned paths) ──────────────────────────────
+  const fullRemoveTargets = [
     '.prizmkit',
     '.dev-team',
     'dev-pipeline',
+    '.prizm-docs',        // AI-generated project context docs
     'CODEBUDDY.md',
     'CLAUDE.md',
-    path.join('.codebuddy', 'skills'),
-    path.join('.codebuddy', 'agents'),
     path.join('.codebuddy', 'settings.json'),
-    path.join('.claude', 'commands'),
-    path.join('.claude', 'agents'),
-    path.join('.claude', 'rules'),
     path.join('.claude', 'settings.json'),
     path.join('.claude', 'team-info.json'),
   ];
 
-  const results = [];
-  for (const rel of targets) {
+  for (const rel of fullRemoveTargets) {
     const abs = path.join(projectRoot, rel);
     results.push(await removePath(abs, dryRun));
   }
 
+  // ── Selective removes (shared dirs — only remove PrizmKit-known entries) ──
+
+  // .claude/commands/ — skills installed as .md files or subdirs
+  const claudeCommandsDir = path.join(projectRoot, '.claude', 'commands');
+  const claudeCommandEntries = allSkillNames.flatMap(name => [name, `${name}.md`]);
+  results.push(...await removeKnownEntries(claudeCommandsDir, claudeCommandEntries, dryRun));
+
+  // .codebuddy/skills/ — skills installed as subdirectories
+  const cbSkillsDir = path.join(projectRoot, '.codebuddy', 'skills');
+  results.push(...await removeKnownEntries(cbSkillsDir, allSkillNames, dryRun));
+
+  // .claude/agents/ — PrizmKit agent files
+  const claudeAgentsDir = path.join(projectRoot, '.claude', 'agents');
+  results.push(...await removeKnownEntries(claudeAgentsDir, agentFiles, dryRun));
+
+  // .codebuddy/agents/ — same agent files
+  const cbAgentsDir = path.join(projectRoot, '.codebuddy', 'agents');
+  results.push(...await removeKnownEntries(cbAgentsDir, agentFiles, dryRun));
+
+  // .claude/rules/ — PrizmKit rule .md files
+  const claudeRulesDir = path.join(projectRoot, '.claude', 'rules');
+  results.push(...await removeKnownEntries(claudeRulesDir, ruleFileNames.map(n => `${n}.md`), dryRun));
+
+  // .codebuddy/rules/ — PrizmKit rule .mdc files
+  const cbRulesDir = path.join(projectRoot, '.codebuddy', 'rules');
+  results.push(...await removeKnownEntries(cbRulesDir, ruleFileNames.map(n => `${n}.mdc`), dryRun));
+
+  // ── .gitignore cleanup ────────────────────────────────────────────────────
   const gitignoreResult = await cleanGitignore(projectRoot, dryRun);
 
+  // ── Global team (optional) ────────────────────────────────────────────────
   if (cleanGlobalTeam) {
     const homeDir = process.env.HOME || process.env.USERPROFILE;
     if (homeDir) {
@@ -80,13 +161,15 @@ export async function runClean(directory, options = {}) {
     }
   }
 
+  // ── Output ────────────────────────────────────────────────────────────────
   const removed = results.filter(r => r.removed).length;
   const found = results.filter(r => r.reason !== 'not_found').length;
 
   console.log(chalk.bold('  清理结果:'));
   for (const item of results) {
     if (item.removed) {
-      console.log(chalk.green(`    ✓ 已删除: ${item.path}`));
+      const note = item.note ? chalk.gray(` ${item.note}`) : '';
+      console.log(chalk.green(`    ✓ 已删除: ${item.path}`) + note);
     } else if (item.reason === 'dry_run') {
       console.log(chalk.gray(`    [dry-run] ${item.path}`));
     }
@@ -107,4 +190,20 @@ export async function runClean(directory, options = {}) {
     console.log(chalk.green(`  清理完成：已删除 ${removed} 项。`));
   }
   console.log('');
+  console.log(chalk.gray('  注意：.prizm-docs/ 为 AI 生成的项目上下文文档，已一并清理。'));
+  console.log(chalk.gray('        用户自定义的 agent/skill/rule 文件未受影响。'));
+  console.log('');
+}
+
+/**
+ * Extract base file names from rules metadata (strip category prefix).
+ * e.g. "prizm/prizm-documentation" -> "prizm-documentation"
+ */
+function metadata_rules_to_filenames(rulesMeta) {
+  const names = {};
+  for (const key of Object.keys(rulesMeta.rules || {})) {
+    const basename = key.split('/').pop();
+    names[basename] = true;
+  }
+  return names;
 }

package/src/external-skills.js

@@ -1,71 +1,80 @@
 /**
  * External Skills Installer
- * Fetches and installs third-party skills from remote URLs.
+ *
+ * Delegates to `npx skills add <repo> --skill <name> --yes` for installation,
+ * then removes symlinks for platforms not selected by the user.
+ *
+ * npx skills creates symlinks for ALL platforms (.claude/skills/, .codebuddy/skills/,
+ * .trae/skills/, skills/, .agent/skills/). We keep only what the user asked for.
  */
 
-import https from 'node:https';
-import http from 'node:http';
+import { execSync } from 'node:child_process';
 import path from 'path';
 import fs from 'fs-extra';
 
-/**
- * Fetch content from a remote URL (supports http and https)
- * @param {string} url - Remote URL to fetch
- * @returns {Promise<string>} - Content string
- */
-export function fetchRemoteSkill(skill) {
-  return new Promise((resolve, reject) => {
-    const url = skill.source;
-    const protocol = url.startsWith('https://') ? https : http;
-
-    const request = protocol.get(url, (res) => {
-      if (res.statusCode === 301 || res.statusCode === 302) {
-        // Follow redirect
-        const redirectSkill = { ...skill, source: res.headers.location };
-        resolve(fetchRemoteSkill(redirectSkill));
-        return;
-      }
+// All platform symlink dirs that `npx skills` creates (besides .agents/ canonical store)
+const ALL_PLATFORM_DIRS = [
+  '.claude/skills',
+  '.codebuddy/skills',
+  '.trae/skills',
+  '.agent/skills',
+  'skills',
+];
 
-      if (res.statusCode !== 200) {
-        reject(new Error(`HTTP ${res.statusCode}: ${url}`));
-        return;
-      }
-
-      const chunks = [];
-      res.on('data', chunk => chunks.push(chunk));
-      res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
-      res.on('error', reject);
-    });
-
-    request.on('error', reject);
-    request.setTimeout(15000, () => {
-      request.destroy();
-      reject(new Error(`Timeout fetching ${url}`));
-    });
-  });
-}
+// Which dirs to KEEP per platform selection
+const KEEP_DIRS = {
+  claude:    ['.claude/skills'],
+  codebuddy: ['.codebuddy/skills'],
+  both:      ['.claude/skills', '.codebuddy/skills'],
+};
 
 /**
- * Install an external skill to the target platform directory.
- * @param {Object} skill - Skill definition from external_skills.known
- * @param {string} platform - 'codebuddy' | 'claude'
- * @param {string} projectRoot - Target project root
- * @param {boolean} dryRun - If true, don't write files
+ * Install an external skill via `npx skills add`, then prune unwanted platform symlinks.
+ *
+ * @param {Object} skill        - Skill definition from external_skills.known
+ *   skill.repo  {string}       - GitHub URL
+ *   skill.name  {string}       - Skill name as listed in the repo
+ * @param {string} platform     - 'claude' | 'codebuddy' | 'both'
+ * @param {string} projectRoot  - Target project root
+ * @param {boolean} dryRun
  */
 export async function installExternalSkill(skill, platform, projectRoot, dryRun) {
-  const content = await fetchRemoteSkill(skill);
+  if (!skill.repo) {
+    throw new Error(`Skill "${skill.name}" has no repo URL defined`);
+  }
+
+  const cmd = `npx skills add ${skill.repo} --skill ${skill.name} --yes`;
 
   if (dryRun) {
+    const keepDirs = KEEP_DIRS[platform] || KEEP_DIRS.claude;
+    console.log(`      [dry-run] ${cmd}`);
+    console.log(`      [dry-run] keep symlinks: ${keepDirs.map(d => path.join(d, skill.name)).join(', ')}`);
     return;
   }
 
-  if (platform === 'codebuddy') {
-    const targetDir = path.join(projectRoot, '.codebuddy', 'skills', skill.name);
-    await fs.ensureDir(targetDir);
-    await fs.writeFile(path.join(targetDir, 'SKILL.md'), content);
-  } else if (platform === 'claude') {
-    const targetDir = path.join(projectRoot, '.claude', 'commands');
-    await fs.ensureDir(targetDir);
-    await fs.writeFile(path.join(targetDir, `${skill.name}.md`), content);
+  execSync(cmd, {
+    cwd: projectRoot,
+    stdio: 'pipe',
+    timeout: 60000,
+  });
+
+  // Prune symlinks for platforms not selected
+  const keepDirs = new Set(KEEP_DIRS[platform] || KEEP_DIRS.claude);
+
+  for (const dir of ALL_PLATFORM_DIRS) {
+    const linkPath = path.join(projectRoot, dir, skill.name);
+    if (keepDirs.has(dir)) continue;
+    try {
+      const stat = await fs.lstat(linkPath);
+      if (stat.isSymbolicLink()) {
+        await fs.remove(linkPath);
+        // Remove parent dir if now empty
+        const parent = path.join(projectRoot, dir);
+        const remaining = await fs.readdir(parent).catch(() => ['_']);
+        if (remaining.length === 0) await fs.remove(parent);
+      }
+    } catch {
+      // not present, skip
+    }
   }
 }

package/src/scaffold.js

@@ -472,25 +472,34 @@ async function installGitHook(projectRoot, dryRun) {
 }
 
 /**
- * 安装 validate-prizm-docs.sh 到 dev-pipeline/scripts/
+ * 安装 PrizmKit 脚本到 .prizmkit/scripts/（始终安装）
  */
-async function installValidateScript(projectRoot, dryRun) {
-  const sourcePath = path.join(getTemplatesDir(), 'hooks', 'validate-prizm-docs.sh');
-  if (!fs.existsSync(sourcePath)) return;
+async function installPrizmkitScripts(projectRoot, dryRun) {
+  const scriptsDir = path.join(projectRoot, '.prizmkit', 'scripts');
+  const templateHooksDir = path.join(getTemplatesDir(), 'hooks');
 
-  const targetDir = path.join(projectRoot, 'dev-pipeline', 'scripts');
-  const targetPath = path.join(targetDir, 'validate-prizm-docs.sh');
+  const scripts = [
+    'validate-prizm-docs.sh',
+    'diff-prizm-docs.sh',
+  ];
 
   if (dryRun) {
-    console.log(chalk.gray('      [dry-run] dev-pipeline/scripts/validate-prizm-docs.sh'));
+    for (const s of scripts) {
+      console.log(chalk.gray(`      [dry-run] .prizmkit/scripts/${s}`));
+    }
     return;
   }
 
-  await fs.ensureDir(targetDir);
-  await fs.copy(sourcePath, targetPath);
-  fs.chmodSync(targetPath, 0o755);
+  await fs.ensureDir(scriptsDir);
 
-  console.log(chalk.green('      ✓ dev-pipeline/scripts/validate-prizm-docs.sh'));
+  for (const s of scripts) {
+    const src = path.join(templateHooksDir, s);
+    if (!fs.existsSync(src)) continue;
+    const tgt = path.join(scriptsDir, s);
+    await fs.copy(src, tgt);
+    fs.chmodSync(tgt, 0o755);
+    console.log(chalk.green(`      ✓ .prizmkit/scripts/${s}`));
+  }
 }
 
 /**
@@ -695,13 +704,12 @@ export async function scaffold(config) {
     for (const name of externalSkills) {
       const skillDef = knownSkills.find(s => s.name === name);
       if (skillDef) {
-        for (const p of platforms) {
-          try {
-            await installExternalSkill(skillDef, p, projectRoot, dryRun);
-            console.log(chalk.green(`      ✓ ${name} (external)`));
-          } catch (e) {
-            console.log(chalk.yellow(`      ⚠ ${name} 拉取失败，跳过: ${e.message}`));
-          }
+        try {
+        // npx skills add handles installation; we pass platform to prune unwanted symlinks
+          await installExternalSkill(skillDef, platform, projectRoot, dryRun);
+          console.log(chalk.green(`      ✓ ${name} (external)`));
+        } catch (e) {
+          console.log(chalk.yellow(`      ⚠ ${name} 安装失败，跳过: ${e.message}`));
         }
       }
     }
@@ -711,11 +719,9 @@ export async function scaffold(config) {
   console.log(chalk.blue('    Git Hook:'));
   await installGitHook(projectRoot, dryRun);
 
-  // 11. Validate script (only if pipeline enabled)
-  if (pipeline) {
-    console.log(chalk.blue('    验证脚本:'));
-    await installValidateScript(projectRoot, dryRun);
-  }
+  // 11. PrizmKit scripts (always installed)
+  console.log(chalk.blue('    PrizmKit 脚本:'));
+  await installPrizmkitScripts(projectRoot, dryRun);
 
   // === 完成 ===
   console.log('');