prizmkit 1.1.78 → 1.1.80

package/bundled/skills-windows/prizmkit-deploy/references/ssh-bootstrap-flow.md

@@ -0,0 +1,49 @@
+# SSH Bootstrap Flow
+
+Bootstraps the server before first deployment. Present a plan showing every privileged action before executing anything.
+
+## Always-Run Preflight
+
+```
+locale-gen en_US.UTF-8           # fix locale warnings on bare Ubuntu
+apt-get update -qq               # refresh package list
+```
+
+## Check-and-Install (idempotent)
+
+Node.js, npm, PM2, Nginx, Git. Use v22 LTS if v25 not available.
+
+## Detect Port Conflicts
+
+`ss -tlnp | grep :80 || true`. If port 80/443 is occupied, report and ask how to resolve.
+
+## User and Directory Setup
+
+```
+useradd -m -s /bin/bash <runtimeUser>   # if not exists
+mkdir -p /var/www/<project>/{releases,shared,deploy-logs}
+chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
+```
+
+## PM2 Startup
+
+```
+env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
+```
+
+## Deploy Key (Pull mode only)
+
+```
+sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
+sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+```
+
+## Security Baseline (Firewall)
+
+After core tools are installed, ask whether to configure ufw. If user agrees, read `references/firewall-setup.md` for the full interactive flow and rule templates.
+
+## Database Setup
+
+If Discovery detected database drivers, ask whether to install the database on the server. If user agrees, read `references/database-setup.md` for platform-specific setup commands and security notes.
+
+After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.

package/bundled/skills-windows/prizmkit-deploy/references/ssh-execution-flow.md

