prizmkit 1.0.13 → 1.0.15

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "[Tier 1] End-to-end refactor workflow: analyze → plan → tasks → implement → review → commit. 6-phase behavior-preserving pipeline with scope guard and mandatory test gates. (project)"
+description: "[Tier 1] End-to-end refactor workflow: analyze → plan → tasks → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. (project)"
+---
+
+refactor-workflow-SKILL.md
+refactor-workflow/SKILL.md
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills (tech-debt-tracker, plan, tasks, implement, code-review, committer) into a 6-phase behavior-preserving pipeline with scope guard enforcement.
+End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills (tech-debt-tracker, plan, tasks, implement, code-review, committer) into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ## Overview
 
@@ -32,148 +36,99 @@ prizmkit.refactor <目标模块或描述>
 | 6 | Commit | `prizmkit.committer` | git commit |
 
 ### Key Principles
-
-- **Behavior preservation**: Refactoring MUST NOT change observable behavior
-- **Acceptance criteria** = "behavior unchanged + structure improved"
-- **No REGISTRY entry**: Refactoring does not go into REGISTRY.md
-- **No spec.md**: Refactoring has no user stories
-- **Mandatory test gates**: Full test suite after every task, not just checkpoints
-- **Scope guard**: New behavior detected → STOP and suggest feature-workflow
+| Principle | Description |
+|-----------|-------------|
+| **Behavior preservation** | Refactoring MUST NOT change observable behavior. Acceptance criteria = "behavior unchanged + structure improved". |
+| **Test gates** | Full test suite MUST run after EVERY task** — not just at checkpoints. |
+| **No REGISTRY entry** | Refactoring does not go into REGISTRY.md (no user stories, no feature registration). |
+| **Incremental safety** | Each task preserves all tests; if tests fail → STOP and revert. |
 
 ### Artifacts
-
 Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 - **`refactor-analysis.md`** — Code analysis (Phase 1)
 - **`plan.md`** — Refactoring plan (Phase 2)
 - **`tasks.md`** — Task breakdown (Phase 3)
 
 ## Commands
-
 ### prizmkit.refactor \<目标模块或描述\>
-
 Execute the full refactor pipeline for a module or code area.
-
 **INPUT**: Target description. Can be:
 - Module or file path (e.g., "src/auth/")
 - Natural language description (e.g., "重构认证模块，提取公共逻辑")
 - Specific refactoring goal (e.g., "extract payment processing into separate service")
-
 ---
 
 ## Phase 1: Analyze — 代码分析
-
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
-
 **STEPS:**
-
 1. **Read target code**: Thoroughly read and understand the target module/files:
    - Code structure and architecture
    - Dependencies (incoming and outgoing)
    - Current test coverage
    - Known tech debt (from `.prizm-docs/` TRAPS)
-
 2. **Invoke `prizmkit.tech-debt-tracker`** on target area:
    - Receive: debt items, complexity metrics, code smell patterns
    - Identify highest-impact refactoring opportunities
-
 3. **Establish baseline**:
    - Run full test suite — record pass/fail counts
    - Note any pre-existing test failures (isolate from refactor impact)
    - Document current behavior contracts (public API, interfaces)
-
 4. **Generate `refactor-analysis.md`** at `.prizmkit/refactor/<refactor-slug>/refactor-analysis.md`:
-
    Required sections:
    - **Current State**: module overview, file inventory, dependency graph, complexity metrics
    - **Refactoring Goals**: what structural improvements are targeted, why (debt items, complexity, maintainability)
    - **Risk Assessment**: what could break, cross-module impact, data migration needs
    - **Baseline Tests**: test suite status (total, passing, failing), coverage estimate, behavior contracts to preserve
    - **Scope Boundary**: what IS in scope, what is explicitly OUT of scope
-
 **CHECKPOINT CP-RW-1**: `refactor-analysis.md` exists with baseline test results.
-
 ---
-
 ## Phase 2: Plan — 重构方案
-
 **Goal**: Generate technical refactoring plan that preserves behavior.
-
 **STEPS:**
-
 1. **Read context**: refactor-analysis.md, `.prizm-docs/` (PATTERNS, RULES, TRAPS)
-
 2. **Invoke `prizmkit.plan`** with refactor-analysis.md as input (in place of spec.md):
    - Plan MUST specify: what changes, what stays the same, how behavior is preserved
    - Artifact path: `.prizmkit/refactor/<refactor-slug>/plan.md`
-
 3. **Verify plan constraints**:
