prizmkit 1.0.58 → 1.0.66

package/bundled/skills/prizm-kit/assets/project-memory-template.md

@@ -32,7 +32,7 @@ Run `/prizm-kit` to see all available PrizmKit commands.
 Not every change needs the full spec -> plan workflow. Use fast path for:
 - Bug fixes with clear root cause, config tweaks, typo fixes, simple refactors
 - Documentation-only changes, test additions for existing code
-- Directly use `/prizmkit-implement` with inline task description, then `/prizmkit-committer`
+- Fast path: `/prizmkit-plan` (simplified) → `/prizmkit-implement` → `/prizmkit-committer`
 
 Use the full workflow (/prizmkit-specify -> /prizmkit-plan -> /prizmkit-analyze -> /prizmkit-implement) for:
 - New features, multi-file coordinated changes, architectural decisions, data model or API changes

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

@@ -1,11 +1,11 @@
 ---
 name: "prizmkit-analyze"
-description: "Cross-document consistency analysis for spec.md, plan.md, and tasks.md. Detects duplications, ambiguities, gaps, and rule conflicts. Read-only. Use this skill to check if spec and plan are aligned, validate documents before coding, or as a quality gate after planning. Trigger on: 'analyze', 'check consistency', 'validate spec', 'review plan', 'is the spec ready', 'check if spec and plan are aligned', 'validate documents before coding'. (project)"
+description: "Cross-document consistency analysis for spec.md and plan.md (including Tasks section). Detects duplications, ambiguities, gaps, and rule conflicts. Read-only. Use this skill to check if spec and plan are aligned, validate documents before coding, or as a quality gate after planning. Trigger on: 'analyze', 'check consistency', 'validate spec', 'review plan', 'is the spec ready', 'check if spec and plan are aligned', 'validate documents before coding'. (project)"
 ---
 
 # PrizmKit Analyze
 
-Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md before implementation. Identifies duplications, ambiguities, underspecified items, rule conflicts, and coverage gaps.
+Perform a non-destructive cross-artifact consistency and quality analysis across spec.md and plan.md (including Tasks section) before implementation. Identifies duplications, ambiguities, underspecified items, rule conflicts, and coverage gaps.
 
 ### When to Use
 - After `/prizmkit-plan` to validate spec-plan-tasks alignment before implementation
@@ -28,8 +28,7 @@ Locate the current feature directory in `.prizmkit/specs/###-feature-name/` by c
 
 Derive absolute paths:
 - SPEC = `.prizmkit/specs/###-feature-name/spec.md`
-- PLAN = `.prizmkit/specs/###-feature-name/plan.md`
-- TASKS = `.prizmkit/specs/###-feature-name/tasks.md` (optional)
+- PLAN = `.prizmkit/specs/###-feature-name/plan.md` (must include a Tasks section)
 
 Abort with an error message if spec.md or plan.md is missing — instruct the user to run the missing prerequisite command (`/prizmkit-specify` or `/prizmkit-plan`).
 
@@ -151,7 +150,7 @@ At end of report, output a concise Next Actions block:
 - Provide explicit command suggestions:
   - "Run `/prizmkit-specify` to refine requirements"
   - "Run `/prizmkit-plan` to adjust architecture or tasks"
-  - "Edit tasks.md to add coverage for requirement X"
+  - "Edit plan.md Tasks section to add coverage for requirement X"
   - "Proceed to `/prizmkit-implement`" (if clean)
 
 ### Step 8: Offer Remediation

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -12,11 +12,19 @@ Perform a comprehensive code review against the feature spec, implementation pla
 - User says "review", "check code", "review my implementation"
 - As a quality gate before `/prizmkit-committer`
 