@@ -0,0 +1,41 @@
+# SSH: Deployment Execution Flow
+
+Pipeline runs in strict order. Each group must complete before the next begins. If any step before traffic switch fails, STOP — do not touch the live version.
+
+## Pre-flight — Change Summary
+
+Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD`. If first deployment, show last 5 commits. If no new commits, warn "没有新的代码变更。确定要重新部署吗？"
+
+## Group 1 — Pre-flight & Prepare
+
+- Verify SSH, runtime user, tools, deploy key, port availability.
+- Generate `releaseId`: `YYYYMMDD-<short-commit-sha>`. Create `releases/<releaseId>`.
+- Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
+
+## Group 2 — Fetch & Build
+
+- **CI/CD Pull mode** (server-side build): git clone → install → copy `.env.production` before build (NEXT_PUBLIC_* vars are baked at build time) → build. If build fails: STOP.
+- **CI/CD Push mode** (runner-side build): extract tarball, skip install/build.
+- **Direct-upload mode**: build was already done locally and SCP'd. Skip this group.
+
+## Group 3 — Stage & Health Check
+
+- Start new version on inactive port via PM2: `pm2 start npm --name <project>-<app>-<color> -- run start -- -p <inactivePort>`.
+- PM2 process naming: `<project>-<app>-<color>` (e.g., `prizm-ideas-web-green`).
+- Wait 3-5 seconds, run health checks against new port. If any fails: STOP, do NOT switch traffic.
+
+## Group 4 — Switch & Verify
+
+- Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
+- `systemctl reload nginx`. Update `current` symlink to new release.
+- Write `shared/deploy-metadata.json` with new `activeColor`, `activePort`, `lastReleaseId`.
+- Run health checks against public endpoint. If any fails: rollback immediately.
+
+## Group 5 — Cleanup & Record
+
+- Stop old PM2 process. Remove oldest releases beyond `releaseRetention` count. `pm2 save`.
+- Write deploy-history JSON. Update `deploy.config.json` validation status.
+
+## Post-deploy — Completion Summary
+
+Output a summary (project, URL, version, duration, health status) and append to deploy.md. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).

package/bundled/skills-windows/prizmkit-deploy/references/ssh-takeover.md

@@ -0,0 +1,20 @@
+# SSH: Existing Deployment Takeover
+
+When deploying to a server that already has deployment assets.
+
+## Detection
+
+1. Check for existing `/var/www/<project>` directory
+2. Check for existing PM2 processes with similar names
+3. Check Nginx config referencing the same domain/IP
+4. Check for port conflicts
+
+## Decision Flow
+
+Report findings and ask for takeover decision:
+
+- **Take over and backup**: Back up existing config, then proceed.
+- **Coexist**: Use different directory/ports/process names.
+- **Manual resolve**: Stop and let the user handle it.
+
+Record takeover decision and validation results in config and history.

package/bundled/skills-windows/prizmkit-deploy/references/ssl-setup.md

@@ -0,0 +1,56 @@
+# SSL/HTTPS Configuration (Let's Encrypt + Certbot)
+
+Read this file when DNS is confirmed pointing to the server and SSL needs to be configured.
+
+## Step 1 — Detect cloud vendor
+
+```
+# Try metadata endpoints to detect cloud vendor
+curl -s --connect-timeout 2 http://100.100.100.200/latest/meta-data/ && echo "ALIBABA"
+curl -s --connect-timeout 2 http://metadata.tencentyun.com/latest/meta-data/ && echo "TENCENT"
+curl -s --connect-timeout 2 http://169.254.169.254/latest/meta-data/ && echo "AWS/GCP/AZURE"
+```
+Also check `/etc/hostname` for vendor patterns.
+
+## Step 2 — Choose SSL strategy
+
+- **Cloud vendor detected** → ask user:
+  > "检测到服务器运行在 <云厂商>。用哪种 SSL 方案？"
+  > - **A. Let's Encrypt 免费证书（推荐）** — 一行命令永久自动续期，最省心
+  > - **B. <云厂商> 自有证书** — 需手动下载配置，1年有效期需手动续期
+  >
+  > 选 A 我直接帮你搞定；选 B 你需要在云控制台下载证书后告诉我路径。
+- **No cloud vendor / unknown** → use certbot directly, no choice needed.
+
+## Step 3 — Certbot install & certificate request
+
+```
+# Install certbot (idempotent)
+which certbot || apt-get install -y certbot python3-certbot-nginx
+
+# Request certificate
+certbot --nginx -d <domain> -d www.<domain> --non-interactive --agree-tos --email <user-email>
+```
+
+**Collect from user before running:**
+- Email address (Let's Encrypt expiry notifications)
+- Confirm domain list (e.g., `example.com, www.example.com`)
+
+## Step 4 — Verify auto-renewal
+
+```
+systemctl status certbot.timer
+certbot renew --dry-run
+```
+If timer is inactive, enable it: `systemctl enable --now certbot.timer`.
+
+## Step 5 — Record
+
+- Write SSL configuration summary to deploy.md: certificate paths, auto-renewal status, expiry date.
+- Record a `"ssl-setup"` event in deploy history.
+
+## Edge cases
+
+- **DNS not yet propagated** → certbot challenge fails. Tell user to wait and retry: `/prizmkit-deploy setup-ssl`.
+- **Existing certificate found** → check expiry date (`certbot certificates`). If expiring within 30 days, warn. Otherwise skip.
+- **Port 80/443 occupied by non-Nginx process** → report and ask how to resolve before proceeding.

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

@@ -0,0 +1,71 @@
+---
+name: "prizmkit-implement"
+description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+---
+
+# PrizmKit Implement
+
+### When to Use
+- After `/prizmkit-plan` when ready to write code
+- User says "implement", "build", "code it", "start coding", "develop"
+- For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
+
+### When NOT to Use
+- No plan.md exists — run /prizmkit-plan first
+- All tasks in plan.md are already checked off — nothing to implement
+- Trivial one-line changes (typo, config tweak) — edit directly without the full workflow
+- Design/planning phase — use /prizmkit-plan to produce spec and plan first
+
+**PRECONDITION:**
+
+| Required Artifact | Check | If Missing |
+|---|---|---|
+| `plan.md` with Tasks section | File exists + unchecked tasks | Run `/prizmkit-plan` |
+| `spec.md` | File exists in same directory as plan.md | Run `/prizmkit-plan` |
+
+**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, auto-detect per precondition above. |
+
+## Context Loading
+
+Before implementation, load context once:
+
+1. **Task context**: Read `plan.md` (including Tasks section) and `spec.md` from the artifact directory. If other companion documents exist in the directory (e.g., `refactor-analysis.md`), read them for additional context.
+2. **Architecture context**: Read `.prizmkit/prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1/L2 docs for affected modules. Pay special attention to TRAPS (known pitfalls) and DECISIONS (architectural choices).
+3. **Dev rules** (if configured): Check `.prizmkit/prizm-docs/root.prizm` for a `RULES:` line — if present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If a referenced file does not exist, skip it silently and continue. These define per-layer conventions (frameworks, naming, patterns, state management, etc.) that AI must follow when generating code for that layer. Apply these rules during implementation — if a rule conflicts with what plan.md describes, call it out and ask the user.
+
+> `.prizmkit/prizm-docs/` uses a 3-level hierarchy: L0 (`root.prizm`) is the project-wide index. L1 (e.g., `auth.prizm`) covers a module — its key files, interfaces, dependencies, traps, and decisions. L2 is for sub-modules with their own complexity. Implement reads these docs to avoid repeating known mistakes; `/prizmkit-retrospective` is responsible for updating them after implementation.
+
+## Execution
+
+For each unchecked task in plan.md, in order:
+
+1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
+2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+   - **Internal ID hygiene**: Do not place PrizmKit feature/bug/refactor IDs (`F-001`, `B-001`, `R-001`), task IDs, session IDs, run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy. Translate internal references into durable product/domain language before writing memory docs, tests, or UI copy.
+   - **Cover three paths for each function**: happy path (valid inputs producing expected behavior), edge cases (boundary values specific to the parameter type and domain — e.g., zero/min/max for numeric, empty collection, boundary index), and error conditions (inputs that should trigger error handling). Determine edge cases from the function's parameter types and domain logic, not from a fixed checklist. If a function has no edge or error paths, don't force them.
+   - **No redundant tests**: Check if a test for this behavior already exists before writing. Each test must verify a uniquely different code path — don't write multiple tests that exercise the same logic.
+   - **Test your own code only**: Don't test framework behavior, third-party library internals, or language built-ins. For library calls, test the integration point (correct parameters passed, return value correctly handled), not the library itself.
+3. Mark task as `[x]` in `plan.md` immediately after completion — not batched at the end. Immediate marking means plan.md always reflects true progress, even if the session is interrupted.
+4. **Parallel tasks**: If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group. Sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
+5. **Checkpoint tasks** (`CP:` prefix in plan.md): When a checkpoint task is reached, verify build passes and tests pass before continuing. Checkpoints catch integration errors early — skipping them means cascading failures in later phases.
+6. After all tasks complete: run full test suite.
+
+## Recovery
+
+If a session is interrupted mid-implementation:
+- Completed tasks are already marked `[x]` in plan.md (because we mark immediately)
+- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked `[ ]` task
+
+**HANDOFF:** `/prizmkit-code-review`
+
+## Output
+
+- Code files created/modified as specified in plan.md Tasks section
+- `plan.md` Tasks section updated with completion markers `[x]`
+- Implementation summary output to conversation

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