-   - No new user-facing behavior (scope guard)
    - All public API contracts preserved
    - Test strategy: how to verify behavior unchanged at each step
    - Rollback strategy: how to revert if behavior breaks
-
 **CHECKPOINT CP-RW-2**: `plan.md` exists with behavior preservation strategy.
-
 ---
-
 ## Phase 3: Tasks — 任务拆解
-
 **Goal**: Break refactoring plan into safe, atomic, testable tasks.
-
 **STEPS:**
-
 1. **Invoke `prizmkit.tasks`** with plan.md:
    - Each task MUST be independently testable
    - Each task MUST preserve all tests (green → green)
    - Artifact path: `.prizmkit/refactor/<refactor-slug>/tasks.md`
-
 2. **Verify task safety**:
    - Every task ends with "run full test suite"
    - No task introduces temporary test failures
    - Tasks are ordered to minimize risk (safe renames first, structural changes later)
-
 **CHECKPOINT CP-RW-3**: `tasks.md` exists with test gates on every task.
-
 ---
-
 ## Phase 4: Implement — 实现
-
 **Goal**: Execute refactoring tasks with mandatory test verification after each task.
-
 **STEPS:**
-
 1. **For EACH task in tasks.md**:
    a. Implement the refactoring change
    b. **Run FULL test suite** (not just affected tests)
    c. Verify: all previously-passing tests still pass
    d. If any test fails → STOP, revert task, investigate
-
-2. **Scope Guard** (checked after each task):
-   - If implementation reveals need for new behavior → **STOP**
-   - Output: "Scope guard triggered: <description of new behavior needed>"
-   - Recommend: "Switch to `prizmkit.feature` for this change"
-   - Do NOT proceed with behavior changes in refactor pipeline
-
-3. **Progress tracking**:
+2. **Progress tracking**:
    - Mark tasks complete in tasks.md as they finish
    - Record test results after each task
-
 **CHECKPOINT CP-RW-4**: All tasks complete, full test suite green.
-
 **KEY RULES:**
 - NEVER skip the test gate between tasks
 - NEVER allow temporary test failures ("we'll fix it in the next task")
 - If a task cannot be completed without breaking tests → split it into smaller tasks
 - Max 3 attempts per task before escalating to user
-
 ---
-
 ## Phase 5: Code Review — 代码审查
-
 **Goal**: Verify refactoring quality and behavior preservation.
-
 **STEPS:**
-
 1. **Invoke `prizmkit.code-review`** (scoped to changed files):
    - Review dimensions for refactoring:
      - **Behavior preservation**: Does observable behavior remain identical?
@@ -181,69 +136,47 @@ Execute the full refactor pipeline for a module or code area.
      - **Test integrity**: Are all tests still meaningful and passing?
      - **Code quality**: Does refactored code follow project conventions?
    - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
-
 2. **Run full test suite one final time**: All tests MUST pass
-
 3. **Handle review results**:
    - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 6
    - **NEEDS_FIXES**: Return to Phase 4 (max 2 review rounds)
-
 **CHECKPOINT CP-RW-5**: Code review passes, all tests green.
-
 ---
-
 ## Phase 6: Commit — 提交
-
 **Goal**: Commit with refactor convention.
-
 **STEPS:**
-
 1. **Invoke `prizmkit.committer`**:
    - Commit message: `refactor(<scope>): <description>`
    - Include all refactored code + any test updates
    - Do NOT push
    - Do NOT invoke `prizmkit.summarize` (no REGISTRY entry for refactoring)
-
 2. **Update `.prizm-docs/`** if needed:
    - Updated module structure documentation
    - New PATTERNS discovered
    - Resolved TRAPS (remove if debt is paid)
-
 **CHECKPOINT CP-RW-6**: Commit recorded with `refactor()` prefix.
-
 ---
-
 ## Fast Path — 快速路径
-
 For single-file refactoring (rename, extract method, <30 lines changed):
-
 ```
 Phase 1 (Analyze) → Phase 4 (Implement) → Phase 5 (Review) → Phase 6 (Commit)
 ```
-
 Skip Phase 2 (Plan) and Phase 3 (Tasks).
-
 **CRITERIA** (ALL must be true):
 - Single file change
 - Estimated change < 30 lines
 - Well-known refactoring pattern (rename, extract method/class, inline, move)
 - No cross-module impact
 - No dependency changes