-**PRECONDITION:** `spec.md`, `plan.md`, `tasks.md` exist in `.prizmkit/specs/###-feature-name/` with completed tasks
+**PRECONDITION (multi-mode):**
+- **Feature mode**: `spec.md` and `plan.md` (with Tasks section) exist in `.prizmkit/specs/###-feature-name/` with completed tasks
+- **Refactor mode**: `refactor-analysis.md` and `plan.md` (with Tasks section) exist in `.prizmkit/refactor/<refactor-slug>/` with completed tasks. No `spec.md` is needed — review against `refactor-analysis.md` goals and behavior preservation instead.
+- **Bugfix mode**: `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with completed tasks. Review against the bug description and reproduction test.
+- **Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
 
 ## Execution Steps
 
-1. Read `spec.md`, `plan.md`, `tasks.md` as review baseline
+1. **Detect mode and load review baseline**:
+   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage.
+   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Review dimensions shift: replace "spec compliance" with **behavior preservation** (observable behavior unchanged), replace "plan adherence" with **structural improvement** (is the code measurably better?). Also check test integrity and code quality.
+   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Review dimensions: bug is actually fixed, no regressions, reproduction test passes, minimal change scope.
+   - If none found → prompt user: "No review baseline found. Which workflow are you in? (feature/refactor/bugfix)"
 2. Read `.prizm-docs/root.prizm` RULES for project conventions
 3. Scan all code files referenced in completed tasks
 4. Review across 6 dimensions:

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

@@ -7,7 +7,7 @@ description: "Pure git commit workflow with safety checks. Stages files, analyze
 
 Pure git commit workflow. Analyzes changes, generates a Conventional Commits message, performs safety checks, and commits.
 
-**This skill does NOT modify any project files.** It only reads and commits. All documentation and memory maintenance must be completed before invoking this skill (via `/prizmkit-retrospective`).
+**This skill is a pure git commit tool. It does NOT modify any project files — no `.prizm-docs/`, no source code, no documentation.** It only reads diffs, generates a commit message, and commits. For feature/refactor workflows, run `/prizmkit-retrospective` before this skill to sync `.prizm-docs/`. For bug fixes, skip retrospective entirely — bug fixes do not update `.prizm-docs/`.
 
 ### When to Use
 - User says "commit", "提交", "finish", "done with this task", "ship it"

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

@@ -10,13 +10,23 @@ Execute implementation by following the task breakdown in plan.md. Respects task
 ### When to Use
 - After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
 - User says "implement", "build", "code it", "start coding", "开发"
-- For fast-path: user describes a simple change directly (skip specify/plan)
+- For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
-**PRECONDITION:** `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
+**PRECONDITION (multi-mode):**
+- **Feature mode** (default): `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
+- **Refactor mode**: `plan.md` exists in `.prizmkit/refactor/<refactor-slug>/` with a Tasks section containing unchecked tasks
+- **Bugfix mode**: `plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with a Tasks section containing unchecked tasks
+- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
 
 ## Execution Steps
 
-1. Read `plan.md` (including Tasks section), `spec.md` for full context
+1. **Detect mode and read context**:
+   - Locate `plan.md` (check the artifact directory passed by the calling workflow, or auto-detect per PRECONDITION above)
+   - Read `plan.md` (including Tasks section)
+   - Read the companion input document for full context:
+     - **Feature mode**: read `spec.md` in the same directory
+     - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
+     - **Bugfix mode**: read `fix-plan.md` in the same directory
 2. Load project context — use the most efficient source available:
    - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS, Section 4 has source files. This snapshot was built in Phase 1 of the pipeline to avoid re-reading dozens of individual files, saving significant tokens.
    - Otherwise → read relevant `.prizm-docs/` L1/L2 for affected modules. Pay special attention to TRAPS (gotchas, race conditions) and DECISIONS (past architectural choices you should respect).

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

@@ -14,16 +14,23 @@ Generate a comprehensive technical implementation plan from a feature specificat
 - When user wants to understand the full implementation approach before coding
 
 ### When NOT to Use
-- No spec.md exists yet → run `/prizmkit-specify` first
-- Simple bug fix or config change → use fast path, no plan needed
+- No input document exists yet (no spec.md, no refactor-analysis.md, no fix-plan.md) → run `/prizmkit-specify` or the appropriate upstream skill first
+- Simple bug fix or config change → use fast path (`/prizmkit-plan` with simplified output → `/prizmkit-implement` → `/prizmkit-committer`)
 - User just wants to explore/research → answer directly, no plan artifact needed
 