@@ -0,0 +1,102 @@
+---
+name: "prizmkit-plan"
+description: "Specify and plan tasks: natural language → spec.md & plan.md with architecture and executable tasks. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+---
+
+# PrizmKit Plan
+
+A universal spec + plan generator. Takes a natural-language description of ANY development task (new feature, refactoring, bug fix, migration, etc.) and produces `spec.md` (WHAT/WHY) and `plan.md` (HOW) with executable tasks.
+
+### When to Use
+- Any non-trivial development task that benefits from written specification and planning
+- Before `/prizmkit-implement` — to create the spec + task breakdown
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", "break it down"
+
+### When NOT to Use
+- Config tweaks, typo fixes, trivial one-line changes → edit directly
+- Simple changes where the developer already knows exactly what to do and the scope is ≤10 lines in a single file
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `description` | Yes | Natural-language description of the task |
+| `artifact_dir` | No | Directory to write spec.md + plan.md into. If omitted, auto-generates under `.prizmkit/specs/` (see Phase 0 Step 2). |
+
+## Execution
+
+### Phase 0: Specify (→ spec.md)
+
+**Skip condition**: If `spec.md` already exists in the artifact directory, skip to Phase 1.
+
+**Steps:**
+
+1. Gather input: read the task description. If no description is provided and interactive session is available, ask the user; otherwise abort with an error.
+2. Determine artifact directory:
+   - If `artifact_dir` is provided → use it directly
+   - If not provided → scan `.prizmkit/specs/` for existing `###-*` directories, find highest numeric prefix, next = highest + 1 (zero-padded to 3 digits; start at `001` if empty). Create `.prizmkit/specs/###-task-slug/`
+   - Auto-generate 2-10 word task slug from description
+3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
+4. Generate `spec.md` from template (`${SKILL_DIR}/assets/spec-template.md`):
+   - Fill sections based on the task description — all sections are optional, include only what is relevant
+   - `[NEEDS CLARIFICATION]` markers for all ambiguous items
+5. **Database design detection**: If changes involve data persistence (new entities, fields, schema changes), add `## Data Model` section — scan existing schema files to extract naming conventions, ID strategy, constraint patterns. Mark uncertain decisions with `[NEEDS CLARIFICATION]`.
+6. Run quality validation : all goals have criteria? scope defined? DB conventions documented (if applicable)?
+7. **Auto-clarification**: If any `[NEEDS CLARIFICATION]` markers remain and interactive session is available, enter interactive clarification.
+   → Read `${SKILL_DIR}/references/clarify-guide.md` for question strategy and update rules.
+   If non-interactive, resolve ambiguities by choosing the most conservative option and annotating the decision.
+   Resolve all markers before proceeding to Phase 1.
+
+**Writing principles**: Focus on WHAT and WHY, never HOW. Every goal needs acceptance criteria. Scope boundaries must be explicit. Mark all genuine ambiguities — the clarification phase resolves them.
+
+**Internal ID hygiene**: PrizmKit IDs (`F-001`, `B-001`, `R-001`), task IDs (`T-100`), session IDs, run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal tracking metadata. They may appear in specs, plans, commit messages, and non-memory pipeline artifacts, but must never be written to `.prizmkit/prizm-docs/`, user-visible product copy, UI text, API responses, or expected UI strings in tests. If a behavior is scoped to the current feature, describe the product behavior without the ID.
+
+### Phase 1: Design (spec.md → plan.md)
+
+**Precondition**: `spec.md` exists in the artifact directory.
+
+**Steps:**
+
+1. Read `spec.md` from the artifact directory
+2. Load project context if not already loaded in Phase 0: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
+3. Resolve any remaining `[NEEDS CLARIFICATION]` by proposing solutions
+4. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
+   - Change approach (how the changes integrate with existing system)
+   - Component / file changes
+   - Data model changes (with **database design gate** — read ALL existing schema files, ensure new schema follows existing patterns, resolve all DB ambiguities inline before proceeding)
+   - Interface design (API endpoints, request/response formats)
+   - Testing strategy
+   - Risk assessment
+   - Behavior preservation strategy (if the task modifies existing behavior — include what must remain unchanged and how to verify)
+5. Cross-check: every goal in spec.md maps to plan components — unmapped goals = coverage gaps
+6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES section
+
+### Phase 2: Task Generation (plan.md → Tasks section)
+
+1. If interactive session is available, ask user for strategy; otherwise infer automatically: MVP-first / Incremental / Parallel
+2. Append `## Tasks` section to `plan.md` using template in `${SKILL_DIR}/assets/plan-template.md`:
+   - Phases: Setup (T-001~T-009) → Foundation (T-010~T-099) → Core (T-100+) → Polish (T-900+)
+   - Each task: `- [ ] [T-NNN] [P?] [G-N?] Description — file: path/to/file`
+   - Checkpoint tasks between phases for validation
+   - Organize Core tasks by goals (G-1, G-2, ...) or by logical grouping appropriate to the task
+3. Verify consistency and coverage → read `${SKILL_DIR}/references/verification-checklist.md` and run all checks. Fix any issues inline before output.
+4. Output: `plan.md` path, summary of design decisions, task count.
+
+**HANDOFF:** `/prizmkit-implement`
+
+## Examples
+
+Read `${SKILL_DIR}/references/examples.md` for worked examples of feature, refactoring, and bug fix planning.
+
+## References
+
+- Spec template: `${SKILL_DIR}/assets/spec-template.md`
+- Plan template: `${SKILL_DIR}/assets/plan-template.md`
+- Clarification guide: `${SKILL_DIR}/references/clarify-guide.md`
+- Verification checklist: `${SKILL_DIR}/references/verification-checklist.md`
+
+## Output
+
+| Directory | Files |
+|---|---|
+| `artifact_dir` (provided or auto-generated `.prizmkit/specs/###-slug/`) | `spec.md` + `plan.md` |