-
 **Fast Path still requires:**
 - refactor-analysis.md (lightweight version with baseline)
 - Full test suite run after implementation
 - Code review
 - `refactor(<scope>):` commit convention
-
 ---
-
 ## Resume — 中断恢复
-
 The pipeline supports resuming from the last completed phase by detecting existing artifacts.
-
 **Detection logic**: Check `.prizmkit/refactor/<slug>/` for:
-
 | Artifact Found | Resume From |
 |---------------|------------|
 | (nothing) | Phase 1: Analyze |
@@ -252,70 +185,39 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | All 3 docs | Phase 4: Implement |
 | All 3 docs + code changes exist | Phase 5: Review |
 | All 3 docs + review passed | Phase 6: Commit |
-
 **Resume command**: `prizmkit.refactor <slug>` — if `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
-
 ---
-
-## Scope Guard — 范围守卫
-
-The scope guard is a critical safety mechanism that prevents behavior changes from sneaking into refactoring.
-
-**Triggers:**
-- New public API method or endpoint added
-- New user-facing feature or UI element
-- Changed return values or response formats
-- New configuration options
-- Modified business logic (not just restructured)
-
-**When triggered:**
-1. STOP current task immediately
-2. Output clear message: "⚠️ Scope Guard: This change introduces new behavior"
-3. Describe what new behavior was detected
-4. Recommend: "Create a feature request and use `prizmkit.feature` instead"
-5. Offer to continue refactoring WITHOUT the behavior change
-
----
-
 ## Error Handling
-
 | Scenario | Action |
 |----------|--------|
 | Cannot identify target module | Ask user for clarification |
 | No tests exist for target module | WARN user, recommend writing tests first |
 | Baseline tests already failing | Isolate failures, document, proceed with caution |
 | Test fails after a refactoring task | Revert task, investigate, retry or split |
-| Scope guard triggered | STOP, recommend feature-workflow |
 | Implementation fails after 3 rounds | Escalate to user with analysis |
 | Review fails after 2 rounds | Escalate with review findings |
 | Refactoring creates circular dependency | STOP, revise plan |
 | Performance regression detected | STOP, investigate, revise approach |
-
 ---
-
 ## Relationship to Other Skills
-
 | Skill | Role in Refactor Workflow |
 |-------|--------------------------|
-| `prizmkit-tech-debt-tracker` | Phase 1: identify debt and complexity |
+| `prizmkit-tool-tech-debt-tracker` | Phase 1: identify debt and complexity |
 | `prizmkit-plan` | Phase 2: refactoring plan generation |
 | `prizmkit-tasks` | Phase 3: task breakdown |
 | `prizmkit-implement` | Phase 4: execute refactoring tasks |
 | `prizmkit-code-review` | Phase 5: review quality and behavior preservation |
 | `prizmkit-committer` | Phase 6: commit with `refactor()` convention |
-| `feature-workflow` | Handoff target when scope guard triggers |
+| `feature-workflow` | Handoff target when new behavior is needed |
 | `prizmkit-specify` | NOT used (no user stories for refactoring) |
 | `prizmkit-analyze` | NOT used (no spec ↔ plan consistency needed) |
 | `prizmkit-summarize` | NOT used (no REGISTRY entry for refactoring) |
 | `prizmkit-retrospective` | Optional: post-refactor lessons learned |
-
 ---
-
 ## Comparison with Feature and Bug Fix Pipelines
-
 | Dimension | Feature Workflow | Refactor Workflow | Bug Fix Pipeline |
-|-----------|-----------------|-------------------|-----------------|
-| Input | Requirement description | Module/code target | Bug description |
+|-----------|-----------------|-------------------|------------------|
+| Input | Natural language requirement | Module/code target | Bug description |
 | Pipeline Phases | 7 (Fast: 5) | 6 (Fast: 4) | 5 (Fast: 3) |
 | Phase 1 | Specify (spec.md) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
 | Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
@@ -324,13 +226,9 @@ The scope guard is a critical safety mechanism that prevents behavior changes fr
 | Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
 | Scope Guard | N/A | ✅ (enforced) | N/A |
 | Behavior Change | ✅ Expected | ❌ Forbidden | ✅ Fix behavior |
-
 ## Path References
-
 All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
-
 ## Output
-
 - `refactor-analysis.md` (Phase 1 artifact)
 - `plan.md` (Phase 2 artifact)
 - `tasks.md` (Phase 3 artifact)

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

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_DOC_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/ per Prizm auto-update protocol. Steps: 1) Run git diff --cached --name-status. 2) Map changed files to modules via root.prizm MODULE_INDEX. 3) Read and update affected .prizm files (only changed sections). 4) Append to changelog.prizm. 5) Stage .prizm files with git add .prizm-docs/. 6) Then proceed with commit using prizmkit-committer workflow. RULES: Never rewrite entire .prizm files. Never add prose. Only update affected sections.'"
+            "command": "SRC=$(git diff --cached --name-only 2>/dev/null | grep -cE '\\.(ts|tsx|js|jsx|py|go|rs|java)$'); if [ \"$SRC\" -gt 0 ]; then PRIZM=$(git diff --cached --name-only 2>/dev/null | grep -c '^\\.prizm-docs/'); if [ \"$PRIZM\" -gt 0 ]; then echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ updated ($PRIZM file(s))\"; else echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ NOT UPDATED — update if this is a feature change\"; fi; fi"
           }
         ]
       }

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

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_DOC_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/ per Prizm auto-update protocol. Steps: 1) Run git diff --cached --name-status. 2) Map changed files to modules via root.prizm MODULE_INDEX. 3) Read and update affected .prizm files (only changed sections). 4) Append to changelog.prizm. 5) Stage .prizm files with git add .prizm-docs/. 6) Then proceed with commit using prizmkit-committer workflow. RULES: Never rewrite entire .prizm files. Never add prose. Only update affected sections.'"
+            "command": "SRC=$(git diff --cached --name-only 2>/dev/null | grep -cE '\\.(ts|tsx|js|jsx|py|go|rs|java)$'); if [ \"$SRC\" -gt 0 ]; then PRIZM=$(git diff --cached --name-only 2>/dev/null | grep -c '^\\.prizm-docs/'); if [ \"$PRIZM\" -gt 0 ]; then echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ updated ($PRIZM file(s))\"; else echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ NOT UPDATED — update if this is a feature change\"; fi; fi"
           }
         ]
       }

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

@@ -0,0 +1,58 @@
+#!/bin/sh
+# prizm-pre-commit.sh — git pre-commit hook for .prizm-docs validation
+
+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"
+
+if [ -f "$VALIDATE_SCRIPT" ]; then
+    sh "$VALIDATE_SCRIPT" --staged
+    exit $?
+fi
+
+# Inline fallback: core checks for staged .prizm files
+FILES=$(git diff --cached --name-only 2>/dev/null | grep '\.prizm$')
+[ -z "$FILES" ] && exit 0
+
+ERRORS=0
+for FILE in $FILES; do
+    [ -f "$FILE" ] || continue
+
+    if grep -qE '^#{1,6} ' "$FILE"; then
+        echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if grep -q '^```' "$FILE"; then
+        echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    case "$FILE" in
+        *root.prizm) LIMIT=4096 ;;
+        *)
+            DIR=$(dirname "$FILE")
+            if [ "$DIR" = ".prizm-docs" ]; then
+                LIMIT=3072
+            else
+                LIMIT=5120
+            fi
+            ;;
+    esac
+
+    if [ "$SIZE" -gt "$LIMIT" ]; then
+        echo "ERROR: $FILE exceeds size limit (${SIZE}B > ${LIMIT}B)." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+done
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "PrizmKit: $ERRORS format error(s) in .prizm files. Fix before committing." >&2
+    exit 1
+fi
+
+exit 0

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

