prizmkit 1.0.67 → 1.0.74

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

@@ -1,16 +1,28 @@
 ---
 name: "prizmkit-retrospective"
-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)"
+description: "Incremental .prizm-docs/ and project memory maintainer. Performs three jobs: (1) structural sync — update .prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES into .prizm-docs/, (3) memory sedimentation — sediment DECISIONS/interface conventions to platform memory files (CLAUDE.md or CODEBUDDY.md+memory/MEMORY.md). Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective
 
-**The sole maintainer of `.prizm-docs/` project memory.** No other skill writes to `.prizm-docs/`. This skill performs two distinct jobs in one pass:
+Maintains two distinct knowledge stores with clear separation of concerns:
 
-1. **Structural Sync** — reflect what changed in code (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
-2. **Knowledge Injection** — extract what was learned (TRAPS, RULES, DECISIONS)
+| Store | Location | Content | Purpose |
+|-------|----------|---------|---------|
+| **Architecture Index** | `.prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES | AI quickly locates code structure, interfaces, and known pitfalls |
+| **Project Memory** | `CLAUDE.md` or `CODEBUDDY.md` + `memory/MEMORY.md` | DECISIONS, interface conventions, project-level rules | Decisions and conventions that influence future development direction |
 
-Both jobs are necessary because `.prizm-docs/` exists to help AI understand the project. Structural accuracy tells AI *what exists*; knowledge tells AI *why it exists and what to watch out for*.
+**Reading guide for other skills**:
+- Need to understand code structure/modules/interfaces? → Read `.prizm-docs/`
+- Need to understand past decisions/conventions/why? → Read platform memory file (`CLAUDE.md` for Claude Code, `CODEBUDDY.md` + `memory/MEMORY.md` for CodeBuddy)
+
+**This skill performs three jobs in one pass:**
+
+1. **Structural Sync** — reflect what changed in code → `.prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
+2. **Architecture Knowledge** — inject TRAPS and module-level RULES → `.prizm-docs/`
+3. **Memory Sedimentation** — sediment DECISIONS and interface conventions → platform memory files
+
+No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing development. For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
 
 ## When to Use
 
@@ -69,9 +81,11 @@ git diff --name-status
 
 ---
 
-## Job 2: Knowledge Injection
+## Job 2: Architecture Knowledge Injection → `.prizm-docs/`
 
-Extract what was learned and inject it into the modules where AI will read it. This job has value **only when real development work was done** — not for trivial changes.
+Extract TRAPS and module-level RULES from development work and inject into `.prizm-docs/`. **DECISIONS do NOT go here** — they are sedimented to platform memory files in Job 3.
+
+`.prizm-docs/` is the **architecture index**: it tells AI *what code exists, how it connects, and what pitfalls to avoid*. It does NOT store *why* a design choice was made — that belongs in project memory.
 
 ### When to run Job 2
 
@@ -85,6 +99,7 @@ Extract what was learned and inject it into the modules where AI will read it. T
 **2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
 
 - `git diff HEAD` — the real source of truth for what happened
+- `.prizmkit/specs/###-feature-name/agents/*.md` — **preferred source** for pre-categorized FINDINGS and INTERFACES_DISCOVERED from all agents. If agent docs exist, prefer them over re-extracting from git diff.
 - `.prizmkit/specs/###-feature-name/plan.md` — if feature work, read planned vs actual
 - `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
 - The relevant `.prizm-docs/` L1/L2 docs for affected modules
@@ -99,21 +114,64 @@ Extract what was learned and inject it into the modules where AI will read it. T
 - Format: `- MUST/NEVER/PREFER: <rule>`
 - Source: patterns that proved necessary during implementation
 
-**DECISIONS** — architecture choices made and why:
-- Format: `- [YYYY-MM-DD] <decision and rationale>`
-- Format: `- REJECTED: <approach> — <why it failed>`
-- Source: alternatives tried, design trade-offs made
-
-**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding that prevents mistakes or accelerates work?" If not, discard.
+**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding that prevents mistakes?" If not, discard. DECISIONS (why we chose A over B) belong in project memory, not here.
 
 **2c.** Inject into the correct `.prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected L1 or L2 `.prizm` file
+- Module-level TRAPS/RULES → the affected L1 or L2 `.prizm` file
 - Project-level RULES/PATTERNS → `root.prizm`
 
 **RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
 
 ---
 
+## Job 3: Memory Sedimentation → Platform Memory Files
+
+Sediment DECISIONS and interface conventions to platform memory files. This is where project-level knowledge lives — the "why" behind design choices, cross-module contracts, and conventions that affect future development.
+
+**Project Memory** is distinct from `.prizm-docs/`:
+- `.prizm-docs/` = architecture index (structure, interfaces, traps) — "what exists and what to watch out for"
+- Memory files = development decisions and conventions — "why we chose this approach and what contracts to honor"
+
+### When to run Job 3
+
+- Feature completion with notable DECISIONS or interface conventions discovered
+- **Skip for**: trivial fixes, config changes, bug fixes with no new conventions
+
+### Sedimentation Rules
+
+1. **Max 3-5 entries per feature**: Only keep DECISIONS and interface conventions that genuinely affect future development
+2. **Dedup first**: Before appending, read the target memory file(s). If a similar entry already exists, skip or merge-update it
+3. **TRAPS → `.prizm-docs/` only** (handled by Job 2 above)
+4. **DECISIONS + key interface conventions → platform memory files**
+
+### Steps
+
+**2b-1.** Detect platform from `.prizmkit/config.json` `"platform"` field (or auto-detect from directory structure):
+- `claude` → target: `CLAUDE.md` in project root
+- `codebuddy` → targets: BOTH `CODEBUDDY.md` in project root AND `memory/MEMORY.md` (dual-write required)
+
+**2b-2.** Collect sedimentation candidates:
+- From `agents/*.md`: DECISIONS and INTERFACES_DISCOVERED entries
+- From git diff analysis: any project-level conventions established
+- Filter: only entries that answer "Would a new session benefit from knowing this decision/convention?"
+
+**2b-3.** Read existing memory file(s) content. Check for duplicates or near-duplicates.
+- For Claude Code: read `CLAUDE.md`
+- For CodeBuddy: read BOTH `CODEBUDDY.md` AND `memory/MEMORY.md`
+
+**2b-4.** Append to memory file(s) using this format:
+```markdown
+### F-XXX: <feature-title>
+- DECISION: <decision content> — <rationale>
+- INTERFACE: <module.function>: <convention>
+```
+
+**2b-5.** For CodeBuddy platform: write identical content to BOTH `CODEBUDDY.md` AND `memory/MEMORY.md` (dual-write, both must be updated).
+
+**2b-6.** If no `agents/` directory exists in the feature directory, still attempt to extract DECISIONS from git diff and plan.md. Skip only if no meaningful decisions were made.
+
+---
+
 ## Final: Changelog + Stage
 
 **3a.** Append to `.prizm-docs/changelog.prizm`:
@@ -136,7 +194,7 @@ git add .prizm-docs/
 In the dev-pipeline, this skill is the **single doc maintenance step** before commit:
 
 ```
-implement → code-review → retrospective (memory maintenance) → committer (pure commit)
+implement → code-review → retrospective (architecture sync + memory sedimentation) → committer (pure commit)
 ```
 
 The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show changes in the final commit. This skill is the sole satisfier of that requirement.
@@ -146,11 +204,14 @@ The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show change
 | From | To | Condition |
 |------|----|-----------|
 | `prizmkit-code-review` | **this skill** | Review passes or work is complete |
-| **this skill** | `prizmkit-committer` | Memory maintained, ready to commit |
+| **this skill** | `prizmkit-committer` | Architecture synced + memory sedimented, ready to commit |
 | `prizmkit-committer` | — | Committed |
 
 ## Output
 
-- `.prizm-docs/*.prizm` — Structurally synced + knowledge enriched
+- `.prizm-docs/*.prizm` — Structurally synced + TRAPS/RULES enriched (architecture index)
 - `.prizm-docs/changelog.prizm` — Appended entries
-- All changes staged via `git add .prizm-docs/`
+- Platform memory file(s) — DECISIONS + interface conventions sedimented (project memory)
+  - Claude Code: `CLAUDE.md`
+  - CodeBuddy: BOTH `CODEBUDDY.md` AND `memory/MEMORY.md`
+- All `.prizm-docs/` changes staged via `git add .prizm-docs/`

package/bundled/skills/prizmkit-tool-adr-manager/SKILL.md

@@ -25,7 +25,7 @@ Create a new Architecture Decision Record.
    - **Consequences**: Identify positive and negative consequences
    - **Alternatives considered**: Ask user about alternatives and why they were rejected
 3. Write to `docs/adr/NNNN-title.md` (zero-padded number, kebab-case title)
-4. Also record in `.prizm-docs/` DECISIONS section of relevant module doc
+4. Record in platform memory file (`CLAUDE.md` for Claude Code, BOTH `CODEBUDDY.md` AND `memory/MEMORY.md` for CodeBuddy) as a DECISION entry
 
 ### `/prizmkit-adr`.list
 
@@ -64,4 +64,4 @@ All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compa
 ## Output
 
 - ADR files in `docs/adr/` directory
-- Updated DECISIONS section in relevant `.prizm-docs/` module doc
+- Updated DECISIONS in platform memory file (`CLAUDE.md` or `CODEBUDDY.md` + `memory/MEMORY.md`)

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

@@ -1,7 +1,7 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', '重构', '优化代码结构', '代码重构'. (project)"
+description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
@@ -9,7 +9,7 @@ description: "End-to-end refactor workflow: analyze → plan → implement → r
 End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 5-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ### When to Use
-- User says "refactor", "clean up code", "restructure", "extract module", "重构", "优化代码结构"
+- User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
 - Code has accumulated tech debt that needs structural improvement
 - Module needs to be split, merged, or reorganized
 - When behavior must remain unchanged but internal quality needs improvement
@@ -34,9 +34,9 @@ refactor-workflow
 
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
-| 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) |
+| 1 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
+| 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
+| 3 | Implement | `/prizmkit-implement` | (code changes) |
 | 4 | Code Review | `/prizmkit-code-review` | (review report) |
 | 5 | Commit | `/prizmkit-committer` | git commit |
 