package/bundled/skills-windows/prizmkit-plan/assets/plan-template.md

@@ -0,0 +1,115 @@
+# Plan: [TITLE]
+
+## Change Approach
+[Description of the technical approach — how these changes integrate with the existing system]
+
+## Component Design
+
+### New Components
+- [Component]: [Purpose]
+
+### Modified Components
+- [Component]: [What changes and why]
+
+## Behavior Preservation Strategy
+<!-- Include when the task modifies existing behavior. Delete if not applicable (e.g., greenfield feature). -->
+<!-- Strategy: one of test-gate / snapshot / manual -->
+<!-- test-gate: all tests must pass after each task -->
+<!-- snapshot: before-after comparison of outputs -->
+<!-- manual: reviewer verification at checkpoints -->
+- Strategy: [test-gate / snapshot / manual]
+- Baseline: [describe green test suite or snapshot state]
+
+## Data Model
+<!-- Include when changes involve database / data persistence. Delete if not applicable. -->
+<!-- IMPORTANT: Read existing schema/model files BEFORE designing new tables -->
+
+### Existing Schema Audit
+<!-- List existing tables/models reviewed. Note observed conventions. -->
+- Tables reviewed: [list tables examined]
+- Naming convention: [snake_case/camelCase — document what existing schema uses]
+- ID strategy: [UUID/auto-increment/CUID — match existing]
+- Timestamp fields: [created_at/updated_at pattern — match existing]
+- Soft delete: [yes/no, field name if applicable]
+- Constraint patterns: [NOT NULL defaults, UNIQUE patterns, index conventions]
+
+### Schema Changes
+| Entity | Type | Fields | Constraints | Relationships | Migration Notes |
+|--------|------|--------|-------------|---------------|-----------------|
+| [name] | new/modify | [field: type, ...] | [NOT NULL, UNIQUE, INDEX, ...] | [FK → existing_table(id)] | [migration strategy] |
+
+### Style Conformance Checklist
+- [ ] Table/column naming matches existing conventions
+- [ ] ID strategy consistent with existing tables
+- [ ] Timestamp fields follow existing patterns
+- [ ] Foreign key constraints and indexes defined
+- [ ] Soft delete strategy matches existing pattern (if applicable)
+- [ ] All fields have explicit nullability (NOT NULL or nullable)
+
+### Unresolved Questions
+<!-- NONE — all DB design questions must be resolved inline before proceeding to Tasks -->
+
+## Interface Design
+[API endpoints, request/response formats, module interfaces — include all details here]
+
+## Integration Points
+- [Service/Module]: [How integrated]
+
+## Testing Strategy
+- Unit: [Approach]
+- Integration: [Approach]
+- E2E: [Approach]
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk] | [H/M/L] | [Plan] |
+
+## Deployment Considerations
+<!-- Include when there is deployment impact (new services, infra, environment changes). Delete if not applicable. -->
+
+### New Infrastructure Requirements
+- [Component]: [Deployment target from config deploy_strategy] — [any special config needed]
+
+### New Environment Variables
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| [VAR_NAME] | yes/no | [Purpose] | [example value] |
+
+### Deployment Impact
+- [ ] No infrastructure changes needed (skip this section)
+- [ ] New service/container required
+- [ ] New environment variables added
+- [ ] Database migration required in production
+- [ ] CI/CD pipeline update needed
+
+## Pre-Implementation Gates
+- [ ] Spec coverage: all goals mapped to components
+- [ ] Data model reviewed — existing schema conventions documented and followed (if applicable)
+- [ ] All `[NEEDS CLARIFICATION]` items resolved
+- [ ] Testing approach agreed
+- [ ] Behavior preservation strategy defined (if modifying existing behavior)
+- [ ] Root cause confirmed with reproduction test design (if fixing a defect)
+
+## Tasks
+
+### Strategy: [MVP-first | Incremental | Parallel]
+
+### Phase: Setup
+- [ ] [T-001] [Description] — file: [path]
+
+### Phase: Foundation
+- [ ] [T-010] [Description] — file: [path]
+
+### Phase: Core
+<!-- Organize by goals (G-1, G-2, ...) or by logical grouping appropriate to the task -->
+- [ ] [T-100] [P] [G-1] [Task description] — file: [path]
+
+### Phase: Polish
+- [ ] [T-900] Final verification
+- [ ] [T-901] Documentation update
+
+### Checkpoints
+- [ ] [CP-1] After Setup: project builds and tests pass
+- [ ] [CP-2] After Foundation: base changes verified
+- [ ] [CP-3] After each Core group: acceptance criteria pass