@@ -0,0 +1,84 @@
+#!/bin/sh
+# validate-prizm-docs.sh — validate .prizm file format and size limits
+# Usage: validate-prizm-docs.sh [--all | --staged]
+
+MODE="${1:---staged}"
+ERRORS=0
+
+# Not a prizm project — exit silently
+[ -f ".prizm-docs/root.prizm" ] || exit 0
+
+# Collect files to check
+if [ "$MODE" = "--all" ]; then
+    FILES=$(find .prizm-docs -name '*.prizm' 2>/dev/null)
+elif [ "$MODE" = "--staged" ]; then
+    FILES=$(git diff --cached --name-only 2>/dev/null | grep '\.prizm$')
+else
+    echo "Usage: validate-prizm-docs.sh [--all | --staged]" >&2
+    exit 1
+fi
+
+# Nothing to check — exit silently
+[ -z "$FILES" ] && exit 0
+
+for FILE in $FILES; do
+    [ -f "$FILE" ] || continue
+
+    # Check markdown headers
+    if grep -qE '^#{1,6} ' "$FILE"; then
+        echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check code blocks
+    if grep -q '^```' "$FILE"; then
+        echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Size limits — determine level by path depth
+    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    case "$FILE" in
+        *root.prizm)
+            LIMIT=4096; LEVEL="L0"
+            HINT="Consolidate MODULE_INDEX, keep top-5 RULES."
+            ;;
+        *)
+            # L1 = direct child of .prizm-docs/, L2 = nested deeper
+            DIR=$(dirname "$FILE")
+            if [ "$DIR" = ".prizm-docs" ]; then
+                LIMIT=3072; LEVEL="L1"
+                HINT="Move implementation details to L2."
+            else
+                LIMIT=5120; LEVEL="L2"
+                HINT="Archive CHANGELOG entries older than 90 days."
+            fi
+            ;;
+    esac
+
+    if [ "$SIZE" -gt "$LIMIT" ]; then
+        echo "ERROR: $FILE exceeds $LEVEL limit (${SIZE}B > ${LIMIT}B). $HINT" >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Required fields in root.prizm
+    case "$FILE" in
+        *root.prizm)
+            if ! grep -q 'PRIZM_VERSION:' "$FILE"; then
+                echo "ERROR: $FILE missing required field PRIZM_VERSION:" >&2
+                ERRORS=$((ERRORS + 1))
+            fi
+            if ! grep -q 'MODULE_INDEX:' "$FILE"; then
+                echo "ERROR: $FILE missing required field MODULE_INDEX:" >&2
+                ERRORS=$((ERRORS + 1))
+            fi
+            ;;
+    esac
+done
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "PrizmKit: $ERRORS format error(s) in .prizm files. Fix before committing." >&2
+    exit 1
+fi
+
+exit 0