@@ -56,12 +56,12 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 **INPUT**: Target description. Can be:
 - Module or file path (e.g., "src/auth/")
-- Natural language description (e.g., "重构认证模块，提取公共逻辑")
+- Natural language description (e.g., "refactor the auth module, extract shared logic")
 - Specific refactoring goal (e.g., "extract payment processing into separate service")
 
 ---
 
-## Phase 1: Analyze — 代码分析
+## Phase 1: Analyze — Code Analysis
 
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
 
@@ -93,7 +93,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 2: Plan — 重构方案与任务
+## Phase 2: Plan — Refactor Plan & Tasks
 
 **Goal**: Generate technical refactoring plan that preserves behavior, including task breakdown.
 
@@ -115,7 +115,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 3: Implement — 实现
+## Phase 3: Implement
 
 **Goal**: Execute refactoring tasks with mandatory test verification after each task.
 
@@ -140,7 +140,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 4: Code Review — 代码审查
+## Phase 4: Code Review
 
 **Goal**: Verify refactoring quality and behavior preservation.
 
@@ -162,7 +162,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 5: Commit — 提交
+## Phase 5: Commit
 
 **Goal**: Commit with refactor convention.
 
@@ -182,7 +182,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Fast Path — 快速路径
+## Fast Path
 
 For single-file refactoring (rename, extract method, <30 lines changed):
 