package/bundled/skills-windows/prizmkit-plan/assets/spec-template.md

@@ -0,0 +1,73 @@
+# [TITLE]
+
+## Overview
+[One paragraph describing the purpose and motivation]
+
+## Goals
+
+### G-1: [Goal Title]
+[Goal description — use whatever format best suits the task:
+  - User Story format: "As a [role], I want [capability], so that [benefit]."
+  - Objective format: "Objective: [change to make]. Target state: [desired outcome]."
+  - Fix format: "Fix: [symptom]. Root cause: [brief cause]."
+  - Or any other clear format.]
+
+**Acceptance Criteria:**
+- [ ] [Criterion 1 — Given/When/Then, or a concrete verifiable statement]
+
+## Scope
+
+### In Scope
+- [Item 1]
+
+### Out of Scope
+- [Item 1]
+
+## Behavior Preservation
+<!-- Include this section when the task modifies existing behavior (refactoring, bug fixes, migrations, etc.). Delete if not applicable. -->
+- [What behavior / contracts / interfaces must remain unchanged]
+- [Existing test suites that must continue to pass]
+
+## Root Cause
+<!-- Include this section when the task is fixing a defect. Delete if not applicable. -->
+- Error classification: [Runtime / Network / Auth / Data / Logic / Config / External]
+- Root cause: [specific code location and mechanism]
+- Affected files: [file list with line numbers]
+- Impact: [blast radius — which modules / features are affected]
+
+## Dependencies
+- [Dependency 1]: [Why needed]
+
+## Data Model
+<!-- Include this section when changes involve database / data persistence. Delete if not applicable. -->
+
+### Existing Schema Reference
+<!-- Read existing schema/model files BEFORE designing new tables. Document observed conventions here. -->
+- Tables reviewed: [list existing tables related to this change]
+- Naming convention: [snake_case/camelCase — match existing]
+- ID strategy: [UUID/auto-increment — match existing]
+- Timestamp pattern: [created_at/updated_at — match existing]
+- Soft delete: [yes/no, field name — match existing]
+
+### New/Modified Entities
+| Entity | Type (new/modify) | Key Fields | Relationships | Constraints |
+|--------|-------------------|------------|---------------|-------------|
+| [entity_name] | new | [field: type] | [FK to existing_table] | [NOT NULL, UNIQUE, etc.] |
+
+### Open Data Model Questions
+<!-- All questions here MUST be resolved before /prizmkit-plan generates Tasks -->
+- [NEEDS CLARIFICATION] [Any uncertain data model decisions — field types, nullability, relationships]
+
+## Constraints
+- [Constraint 1]
+
+## Clarifications
+[NEEDS CLARIFICATION]: [Ambiguous item]
+
+## Review Checklist
+- [ ] All goals have acceptance criteria
+- [ ] Scope boundaries are clearly defined
+- [ ] Dependencies are identified
+- [ ] No implementation details (WHAT not HOW)
+- [ ] Behavior preservation defined (if modifying existing behavior)
+- [ ] Root cause identified with evidence (if fixing a defect)