-**PRECONDITION:** `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists. If spec.md is missing, prompt the user: "No spec found — want me to run /prizmkit-specify first?"
+**PRECONDITION (multi-mode):**
+- **Feature mode** (default): `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists. If spec.md is missing, prompt the user: "No spec found — want me to run /prizmkit-specify first?"
+- **Refactor mode**: `refactor-analysis.md` exists in `.prizmkit/refactor/<refactor-slug>/`. Use refactor-analysis.md as the input document in place of spec.md. Output plan.md to the same `.prizmkit/refactor/<refactor-slug>/` directory, NOT to `.prizmkit/specs/`.
+- **Bugfix mode**: Bug description provided by caller or `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/`. Output plan.md to the same directory.
+- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
 
 ## Execution Steps
 
 **Phase 0 — Research:**
-1. Read `spec.md` for feature requirements
+1. Read the input document for requirements:
+   - **Feature mode**: Read `spec.md` for feature requirements
+   - **Refactor mode**: Read `refactor-analysis.md` for refactoring goals, scope boundary, and baseline tests
+   - **Bugfix mode**: Read bug description / `fix-plan.md` for reproduction steps and expected fix
 2. Load project context (use first available source):
    - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read it for all context (Section 3 'Prizm Context' for docs, Section 4 'Existing Source Files' for code). The context-snapshot consolidates dozens of individual files into one read, saving significant tokens.
    - Otherwise → read `.prizm-docs/root.prizm` and relevant `.prizm-docs/` L1/L2 docs for affected modules
@@ -90,5 +97,9 @@ The plan template is located at `${SKILL_DIR}/assets/plan-template.md`.
 
 ## Output
 
-All outputs are written to `.prizmkit/specs/###-feature-name/`:
-- `plan.md` — The implementation plan (includes architecture, component design, data model, interface design, testing strategy, risk assessment, and Tasks section)
+Output directory depends on mode:
+- **Feature mode**: `.prizmkit/specs/###-feature-name/plan.md`
+- **Refactor mode**: `.prizmkit/refactor/<refactor-slug>/plan.md`
+- **Bugfix mode**: `.prizmkit/bugfix/<BUG_ID>/plan.md`
+
+The plan.md includes architecture, component design, data model, interface design, testing strategy, risk assessment, and Tasks section.

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-prizm-docs"
-description: "AI-only documentation framework for progressive context loading. Manages .prizm-docs/ with 3-level hierarchy (L0/L1/L2). Use this skill whenever docs need bootstrapping, syncing, checking, validating, rebuilding, or migrating. Trigger on: 'initialize docs', 'update docs', 'sync docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs are stale', 'prizm docs'. Also invoke as part of /prizmkit-init for first-time setup, or before /prizmkit-committer to ensure docs are fresh. (project)"
+description: "Project documentation specification and standard for AI-optimized progressive context loading. Defines the .prizm-docs/ 3-level hierarchy (L0/L1/L2), format rules, size limits, and loading protocol. Use this skill to: bootstrap docs for new projects (init), check doc freshness (status), regenerate stale modules (rebuild), validate format compliance (validate), or migrate existing docs (migrate). For incremental doc updates after code changes, use /prizmkit-retrospective instead — it is the sole writer of .prizm-docs/ during development. Trigger on: 'initialize docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs are stale', 'prizm docs'. (project)"
 ---
 
 # Prizm Docs - AI Documentation Framework
@@ -22,6 +22,20 @@ This skill handles 6 operations. When invoked, determine the user's intent and e
 
 ---
 