@@ -213,7 +213,7 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 
 ---
 
-## Resume — 中断恢复
+## Resume — Interruption Recovery
 
 The pipeline supports resuming from the last completed phase by detecting existing artifacts.
 

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

@@ -6,7 +6,7 @@
   "communication": {
     "protocol": "SendMessage",
     "routing": "mesh",
-    "note": "Teammates 间通过 SendMessage 直接通信，关键消息同时通知 Orchestrator"
+    "note": "Teammates communicate directly via SendMessage; key messages must also be sent to Orchestrator"
   },
   "members": [
     {

package/package.json

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

package/src/upgrade.js

@@ -213,13 +213,25 @@ export async function runUpgrade(directory, options = {}) {
   }
 
   // 3. Resolve new skill list using old manifest's suite + platform (or defaults)
-  const platform = oldManifest?.platform || 'claude';
+  const oldManifestPlatform = oldManifest?.platform || 'claude';
   const suite = oldManifest?.suite || 'full';
   const team = oldManifest?.options?.team ?? true;
   const pipeline = oldManifest?.options?.pipeline ?? true;
   const rulesPreset = oldManifest?.options?.rules || 'recommended';
   const aiCli = userConfig.ai_cli || oldManifest?.options?.aiCli || '';
 
+  // Filesystem-based platform detection (overrides manifest if dirs exist)
+  const hasClaude = await fs.pathExists(path.join(projectRoot, '.claude', 'commands'))
+                    || await fs.pathExists(path.join(projectRoot, '.claude', 'agents'));
+  const hasCodeBuddy = await fs.pathExists(path.join(projectRoot, '.codebuddy', 'skills'))
+                       || await fs.pathExists(path.join(projectRoot, '.codebuddy', 'agents'));
+
+  let platform;
+  if (hasClaude && hasCodeBuddy) platform = 'both';
+  else if (hasCodeBuddy) platform = 'codebuddy';
+  else if (hasClaude) platform = 'claude';
+  else platform = oldManifestPlatform; // fallback to manifest
+
   const newSkillList = await resolveSkillList(suite);
   const agentsDir = getAgentsDir();
   const newAgentFiles = (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'));
@@ -255,7 +267,7 @@ export async function runUpgrade(directory, options = {}) {
   const oldVersion = oldManifest?.version || 'unknown';
   console.log(chalk.bold('  Upgrade Summary:'));
   console.log(`    Version: ${chalk.gray(oldVersion)} → ${chalk.cyan(pkg.version)}`);
-  console.log(`    Platform: ${platform}`);
+  console.log(`    Platform: ${platform}${platform !== oldManifestPlatform ? chalk.yellow(` (detected from filesystem, manifest had: ${oldManifestPlatform})`) : ''}`);
   console.log(`    Suite: ${suite}`);
   console.log('');