package/bundled/skills-windows/prizmkit-plan/references/clarify-guide.md

@@ -0,0 +1,67 @@
+# Clarification Phase — Execution Guide
+
+Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLARIFICATION]` markers exist, or during Phase 1 (design) when data model ambiguities arise.
+
+---
+
+## Question Strategy
+
+**Ask one question at a time.** Batching questions produces lower-quality answers.
+
+For each question:
+1. Cite the exact location in spec.md (e.g., "§Goals G-1 says..." or "§Scope says...")
+2. State what is ambiguous and why it matters for implementation
+3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
+
+**Prioritize by implementation impact** (highest first):
+1. Data model (entities, relationships, field types, constraints, naming) — **hardest to change after code is written**
+2. Functional scope boundaries
+3. UX flow and error handling
+4. Non-functional requirements (performance, security)
+5. Edge cases and integration points
+
+## Update Discipline
+
+After **each** user answer:
+- Immediately update `spec.md` (do not batch at the end)
+- Remove the resolved `[NEEDS CLARIFICATION]` marker
+- Re-evaluate for new ambiguities exposed by the answer
+
+## No Limits Policy
+
+**There is no cap on rounds or questions.** Keep asking until:
+- All `[NEEDS CLARIFICATION]` markers are removed, AND
+- No vague or underspecified areas remain, AND
+- You are fully confident about the requirements
+
+If the user's answer raises new questions — ask those too. If a previously-resolved item needs revisiting due to new context — go back.
+
+## Early Termination
+
+If the user says "done", "stop", or "enough" — end immediately and output a summary of:
+- What was resolved
+- What remains unclear (list any open `[NEEDS CLARIFICATION]` items)
+
+## Example Exchange
+
+**Question:**
+> §Goals G-1 says "User can upload files" but doesn't specify file types or size limits.
+>
+> **Recommended:** Accept JPEG, PNG, PDF up to 10MB — covers common use cases without straining storage.
+>
+> Do you agree, or different constraints?
+
+**User:** "Also allow SVG, make it 25MB"
+
+**Action:** Update spec.md §Goals G-1 → `File upload: JPEG, PNG, PDF, SVG. Max 25MB per file.` Remove marker.
+
+**Follow-up question triggered by answer:**
+> SVGs can contain embedded scripts (XSS risk). Should uploaded SVGs be sanitized (strip `<script>` + event handlers), or restricted to trusted users only?
+>
+> **Recommended:** Sanitize all SVG uploads — allows all users to upload safely.
+
+## Guidelines
+
+- Stay at WHAT/WHY level — no implementation details (HOW) in spec
+- If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
+- If the user seems fatigued: "I have N more questions — continue now or later?" — but never silently stop with unresolved ambiguities