package/package.json

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

package/src/detect-platform.js

@@ -6,9 +6,9 @@
 import { execFileSync } from 'child_process';
 
 /**
- * 允许检测的命令白名单
+ * 允许检测的命令白名单（仅用于 which 检测）
  */
-const ALLOWED_COMMANDS = ['cbc', 'claude'];
+const ALLOWED_COMMANDS = ['cbc', 'claude', 'claude-internal'];
 
 /**
  * 检查命令是否存在于 PATH 中
@@ -26,21 +26,33 @@ function commandExists(cmd) {
 }
 
 /**
- * 检测已安装的 AI CLI 工具，并返回推荐的默认平台。
- * @returns {{ cbc: boolean, claude: boolean, suggested: string }}
+ * 检测已安装的 AI CLI 工具，并返回推荐的默认平台和 CLI 命令。
+ *
+ * 注意：platform 控制目录结构（.codebuddy/ 或 .claude/），
+ *       suggestedCli 是实际运行的可执行命令，二者相互独立。
+ *
+ * @returns {{ cbc: boolean, claude: boolean, claudeInternal: boolean, suggested: string, suggestedCli: string }}
  */
 export function detectPlatform() {
   const cbc = commandExists('cbc');
   const claude = commandExists('claude');
+  const claudeInternal = commandExists('claude-internal');
 
+  // platform 建议：基于目录结构，优先 both
   let suggested = 'codebuddy';
-  if (cbc && claude) {
+  if ((cbc) && (claude || claudeInternal)) {
     suggested = 'both';
-  } else if (claude && !cbc) {
+  } else if ((claude || claudeInternal) && !cbc) {
     suggested = 'claude';
-  } else if (cbc && !claude) {
+  } else if (cbc && !claude && !claudeInternal) {
     suggested = 'codebuddy';
   }
 
-  return { cbc, claude, suggested };
+  // CLI 命令建议：优先 cbc，其次 claude-internal，再次 claude
+  let suggestedCli = '';
+  if (cbc) suggestedCli = 'cbc';
+  else if (claudeInternal) suggestedCli = 'claude-internal';
+  else if (claude) suggestedCli = 'claude';
+
+  return { cbc, claude, claudeInternal, suggested, suggestedCli };
 }

package/src/external-skills.js

@@ -0,0 +1,71 @@
+/**
+ * External Skills Installer
+ * Fetches and installs third-party skills from remote URLs.
+ */
+
+import https from 'node:https';
+import http from 'node:http';
+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;
+      }
+
+      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}`));
+    });
+  });
+}
+
+/**
+ * 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
+ */
+export async function installExternalSkill(skill, platform, projectRoot, dryRun) {
+  const content = await fetchRemoteSkill(skill);
+
+  if (dryRun) {
+    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);
+  }
+}