prizmkit 1.0.3 → 1.0.5

package/bundled/dev-pipeline/scripts/utils.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Shared utility functions for dev-pipeline scripts.
+
+Centralizes common operations (JSON I/O, error reporting, display helpers)
+to avoid duplication across pipeline scripts.
+"""
+
+import json
+import os
+import sys
+
+
+def load_json_file(path):
+    """Load and return parsed JSON from a file.
+
+    Returns (data, error_string). On success error_string is None.
+    """
+    abs_path = os.path.abspath(path)
+    if not os.path.isfile(abs_path):
+        return None, "File not found: {}".format(abs_path)
+    try:
+        with open(abs_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        return None, "Invalid JSON: {}".format(str(e))
+    except IOError as e:
+        return None, "Cannot read file: {}".format(str(e))
+    return data, None
+
+
+def write_json_file(path, data):
+    """Write data as JSON to a file. Creates parent directories if needed.
+
+    Returns an error string on failure, None on success.
+    """
+    abs_path = os.path.abspath(path)
+    parent = os.path.dirname(abs_path)
+    if parent and not os.path.isdir(parent):
+        try:
+            os.makedirs(parent, exist_ok=True)
+        except OSError as e:
+            return "Cannot create directory: {}".format(str(e))
+    try:
+        with open(abs_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+    except IOError as e:
+        return "Cannot write file: {}".format(str(e))
+    return None
+
+
+def error_out(message, code=1):
+    """Print an error JSON and exit with the given code."""
+    output = {"error": message}
+    print(json.dumps(output, indent=2, ensure_ascii=False))
+    sys.exit(code)
+
+
+def pad_right(text, width):
+    """Pad text with spaces to fill width, accounting for ANSI escape codes."""
+    i = 0
+    visible_len = 0
+    while i < len(text):
+        if text[i] == "\033":
+            while i < len(text) and text[i] != "m":
+                i += 1
+            i += 1
+        else:
+            visible_len += 1
+            i += 1
+    padding = width - visible_len
+    if padding > 0:
+        return text + " " * padding
+    return text
+
+
+def _build_progress_bar(percent, width=20):
+    """Build a text progress bar.
+
+    Example: ████████░░░░░░░░░░░░ 40%
+    """
+    filled = int(width * percent / 100)
+    empty = width - filled
+    bar = "\u2588" * filled + "\u2591" * empty
+    return "{} {:>3}%".format(bar, int(percent))

package/bundled/skills/_metadata.json

@@ -197,6 +197,20 @@
       "hasAssets": false,
       "hasScripts": false
     },
+    "feature-workflow": {
+      "description": "End-to-end feature workflow: specify → plan → tasks → analyze → implement → review → commit.",
+      "tier": "1",
+      "category": "pipeline",
+      "hasAssets": false,
+      "hasScripts": false
+    },
+    "refactor-workflow": {
+      "description": "End-to-end refactor workflow: analyze → plan → tasks → implement → review → commit. Behavior-preserving.",
+      "tier": "1",
+      "category": "pipeline",
+      "hasAssets": false,
+      "hasScripts": false
+    },
     "bug-planner": {
       "description": "Interactive bug planning that produces bug-fix-list.json. Supports stack traces, user reports, failed tests, log patterns, monitoring alerts.",
       "tier": "companion",
@@ -228,11 +242,11 @@
   },
   "suites": {
     "full": {
-      "description": "All 32 skills",
+      "description": "All 34 skills",
       "skills": "*"
     },
     "core": {
-      "description": "Core Tier 1 skills (15 skills)",
+      "description": "Core Tier 1 skills (17 skills)",
       "skills": [
         "prizm-kit",
         "prizmkit-init",
@@ -248,7 +262,9 @@
         "prizmkit-retrospective",
         "prizmkit-prizm-docs",
         "prizmkit-tech-debt-tracker",
-        "prizmkit-bug-fix-workflow"
+        "prizmkit-bug-fix-workflow",
+        "feature-workflow",
+        "refactor-workflow"
       ]
     },
     "minimal": {

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

@@ -0,0 +1,317 @@
+---
+name: "feature-workflow"
+tier: 1
+description: "[Tier 1] End-to-end feature workflow: specify → plan → tasks → analyze → implement → review → commit. 7-phase pipeline with resume support and fast path for simple changes. (project)"
+---
+
+# PrizmKit Feature Workflow
+
+End-to-end orchestration skill for new features. Chains existing PrizmKit skills (specify, plan, tasks, analyze, implement, code-review, committer, summarize) into a 7-phase pipeline with standardized artifacts and resume support.
+
+## Overview
+
+```
+prizmkit.feature <需求描述>
+  → Phase 1: Specify   → spec.md
+  → Phase 2: Plan      → plan.md
+  → Phase 3: Tasks     → tasks.md
+  → Phase 4: Analyze   → (consistency report)
+  → Phase 5: Implement → (code)
+  → Phase 6: Review    → (review report)
+  → Phase 7: Commit    → git commit + REGISTRY
+```
+
+### Pipeline Phases
+
+| Phase | Name | Skill Used | Artifact |
+|-------|------|-----------|----------|
+| 1 | Specify 需求规格 | `prizmkit.specify` | → `spec.md` |
+| 2 | Plan 技术方案 | `prizmkit.plan` | → `plan.md` |
+| 3 | Tasks 任务拆解 | `prizmkit.tasks` | → `tasks.md` |
+| 4 | Analyze 一致性检查 | `prizmkit.analyze` | (quality report) |
+| 5 | Implement 实现 | `prizmkit.implement` | (code changes) |
+| 6 | Code Review | `prizmkit.code-review` | (review report) |
+| 7 | Commit & Archive | `prizmkit.committer` + `prizmkit.summarize` | git commit + REGISTRY |
+
+### Artifacts
+
+Standard feature artifacts stored at `.prizmkit/specs/<feature-slug>/`:
+- **`spec.md`** — Feature specification (Phase 1)
+- **`plan.md`** — Technical implementation plan (Phase 2)
+- **`tasks.md`** — Executable task breakdown (Phase 3)
+
+## Commands
+
+### prizmkit.feature \<需求描述\>
+
+Execute the full feature pipeline from natural language description to committed code.
+
+**INPUT**: Natural language feature description. Can be:
+- A brief one-liner (e.g., "添加用户头像上传功能")
+- A detailed requirement paragraph
+- A reference to an existing spec file
+
+---
+
+## Phase 1: Specify — 需求规格
+
+**Goal**: Transform natural language into structured feature specification.
+
+**STEPS:**
+
+1. **Parse feature description**: Extract:
+   - Core functionality requested
+   - User-facing behavior expectations
+   - Implicit constraints and edge cases
+   - Affected modules (from `.prizm-docs/`)
+
+2. **Invoke `prizmkit.specify`** with the feature description:
+   - Receive structured `spec.md` with user stories, acceptance criteria, scope
+   - Artifact path: `.prizmkit/specs/<feature-slug>/spec.md`
+
+3. **Validate spec completeness**:
+   - All acceptance criteria are testable
+   - Scope boundaries are clear
+   - No ambiguous requirements remain
+
+**CHECKPOINT CP-FW-1**: `spec.md` exists and is well-formed.
+
+---
+
+## Phase 2: Plan — 技术方案
+
+**Goal**: Generate technical implementation plan from the specification.
+
+**STEPS:**
+
+1. **Read context**: spec.md, `.prizm-docs/` (PATTERNS, RULES, TRAPS)
+
+2. **Invoke `prizmkit.plan`** with spec.md:
+   - Receive `plan.md` with architecture decisions, file changes, dependencies
+   - Artifact path: `.prizmkit/specs/<feature-slug>/plan.md`
+
+3. **Verify plan alignment**:
+   - Plan addresses all spec acceptance criteria
+   - No out-of-scope changes
+   - Dependencies are identified
+
+**CHECKPOINT CP-FW-2**: `plan.md` exists and aligns with spec.md.
+
+---
+
+## Phase 3: Tasks — 任务拆解
+
+**Goal**: Break implementation plan into executable, ordered tasks.
+
+**STEPS:**
+
+1. **Invoke `prizmkit.tasks`** with plan.md:
+   - Receive `tasks.md` with ordered task list, dependencies, estimated scope
+   - Artifact path: `.prizmkit/specs/<feature-slug>/tasks.md`
+
+2. **Verify task coverage**:
+   - Every plan item maps to at least one task
+   - Tasks include test tasks (not just implementation)
+   - Task order respects dependencies
+
+**CHECKPOINT CP-FW-3**: `tasks.md` exists with complete task coverage.
+
+---
+
+## Phase 4: Analyze — 一致性检查
+
+**Goal**: Cross-document consistency analysis before implementation begins.
+
+**STEPS:**
+
+1. **Invoke `prizmkit.analyze`** with spec.md, plan.md, tasks.md:
+   - Check spec ↔ plan alignment
+   - Check plan ↔ tasks coverage
+   - Check for contradictions or gaps
+   - Verify naming consistency
+
+2. **Handle analysis results**:
+   - **PASS**: Proceed to Phase 5
+   - **WARNINGS**: Log warnings, proceed to Phase 5
+   - **ERRORS**: Return to the earliest affected phase to fix inconsistencies
+
+**CHECKPOINT CP-FW-4**: Analysis passes (no blocking errors).
+
+---
+
+## Phase 5: Implement — 实现
+
+**Goal**: Execute tasks.md with TDD approach.
+
+**STEPS:**
+
+1. **Invoke `prizmkit.implement`**:
+   - Follow tasks.md order
+   - TDD: write tests first, then implementation
+   - Run tests after each task completion
+
+2. **Progress tracking**:
+   - Mark tasks complete in tasks.md as they finish
+   - If a task fails after 3 attempts → escalate to user
+
+3. **Local verification**:
+   - All new tests pass
+   - All existing tests pass (no regression)
+
+**CHECKPOINT CP-FW-5**: All tasks complete, all tests green.
+
+---
+
+## Phase 6: Code Review — 代码审查
+
+**Goal**: Ensure implementation quality and spec compliance.
+
+**STEPS:**
+
+1. **Invoke `prizmkit.code-review`** (scoped to changed files):
+   - Review dimensions:
+     - **Spec compliance**: Does implementation match all acceptance criteria?
+     - **Plan adherence**: Does code follow the technical plan?
+     - **Code quality**: Clean, maintainable, follows project conventions?
+     - **Test coverage**: Are all acceptance criteria tested?
+   - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
+
+2. **Handle review results**:
+   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 7
+   - **NEEDS_FIXES**: Return to Phase 5 (max 2 review rounds)
+
+**CHECKPOINT CP-FW-6**: Code review passes.
+
+---
+
+## Phase 7: Commit & Archive — 提交与归档
+
+**Goal**: Commit with proper conventions, archive to REGISTRY.
+
+**STEPS:**
+
+1. **Invoke `prizmkit.committer`**:
+   - Commit message: `feat(<scope>): <description>`
+   - Include all implementation code + tests
+   - Do NOT push
+
+2. **Invoke `prizmkit.summarize`**:
+   - Archive feature to REGISTRY.md
+   - Include: feature slug, description, files changed, date
+
+3. **Update `.prizm-docs/`** if needed:
+   - New PATTERNS discovered during implementation
+   - New TRAPS encountered
+   - Updated module documentation
+
+**CHECKPOINT CP-FW-7**: Commit recorded, REGISTRY updated.
+
+---
+
+## Fast Path — 快速路径
+
+For simple features (single file, <50 lines, no cross-module impact):
+
+```
+Phase 2 (Plan) → Phase 3 (Tasks) → Phase 5 (Implement) → Phase 6 (Review) → Phase 7 (Commit)
+```
+
+Skip Phase 1 (Specify) and Phase 4 (Analyze).
+
+**CRITERIA** (ALL must be true):
+- Single file change or tightly scoped to one module
+- Estimated change < 50 lines
+- No cross-module dependencies or side effects
+- No new user-facing API surface
+- Clear and unambiguous requirement
+
+**Fast Path still requires:**
+- plan.md and tasks.md (lightweight versions)
+- Code review
+- `feat(<scope>):` commit convention
+- REGISTRY update via summarize
+
+---
+
+## Resume — 中断恢复
+
+The pipeline supports resuming from the last completed phase by detecting existing artifacts.
+
+**Detection logic**: Check `.prizmkit/specs/<slug>/` for:
+
+| Artifact Found | Resume From |
+|---------------|------------|
+| (nothing) | Phase 1: Specify |
+| `spec.md` only | Phase 2: Plan |
+| `spec.md` + `plan.md` | Phase 3: Tasks |
+| `spec.md` + `plan.md` + `tasks.md` | Phase 4: Analyze |
+| All 3 docs + analysis passed | Phase 5: Implement |
+| All 3 docs + code changes exist | Phase 6: Review |
+| All 3 docs + review passed | Phase 7: Commit |
+
+**Resume command**: `prizmkit.feature <slug>` — if `<slug>` matches an existing `.prizmkit/specs/<slug>/` directory, resume instead of starting fresh.
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Cannot parse feature description | Ask user for clarification |
+| Spec has ambiguous requirements | Invoke `prizmkit.clarify` before proceeding |
+| Plan-spec misalignment detected | Return to Phase 2 with feedback |
+| Analyze finds blocking errors | Return to earliest affected phase |
+| Implementation fails after 3 rounds | Escalate to user with analysis |
+| Review fails after 2 rounds | Escalate with review findings |
+| Full test suite has pre-existing failures | Warn user, isolate feature tests |
+| Feature requires breaking changes | STOP, recommend ADR via `prizmkit.adr-manager` |
+
+---
+
+## Relationship to Other Skills
+
+| Skill | Role in Feature Workflow |
+|-------|------------------------|
+| `prizmkit-specify` | Phase 1: structured spec generation |
+| `prizmkit-clarify` | Phase 1 fallback: resolve ambiguities |
+| `prizmkit-plan` | Phase 2: technical implementation plan |
+| `prizmkit-tasks` | Phase 3: task breakdown |
+| `prizmkit-analyze` | Phase 4: cross-document consistency |
+| `prizmkit-implement` | Phase 5: TDD implementation |
+| `prizmkit-code-review` | Phase 6: review and quality gate |
+| `prizmkit-committer` | Phase 7: commit with `feat()` convention |
+| `prizmkit-summarize` | Phase 7: archive to REGISTRY |
+| `prizmkit-retrospective` | Optional: post-feature lessons learned |
+| `prizmkit-bug-fix-workflow` | NOT used (separate pipeline for bugs) |
+| `app-planner` | Pre-pipeline: interactive feature planning |
+
+---
+
+## Comparison with Bug Fix Pipeline
+
+| Dimension | Feature Workflow | Bug Fix Pipeline |
+|-----------|-----------------|-----------------|
+| Input | Natural language requirement | Bug description / stack trace |
+| Pipeline Phases | 7 (Fast Path: 5) | 5 (Fast Path: 3) |
+| Artifact Docs | 3: spec.md + plan.md + tasks.md | 2: fix-plan.md + fix-report.md |
+| Artifact Path | `.prizmkit/specs/<feature-slug>/` | `.prizmkit/bugfix/<bug-id>/` |
+| Skills Chain | specify → plan → tasks → analyze → implement → review → commit + summarize | error-triage → bug-reproduce → implement → code-review → commit |
+| Commit Prefix | `feat(<scope>):` | `fix(<scope>):` |
+| REGISTRY Update | ✅ via summarize | ❌ not applicable |
+| Resume Support | ✅ artifact-based detection | ❌ |
+
+## Path References
+
+All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
+## Output
+
+- `spec.md` (Phase 1 artifact)
+- `plan.md` (Phase 2 artifact)
+- `tasks.md` (Phase 3 artifact)
+- Consistency analysis report (Phase 4, conversation only)
+- Implementation code + tests (Phase 5)
+- Code review report (Phase 6, conversation only)
+- Git commit with `feat(<scope>):` prefix (Phase 7)
+- REGISTRY.md entry (Phase 7)
+- Updated `.prizm-docs/` (if applicable)

package/bundled/skills/prizm-kit/SKILL.md

@@ -70,7 +70,7 @@ PrizmKit produces two complementary knowledge layers:
 .prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → tasks → code)
 ```
 
-## Skill Inventory (32 skills)
+## Skill Inventory (34 skills)
 
 ### Foundation (3)
 - **prizm-kit** — Full-lifecycle dev toolkit entry point
@@ -80,7 +80,7 @@ PrizmKit produces two complementary knowledge layers:
 ### Spec-Driven Workflow (10)
 - **prizmkit-specify** — Create structured feature specifications from natural language
 - **prizmkit-clarify** — Interactive requirement clarification
-- **prizmkit-plan** — Generate technical plan + data model + API contracts
+- **prizmkit-plan** — Generate technical plan (with data model & API contracts as inline sections)
 - **prizmkit-tasks** — Break plan into executable task list
 - **prizmkit-analyze** — Cross-document consistency analysis (spec ↔ plan ↔ tasks)
 - **prizmkit-implement** — Execute tasks following TDD approach
@@ -111,8 +111,10 @@ PrizmKit produces two complementary knowledge layers:
 - **prizmkit-onboarding-generator** — [Tier 2] Generate developer onboarding guides
 - **prizmkit-api-doc-generator** — [Tier 2] Extract API documentation from source code
 
-### Pipeline & Companion (5)
+### Pipeline & Companion (7)
 - **prizmkit-bug-fix-workflow** — [Tier 1] End-to-end bug fix workflow: triage → reproduce → fix → verify → commit
+- **feature-workflow** — [Tier 1] End-to-end feature workflow: specify → plan → tasks → analyze → implement → review → commit
+- **refactor-workflow** — [Tier 1] End-to-end refactor workflow: analyze → plan → tasks → implement → review → commit
 - **app-planner** — Interactive app planning that produces feature-list.json for dev-pipeline
 - **bug-planner** — Interactive bug planning that produces bug-fix-list.json for bugfix-pipeline
 - **dev-pipeline-launcher** — Launch and manage the dev-pipeline from within a CLI session

package/bundled/skills/prizm-kit/assets/hooks/prizm-commit-hook.json

@@ -2,12 +2,12 @@
   "hooks": {
     "UserPromptSubmit": [
       {
-        "matcher": "(?i)\\b(commit|push|finish|ship|merge|pull request|pr)\\b|提交|推送|收尾|完成任务|合并|发版|发布",
+        "matcher": "\\b(commit|Commit|push|Push|finish|Finish|ship|Ship|merge|Merge|pull request|Pull Request|pr|PR)\\b|提交|推送|收尾|完成任务|合并|发版|发布",
         "hooks": [
           {
             "type": "prompt",
             "prompt": "You are a commit-intent detector for PrizmKit. Analyze the user prompt and determine if the user intends to COMMIT, PUSH, FINISH, SHIP, MERGE, or create a PULL REQUEST.\n\nUser prompt: $ARGUMENTS\n\nIF commit intent detected, respond with:\n{\"ok\": true, \"reason\": \"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.\"}\n\nIF no commit intent, respond with:\n{\"ok\": true}\n\nRespond with JSON only. No explanation.",
-            "timeout": 10
+            "timeout": 300
           }
         ]
       }

package/bundled/skills/prizmkit-bug-fix-workflow/SKILL.md

@@ -325,7 +325,7 @@ When `affected_feature` is non-empty:
 | Input Skill | `app-planner` (7-phase interactive) | `bug-planner` (multi-format parser) |
 | Input File | `feature-list.json` (F-NNN) | `bug-fix-list.json` (B-NNN) |
 | Schema Version | `dev-pipeline-feature-list-v1` | `dev-pipeline-bug-fix-list-v1` |
-| Pipeline Phases | 10 Phase (0-7 + init + cleanup) | 5 Phase (Fast Path: 3) |
+| Pipeline Phases | 7 Phase (Fast Path: 5) | 5 Phase (Fast Path: 3) |
 | Artifact Docs | 3: spec.md + plan.md + tasks.md | 2: fix-plan.md + fix-report.md |
 | Artifact Path | `.prizmkit/specs/<feature-slug>/` | `.prizmkit/bugfix/<bug-id>/` |
 | Prompt Template | `bootstrap-prompt.md` | `bugfix-bootstrap-prompt.md` |

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

@@ -87,8 +87,25 @@ python3 ${SKILL_DIR}/scripts/manage_changelog.py add --type <type> --message "<d
 ```
 
 #### Step 5: Git Commit
+
+5a. Safety check before staging:
+```bash
+git diff --name-only
+git ls-files --others --exclude-standard
+```
+Review the output for sensitive files. If any file matches these patterns, **STOP and warn the user**:
+- `.env`, `.env.*`
+- `*.key`, `*.pem`, `*.p12`
+- `credentials.*`, `*secret*`
+- `*.sqlite`, `*.db` (database files)
+
+5b. Stage and commit:
+```bash
+git add -A
+git diff --cached --name-only
+```
+Review staged file list one final time, then:
 ```bash
-git add .
 git commit -m "<type>(<scope>): <description>"
 ```
 Follow Conventional Commits format.
@@ -104,7 +121,7 @@ Then verify working tree is clean:
 git status
 ```
 - If "nothing to commit, working tree clean": commit verified successfully, proceed
-- If there are uncommitted changes remaining: **STOP** and report error — all changes must be captured in the commit. Run `git add . && git commit --amend --no-edit` to include missed files, then re-verify
+- If there are uncommitted changes remaining: **STOP** and report error — all changes must be captured in the commit. Run `git add -A && git commit --amend --no-edit` to include missed files, then re-verify
 
 #### Step 7: Optional Push
 Ask user: "Push to remote?"
@@ -112,6 +129,7 @@ Ask user: "Push to remote?"
 - No: Stop
 
 ### Error Handling
-- If git diff is empty but untracked files exist: run `git add -N .` first
+- If git diff is empty but untracked files exist: run `git add -N .` first (respects .gitignore)
 - If CHANGELOG.md script fails: update manually or ask user
 - If .prizm-docs/ doesn't exist: skip Step 2 entirely (project not initialized)
+- If sensitive files are detected during Step 5a safety check: warn user and do NOT stage them automatically

package/bundled/skills/prizmkit-prizm-docs/assets/PRIZM-SPEC.md

@@ -684,7 +684,7 @@ JSON:
           {
             "type": "prompt",
             "prompt": "You are a commit-intent detector for the Prizm documentation framework. Analyze the user prompt and determine if the user intends to COMMIT, PUSH, FINISH, SHIP, MERGE, or create a PULL REQUEST.\n\nUser prompt: $ARGUMENTS\n\nIF commit intent detected, respond with:\n{\"ok\": true, \"reason\": \"PRIZM_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/. 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. 6) Then commit. RULES: Never rewrite entire files. Never add prose. Only update affected sections.\"}\n\nIF no commit intent, respond with:\n{\"ok\": true}\n\nJSON only.",
-            "timeout": 10
+            "timeout": 300
           }
         ]
       }