+## Role Clarification
+
+**This skill vs `/prizmkit-retrospective`**:
+
+| Aspect | `/prizmkit-prizm-docs` | `/prizmkit-retrospective` |
+|--------|----------------------|--------------------------|
+| **Role** | Documentation SPECIFICATION + BOOTSTRAP | Incremental WRITER during development |
+| **When** | Project setup, health checks, migrations | After feature completion, before commit |
+| **Writes** | Initial .prizm-docs/ structure (init, rebuild, migrate) | Incremental updates to existing .prizm-docs/ |
+| **Reads** | Source code structure (for init/rebuild) | git diff + code changes (for sync) |
+| **Knowledge** | Defines format rules, size limits, loading protocol | Extracts TRAPS/RULES/DECISIONS from work done |
+
+**Key principle**: `/prizmkit-prizm-docs` defines WHAT the docs should look like and bootstraps them. `/prizmkit-retrospective` is the SOLE WRITER that keeps docs in sync with code during ongoing development.
+
 ## Operation: Init
 
 Bootstrap .prizm-docs/ for the current project.

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-retrospective"
-description: "The SOLE maintainer of .prizm-docs/ project memory. Performs two jobs: (1) structural sync — update KEY_FILES/INTERFACES/DEPENDENCIES to reflect code changes, and (2) knowledge injection — extract TRAPS/RULES/DECISIONS from completed work. Update project documentation after code changes. Run after code review passes and before committing. Must be run before /prizmkit-committer. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete', 'update project documentation'. (project)"
+description: "Incremental .prizm-docs/ maintainer — the sole writer during ongoing development. Performs two jobs after code changes: (1) structural sync — update KEY_FILES/INTERFACES/DEPENDENCIES to reflect code changes, and (2) knowledge injection — extract TRAPS/RULES/DECISIONS from completed work. Run after code review passes and before committing. For initial doc setup, validation, or migration, use /prizmkit-prizm-docs instead. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective

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

@@ -14,7 +14,7 @@ Create structured feature specifications from natural language descriptions. Thi
 - When multiple stakeholders need to agree on scope before coding starts
 
 ### When NOT to Use
-- Bug fixes with clear root cause → use fast path (/prizmkit-implement directly)
+- Bug fixes with clear root cause → use fast path (`/prizmkit-plan` simplified → `/prizmkit-implement` → `/prizmkit-committer`)
 - Config tweaks, typo fixes, simple refactors → edit directly
 - Documentation-only changes → no spec needed
 - User already has a detailed spec → skip to /prizmkit-plan
@@ -23,8 +23,12 @@ Create structured feature specifications from natural language descriptions. Thi
 
 1. Ask user for feature description (natural language)
 2. Auto-generate 2-4 word feature slug from description
-3. Determine next feature number by scanning `.prizmkit/specs/`
-4. Create directory: `.prizmkit/specs/###-feature-name/`
+3. Determine next feature number by scanning `.prizmkit/specs/`:
+   - List existing `###-*` directories and find the highest numeric prefix
+   - Next number = highest + 1 (zero-padded to 3 digits)
+   - Append a short timestamp suffix (`-MMDD`) to prevent collisions in concurrent sessions. Example: `004-user-avatar-0319/`
+   - If `.prizmkit/specs/` is empty or doesn't exist, start at `001`
+4. Create directory: `.prizmkit/specs/###-feature-name-MMDD/`
 5. Load project context (use first available source):
    - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read Section 3 'Prizm Context' from it (do NOT re-read `.prizm-docs/` files)
    - Otherwise → read `.prizm-docs/root.prizm`
@@ -47,7 +51,7 @@ Create structured feature specifications from natural language descriptions. Thi
 - **Every user story needs acceptance criteria** in Given/When/Then format — without them, the implementer has no way to verify the feature works correctly, and the code reviewer has no baseline to check against.
 - **Scope boundaries must be explicit** — without "Out of scope" boundaries, implementers tend to gold-plate features with capabilities nobody asked for, wasting time and adding complexity.
 - **Max 3 `[NEEDS CLARIFICATION]` markers** — more than 3 means the feature idea isn't mature enough to spec. Suggest the user think through the concept further and return, or use `/prizmkit-clarify` to resolve them interactively.
-- **Feature numbers are zero-padded to 3 digits** (e.g., `001`, `012`) — ensures consistent sorting in file explorers and git logs.
+- **Feature numbers are zero-padded to 3 digits** (e.g., `001`, `012`) with a `-MMDD` timestamp suffix — ensures consistent sorting and prevents collisions when multiple sessions run concurrently.
 
 ## Handling Vague Inputs
 

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

