prizmkit 1.0.13 → 1.0.14

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/package.json

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

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);
+  }
+}

package/src/index.js

@@ -5,10 +5,9 @@
  * 然后调用 scaffold.js 执行纯净安装。
  */
 
-import { select, confirm } from '@inquirer/prompts';
+import { select, confirm, input } from '@inquirer/prompts';
 import chalk from 'chalk';
 import path from 'path';
-import fs from 'fs-extra';
 import { detectPlatform } from './detect-platform.js';
 import { scaffold } from './scaffold.js';
 import { loadMetadata } from './metadata.js';
@@ -54,6 +53,9 @@ export async function runScaffold(directory, options) {
       skills: options.skills || 'full',
       team: options.team !== false,
       pipeline: options.pipeline !== false,
+      rules: options.rules || 'recommended',
+      aiCli: options.aiCli || '',
+      externalSkills: options.externalSkills ? options.externalSkills.split(',').map(s => s.trim()).filter(Boolean) : [],
       projectRoot,
       dryRun: options.dryRun || false,
     };
@@ -82,8 +84,15 @@ export async function runScaffold(directory, options) {
       default: detected.suggested,
     });
 
+    // 1.5. AI CLI 命令配置
+    const defaultCli = detected.cbc ? 'cbc' : detected.claude ? 'claude' : '';
+    const aiCli = await input({
+      message: '底层 AI CLI 可执行命令 (留空自动检测):',
+      default: defaultCli,
+    });
+
     // 2. 选择技能套件
-    const skillSuite = await select({
+    const skillSuiteChoice = await select({
       message: '选择技能套件:',
       choices: [
         {
@@ -98,10 +107,41 @@ export async function runScaffold(directory, options) {
           name: `Minimal — 最小可用 (${metadata.suites.minimal.skills.length} 个技能)`,
           value: 'minimal',
         },
+        {
+          name: 'Recommended — 按项目类型推荐 ▸',
+          value: 'recommended',
+        },
       ],
       default: 'full',
     });
 
+    let skillSuite = skillSuiteChoice;
+    if (skillSuiteChoice === 'recommended') {
+      const projectType = await select({
+        message: '选择项目类型:',
+        choices: Object.entries(metadata.recommendations || {}).map(([key, val]) => ({
+          name: val.label,
+          value: `recommended:${key}`,
+        })),
+      });
+      skillSuite = projectType;
+    }
+
+    // 2.5. 外部 Skill 选择（可选）
+    let selectedExternalSkills = [];
+    const knownExternalSkills = metadata.external_skills?.known || [];
+    if (knownExternalSkills.length > 0) {
+      const { checkbox } = await import('@inquirer/prompts');
+      selectedExternalSkills = await checkbox({
+        message: '选择要安装的第三方 Skills（可选，需要网络）:',
+        choices: knownExternalSkills.map(s => ({
+          name: `${s.name} — ${s.description}`,
+          value: s.name,
+          checked: false,
+        })),
+      });
+    }
+
     // 3. 团队模式
     const team = await confirm({
       message: '启用多 Agent 团队模式 (prizm-dev-team)?',
@@ -114,12 +154,24 @@ export async function runScaffold(directory, options) {
       default: true,
     });
 
+    // 5. Rules 预设
+    const rulesPreset = await select({
+      message: '安装 AI 行为规则 (rules):',
+      choices: [
+        { name: 'Recommended — 全部规则 (推荐)', value: 'recommended' },
+        { name: 'Minimal — 仅渐进式加载 + 通用规则', value: 'minimal' },
+        { name: 'None — 不安装规则', value: 'none' },
+      ],
+      default: 'recommended',
+    });
+
     // 显示安装摘要
     const platformLabel = platform === 'both' ? 'CodeBuddy + Claude Code'
       : platform === 'codebuddy' ? 'CodeBuddy' : 'Claude Code';
     const suiteLabel = skillSuite === 'full' ? `Full (${totalSkills} 个)`
       : skillSuite === 'core' ? `Core (${metadata.suites.core.skills.length} 个)`
-      : `Minimal (${metadata.suites.minimal.skills.length} 个)`;
+      : skillSuite === 'minimal' ? `Minimal (${metadata.suites.minimal.skills.length} 个)`
+      : `Recommended (${skillSuite})`;
 
     console.log('');
     console.log(chalk.bold('  安装摘要:'));
@@ -127,6 +179,9 @@ export async function runScaffold(directory, options) {
     console.log(`    技能:       ${chalk.cyan(suiteLabel)}`);
     console.log(`    团队模式:   ${team ? chalk.green('启用') : chalk.gray('禁用')}`);
     console.log(`    流水线:     ${pipeline ? chalk.green('启用') : chalk.gray('禁用')}`);
+    console.log(`    规则:       ${chalk.cyan(rulesPreset)}`);
+    if (aiCli) console.log(`    AI CLI:     ${chalk.cyan(aiCli)}`);
+    if (selectedExternalSkills.length > 0) console.log(`    外部技能:   ${chalk.cyan(selectedExternalSkills.join(', '))}`);
     console.log(`    目标目录:   ${projectRoot}`);
     console.log('');
 
@@ -146,6 +201,9 @@ export async function runScaffold(directory, options) {
       skills: skillSuite,
       team,
       pipeline,
+      rules: rulesPreset,
+      aiCli: aiCli || '',
+      externalSkills: selectedExternalSkills,
       projectRoot,
       dryRun: options.dryRun || false,
     };

package/src/metadata.js

@@ -51,6 +51,7 @@ export async function loadMetadata() {
 
   throw new Error(
     '无法找到 Skill 元数据文件。\n' +
+    `尝试路径：\n  1. ${bundledPath}\n  2. ${corePath}\n` +
     '请确保在 PrizmKit 框架目录中运行，或已执行 `npm run bundle` 打包资源。'
   );
 }
@@ -131,4 +132,39 @@ export function getAdaptersDir() {
   if (fs.pathExistsSync(coreDir)) return coreDir;
 
   throw new Error('无法找到 Adapters 目录。');
+}
+
+/**
+ * 获取 core rules 目录路径
+ */
+export function getRulesDir() {
+  const bundledDir = path.join(getBundledRoot(), 'rules');
+  const coreDir = path.join(getFrameworkRoot(), 'core', 'rules');
+
+  if (fs.pathExistsSync(bundledDir)) return bundledDir;
+  if (fs.pathExistsSync(coreDir)) return coreDir;
+
+  throw new Error('无法找到 Rules 目录。');
+}
+
+/**
+ * 加载 Rules 元数据
+ * @returns {Promise<Object>} metadata 对象（包含 rules 和 presets）
+ */
+export async function loadRulesMetadata() {
+  const bundledPath = path.join(getBundledRoot(), 'rules', '_rules-metadata.json');
+  const corePath = path.join(getFrameworkRoot(), 'core', 'rules', '_rules-metadata.json');
+
+  if (await fs.pathExists(bundledPath)) {
+    return fs.readJSON(bundledPath);
+  }
+
+  if (await fs.pathExists(corePath)) {
+    return fs.readJSON(corePath);
+  }
+
+  throw new Error(
+    '无法找到 Rules 元数据文件。\n' +
+    `尝试路径：\n  1. ${bundledPath}\n  2. ${corePath}`
+  );
 }