@@ -34,7 +34,7 @@ refactor-workflow
 
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
-| 1 | Analyze 代码分析 | `/prizmkit-tool-tech-debt-tracker` + code reading | → `refactor-analysis.md` |
+| 1 | Analyze 代码分析 | Built-in code analysis + code reading | → `refactor-analysis.md` |
 | 2 | Plan 重构方案与任务 | `/prizmkit-plan` | → `plan.md` (含 Tasks section) |
 | 3 | Implement 实现 | `/prizmkit-implement` | (code changes) |
 | 4 | Code Review | `/prizmkit-code-review` | (review report) |
@@ -72,9 +72,11 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
    - Dependencies (incoming and outgoing)
    - Current test coverage
    - Known tech debt (from `.prizm-docs/` TRAPS)
-2. **Invoke `/prizmkit-tool-tech-debt-tracker`** on target area:
-   - Receive: debt items, complexity metrics, code smell patterns
+2. **Perform code analysis** on target area:
+   - Identify code smells: long functions, deep nesting, duplicated logic, excessive coupling
+   - Assess complexity metrics: function length, parameter count, cyclomatic complexity
    - Identify highest-impact refactoring opportunities
+   - Check for TODO/FIXME/HACK comments indicating known debt
 3. **Establish baseline**:
    - Run full test suite — record pass/fail counts
    - Note any pre-existing test failures (isolate from refactor impact)
@@ -185,10 +187,10 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 For single-file refactoring (rename, extract method, <30 lines changed):
 
 ```
-Phase 1 (Analyze) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit)
+Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit)
 ```
 
-Skip Phase 2 (Plan).
+Skip Phase 2's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
 
 **CRITERIA** (ALL must be true):
 - Single file change
@@ -197,8 +199,14 @@ Skip Phase 2 (Plan).
 - No cross-module impact
 - No dependency changes
 
+**Fast Path implementation differs from full path:**
+- Phase 2 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md, without deep architecture research
+- Phase 3 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
+- Single-task refactors typically have just one task in plan.md
+
 **Fast Path still requires:**
 - refactor-analysis.md (lightweight version with baseline)
+- plan.md (simplified, 1-2 tasks)
 - Full test suite run after implementation
 - Code review
 - `refactor(<scope>):` commit convention
@@ -242,7 +250,7 @@ The pipeline supports resuming from the last completed phase by detecting existi
 
 | Skill | Role in Refactor Workflow |
 |-------|--------------------------|
-| `/prizmkit-tool-tech-debt-tracker` | Phase 1: identify debt and complexity |
+| (built-in code analysis) | Phase 1: identify debt and complexity |
 | `/prizmkit-plan` | Phase 2: refactoring plan + task generation |
 | `/prizmkit-implement` | Phase 3: execute refactoring tasks |
 | `/prizmkit-code-review` | Phase 4: review quality and behavior preservation |

package/bundled/team/prizm-dev-team.json

@@ -19,7 +19,7 @@
       "name": "dev",
       "role": "developer",
       "agentDefinition": "prizm-dev-team-dev",
-      "prompt": "You are a Dev Agent of the prizm-dev-team. Follow /prizmkit-implement workflow with TDD. Read tasks.md/plan.md/spec.md, implement task-by-task, mark completed tasks [x]. Check .prizm-docs/ TRAPS before implementing.",
+      "prompt": "You are a Dev Agent of the prizm-dev-team. Follow /prizmkit-implement workflow with TDD. Read plan.md/spec.md, implement task-by-task, mark completed tasks [x]. Check .prizm-docs/ TRAPS before implementing.",
       "subscriptions": ["*"]
     },
     {

package/package.json

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

package/src/scaffold.js

@@ -850,7 +850,7 @@ export async function scaffold(config) {
     console.log('  下一步:');
     console.log(`    1. ${chalk.cyan('cd ' + projectRoot)}`);
     console.log(`    2. ${chalk.cyan(cli)}                          ${chalk.gray('# 启动 AI 对话')}`);
-    console.log(`    3. ${chalk.cyan('说 "prizmkit.init"')}           ${chalk.gray('# 初始化项目上下文')}`);
+    console.log(`    3. ${chalk.cyan('说 "/prizmkit-init"')}           ${chalk.gray('# 初始化项目上下文')}`);
 
     if (pipeline) {
       console.log(`    4. ${chalk.cyan('说 "规划一个应用"')}             ${chalk.gray('# 生成 feature-list.json')}`);