prizmkit 1.1.7 → 1.1.9

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

@@ -1,11 +1,11 @@
 ---
 name: "prizmkit-init"
-description: "Project takeover and bootstrap. Scans any project, generates Prizm docs, configures hooks. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
+description: "Project takeover and bootstrap. Scans any project, generates Prizm docs and project brief. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
 ---
 
 # PrizmKit Init
 
-Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation, and configures platform-specific hooks for documentation sync. Supports CodeBuddy, Claude Code, and dual-platform installations.
+Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation and project brief. Supports CodeBuddy, Claude Code, and dual-platform installations.
 
 ### When to Use
 - Taking over a new project (brownfield or greenfield)
@@ -14,35 +14,58 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 - After `npx prizmkit install` when project has no `.prizm-docs/`
 
 ### When NOT to Use
-- `.prizm-docs/` already exists and is up to date → use `/prizmkit-prizm-docs` (Update) instead
-- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild)
-- User wants to start a feature → skip init if already initialized, go to `/prizmkit-plan`
+- All artifacts exist and are up to date → use `/prizmkit-prizm-docs` (Update) instead if you only want to resync docs
+- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild) instead (faster, targeted)
+- User wants to start a feature on an already-initialized project → skip init, go to `/prizmkit-plan`
 
 ### Error Handling
-- If `.prizm-docs/` already exists: ask user if they want to reinitialize (overwrites) or update (preserves)
+- If artifacts already exist: idempotent status check offers regenerate/skip choices (see Phase 3: Idempotent Status Check)
 - If no source files found in any directory: fall back to greenfield mode
-- If platform cannot be detected: ask user explicitly which platform(s) to configure
 
 ## Execution Steps
 
-**PLATFORM DETECTION (before anything else):**
-1. Check for platform indicators in the current environment:
-   - CodeBuddy: `.codebuddy/` directory exists, or running inside `cbc` session
-   - Claude Code: `.claude/` directory exists, or running inside `claude` session
-   - Both: Both directories exist
-   - Unknown: Neither exists — ask the user which platform(s) to configure
-2. Store detected platform in `.prizmkit/config.json` as `"platform": "codebuddy" | "claude" | "both"`
-
-MODE DETECTION:
-- If `.prizm-docs/` exists: Ask user if they want to reinitialize or update
-  - **Reinitialize**: overwrites `.prizm-docs/` and `config.json` tech_stack (fresh start)
-  - **Update**: re-scans tech stack and merges changes into existing `config.json` (see Step 3b merge strategy); updates `root.prizm` TECH_STACK if changed; preserves existing `.prizm-docs/` L1/L2 docs; checks for missing L1/L2 docs and creates them for modules with source files (see Update Supplement below)
+**Phase 1: Platform Detection**
+1. Detect which platform is running (CodeBuddy or Claude Code) via AI CLI environment.
+2. Hold detected platform value in memory — written to disk in Phase 6 along with other config fields.
+
+**Phase 2: Mode Detection**
 - If project has source code: brownfield mode
 - If project is nearly empty: greenfield mode
 
+**Phase 3: Idempotent Status Check**
+
+Scan all init artifacts and display their status:
+
+| Artifact | Path | Check |
+|----------|------|-------|
+| Prizm docs | `.prizm-docs/` | Directory exists + `root.prizm` present |
+| Runtime config | `.prizmkit/config.json` | File exists |
+| Project brief | `.prizmkit/plans/project-brief.md` | File exists |
+
+Display status table to user:
+```
+Init Status Check:
+  [exists]  .prizm-docs/          (N files)
+  [exists]  .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+```
+
+- **If all missing**: skip interaction, proceed to generate everything.
+- **If some exist**: ask user once:
+  - **[A] Regenerate all** — overwrite all existing artifacts (fresh start)
+  - **[B] Only generate missing** — skip existing, fill gaps (default)
+  - **[C] Pick per item** — ask for each existing artifact: regenerate or skip
+
+Each subsequent phase checks its artifact's action before executing:
+- `action == skip` → output "Skipped (exists)" and move on
+- `action == generate | regenerate` → run normally
+- **Special case for `.prizm-docs/`**:
+  - `skip` = **Update** mode: preserve existing L1/L2 docs, re-scan tech stack, merge changes, check for missing docs (see `${SKILL_DIR}/references/update-supplement.md`)
+  - `regenerate` = **Reinitialize**: overwrite everything
+
 BROWNFIELD WORKFLOW (existing project):
 
-**Step 1: Project Scanning**
+**Phase 4: Project Scanning**
 1. Detect tech stack from build files (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Cargo.toml`, etc.)
 2. Map directory structure using a TWO-TIER model — flat structures lose the nesting relationships that AI needs to navigate the codebase:
    - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
@@ -68,8 +91,8 @@ BROWNFIELD WORKFLOW (existing project):
 
    **IMPORTANT**: Not all projects have all fields. A pure backend API will have no `frontend_framework` or `frontend_styling`. A library may have no database. Only record what is actually detected — never generate empty or placeholder values.
 
-**Step 2: Prizm Documentation Generation**
-Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Step 1:
+**Phase 5: Prizm Documentation Generation**
+Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
   - Create `.prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizm-docs/<top-level>/`)
   - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
   - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
@@ -77,25 +100,53 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - Create `changelog.prizm`
   - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
 
-**Step 3: PrizmKit Workspace Initialization**
-3a. Create `.prizmkit/` directory:
+**Phase 6: Workspace Initialization**
+6a. Create `.prizmkit/` directory structure (if missing):
   - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
   - `.prizmkit/specs/` (empty)
+  - `.prizmkit/plans/` (empty — needed by Phase 7 and future pipeline tasks)
 
-3b. Write detected tech stack to `.prizmkit/config.json`:
+6b. Write detected tech stack to `.prizmkit/config.json`:
    → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
-**Step 4: Hook & Settings Configuration**
-
-4a. Read or create platform settings file (`.codebuddy/settings.json` or `.claude/settings.json`)
-4b. Add UserPromptSubmit and PostToolUse hooks for automatic prizm-docs reminders
-4c. For Claude Code: also add `permissions` entries and `.claude/rules/` for documentation enforcement:
-  - `.claude/rules/prizm-documentation.md` (glob-scoped source file rules)
-  - `.claude/rules/prizm-commit-workflow.md` (commit workflow enforcement)
-4d. Preserve any existing hooks and settings — never overwrite user's custom configuration
-
-**Step 5: Report**
-Output summary: platform detected, tech stack detected (with detail), modules discovered, L1 docs generated, platform-specific configuration applied, next recommended steps.
+**Phase 7: Project Brief Generation**
+
+If action for project brief == skip, output "Project brief: skipped (exists)" and proceed to Phase 8 (Report).
+
+Otherwise, generate a project brief to capture the user's overall product vision. This file is referenced by `root.prizm` so every new AI session understands the project goals.
+
+→ Read `${SKILL_DIR}/assets/project-brief-template.md` for the brief format rules and checklist template.
+
+**Brownfield** (existing codebase):
+1. Infer project goals from:
+   - Generated `root.prizm` (tech stack, module structure, module groups)
+   - `README.md` (if exists)
+   - Package metadata (`package.json` description, `pyproject.toml`, etc.)
+   - Quick scan of key entry points identified in L1 docs
+2. Generate a draft in the checklist format defined in the template
+3. Present the draft to the user and ask:
+   - Is this inference correct?
+   - Anything to add, remove, or modify?
+4. Apply user edits and write to `.prizmkit/plans/project-brief.md`
+
+**Greenfield** (new/empty project):
+1. Use **progressive questioning** (defined in template) to fully understand the user's intent:
+   - Round 1: Problem & Vision → Round 2: Scope & Features → Round 3: Technical Constraints → Round 4: Clarification (adaptive)
+   - Stop when completion criteria are met: problem, users, core features, boundaries, and technical direction are all clear
+   - If answers are vague, probe deeper — don't accept shallow responses
+2. Generate brief from answers in checklist format
+3. Present to user for confirmation/editing
+4. Write to `.prizmkit/plans/project-brief.md`
+
+**After writing the brief**:
+- Check if `root.prizm` already contains a `PROJECT_BRIEF:` line
+- If exact match `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` exists: skip (already correct)
+- If `PROJECT_BRIEF:` exists with a different path: warn user and ask to confirm update or keep old path
+- If not present: add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` at the end of `root.prizm`, after all standard sections
+- This ensures every AI session that loads L0 knows to read the project brief
+
+**Phase 8: Report**
+Output summary: platform detected, tech stack detected (with detail), modules discovered, L1 docs generated, project brief status, next recommended steps.
 
 Tech stack report format (only show detected fields, adapt to project type):
 ```
@@ -114,37 +165,16 @@ Adapt fields to match project type — only show detected fields.
 
 Saved to: `.prizmkit/config.json` → `tech_stack` field
 
-Include platform-specific guidance:
-- CodeBuddy: "Use `/prizmkit-plan` to start your first feature"
-- Claude Code: "Use `/prizmkit-plan` to start your first feature"
+Next step: "Use `/prizmkit-plan` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
-- Skip Step 1 (no code to scan) — but ask the user about their intended tech stack:
+- Skip Phase 4 (no code to scan) — but ask the user about their intended tech stack:
   - "What language/framework will you use?" (e.g. React + Node.js, Python + FastAPI, etc.)
   - Record answers in `config.json` `tech_stack` with `"_auto_detected": false` (user-provided, not auto-detected)
   - If user is unsure, skip tech_stack — it can be populated later on re-init after code exists
-- Step 2: Create minimal `.prizm-docs/` with just `root.prizm` skeleton (populate TECH_STACK from user answers if provided)
-- Steps 3-5: Same as brownfield (Step 5 Report recommends starting with specify for first feature)
-
-### Gradual Adoption Path
-After init, PrizmKit operates in phases:
-- **Passive** (default): Generates docs, doesn't enforce workflow
-- **Advisory**: Suggests improvements, flags issues (enable in config)
-- **Active**: Enforces spec-driven workflow for new features (enable in config)
-
-User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "advisory" | "active"`
-
-### Platform Reference
-
-| Concept | CodeBuddy | Claude Code |
-|---------|-----------|-------------|
-| Command invocation | `/prizmkit-xxx` | `/prizmkit-xxx` |
-| Project knowledge | `.prizm-docs/` | `.prizm-docs/` |
-| Settings | `.codebuddy/settings.json` | `.claude/settings.json` |
-| Skills/Commands | `.codebuddy/skills/` | `.claude/commands/` |
-| Agents | `.codebuddy/agents/` | `.claude/agents/` |
-| Rules | hooks in settings.json | `.claude/rules/*.md` |
-| CLI command | `cbc` | `claude` |
+- Phase 5: Create minimal `.prizm-docs/` with just `root.prizm` skeleton (populate TECH_STACK from user answers if provided)
+- Phase 7: Generate project brief (greenfield flow — ask user about project goals, see Phase 7 above)
+- Phases 6, 8: Same as brownfield (Phase 8 Report recommends `/prizmkit-plan` for first feature)
 
 ## Example
 
@@ -153,6 +183,12 @@ User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "
 $ /prizmkit-init
 
 Platform detected: Claude Code
+Init Status Check:
+  [missing] .prizm-docs/
+  [missing] .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+→ All missing, generating everything.
+
 Mode: Brownfield (154 source files found)
 
 Tech stack detected:
@@ -171,8 +207,10 @@ Modules discovered:
   src/services/   → .prizm-docs/services.prizm (15 files)
   src/middleware/  → .prizm-docs/middleware.prizm (5 files)
 
+Project brief: inferred from codebase → confirmed by user
+  → .prizmkit/plans/project-brief.md
+
 Generated: root.prizm + 4 L1 docs + changelog.prizm
-Configured: .claude/rules/ (2 files), hooks in settings.json
 Saved: .prizmkit/config.json (tech_stack recorded)
 
 Next: Use /prizmkit-plan to start your first feature
@@ -185,8 +223,14 @@ UPDATE SUPPLEMENT (runs after tech stack merge in Update mode):
 ```
 $ /prizmkit-init
 
-.prizm-docs/ already exists. Reinitialize or update?
-> Update (preserve existing docs)
+Init Status Check:
+  [exists]  .prizm-docs/          (12 files)
+  [exists]  .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+
+Missing items will be generated.
+For existing items: [A] Regenerate all  [B] Only generate missing (default)  [C] Pick per item
+> B (Only generate missing)
 
 Tech stack changes detected:
   + bundler: Vite (newly detected)
@@ -199,5 +243,8 @@ Documentation gap-fill:
   = routes.prizm (L1) — up to date
   ~ models.prizm (L1) — FILES count updated (8 → 10)
 
+Project brief: inferred from codebase → confirmed by user
+  → .prizmkit/plans/project-brief.md (generated)
+
 Merged into .prizmkit/config.json (2 fields updated, user overrides preserved)
 ```

package/bundled/skills/prizmkit-init/assets/project-brief-template.md

@@ -0,0 +1,82 @@
+# Project Brief Template
+
+> Capture the user's key product ideas as a simple checklist. Each line is one idea. This file is referenced by `root.prizm` (`PROJECT_BRIEF:`) so every new AI session automatically knows the project's goals.
+
+## File Location
+
+`.prizmkit/plans/project-brief.md`
+
+## Format
+
+```markdown
+# Project Brief
+
+[ ] Core product idea or constraint
+[ ] Another product idea
+[ ] Third idea — one sentence, no sub-bullets
+[x] Already implemented feature -> src/feature/, src/utils/helper.ts
+```
+
+## Rules
+
+1. **First line**: `# Project Brief`
+2. **Remaining lines**: One idea per line, prefixed with `[ ]` (pending) or `[x]` (done)
+3. Each line is **one sentence** — no paragraphs, no sub-bullets, no grouping headers
+4. Language: match the user's language (Chinese or English)
+5. **Size limit**: 500 words max (this file is injected into every session's context window)
+6. **Completion marking** (mandatory): When a brief item is implemented:
+   - Change `[ ]` to `[x]`
+   - Append `->` followed by the **key file or directory paths** that implement it
+   - List the most important 1-3 paths only (entry point, core module, or directory) — not every touched file
+   - Example: `[x] User authentication with OAuth -> src/auth/, src/middleware/auth.ts`
+   - This lets future AI sessions instantly locate the implementation without re-scanning
+
+## Brownfield Init
+
+When initializing an existing project, AI infers the brief from:
+- Generated `root.prizm` (tech stack, module structure)
+- `README.md` (if exists)
+- Package metadata (`package.json` description, `pyproject.toml`, etc.)
+
+Then presents the draft to the user for confirmation and editing.
+
+## Greenfield Init
+
+When initializing a new/empty project, use **progressive questioning** to fully understand the user's intent before generating the brief. Do NOT dump all questions at once — ask in rounds, adapting based on answers.
+
+### Round 1: Problem & Vision (required)
+- What problem does this project solve? (or: what's the core idea?)
+- Who is the target user / audience?
+
+### Round 2: Scope & Features (required)
+- What are the 3-5 core features or capabilities? (ask user to list them)
+- What is the MVP scope? (what's the minimum version that delivers value?)
+- Are there any explicit non-goals? (things this project deliberately does NOT do)
+
+### Round 3: Technical Constraints (if user has preferences)
+- Any preferred tech stack / language / framework?
+- Any integration requirements? (third-party APIs, databases, auth providers)
+- Deployment target? (web app, mobile, CLI, library, self-hosted, cloud)
+
+### Round 4: Clarification (adaptive — only if gaps remain)
+If previous answers are vague or incomplete, probe deeper:
+- "You mentioned X — can you give a concrete example of how a user would use it?"
+- "Are there existing tools that do something similar? How is yours different?"
+- "What does success look like for V1?"
+
+### Completion Criteria
+Stop asking when ALL of these are clear:
+1. **Problem** — what pain point or opportunity this addresses
+2. **Users** — who will use it and in what context
+3. **Core features** — at least 3 concrete capabilities (not vague aspirations)
+4. **Boundaries** — what's in scope vs. out of scope for V1
+5. **Technical direction** — enough to populate `config.json` tech_stack (or explicitly deferred)
+
+If the user gives short/vague answers, don't accept them — rephrase and ask again. A weak brief leads to weak specs downstream.
+
+### Generate & Confirm
+Once all criteria are met:
+1. Generate brief in checklist format (see Format section above)
+2. Present to user with: "Here's what I captured — anything to add, remove, or change?"
+3. Apply edits and write to `.prizmkit/plans/project-brief.md`
+

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

@@ -1,111 +1,103 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan features: natural language → spec.md → plan.md with architecture and executable tasks. Supports feature, refactor, and bugfix modes. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new feature', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+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
-- New feature — user says "specify", "plan", "new feature", "I want to add..."
+- Any non-trivial development task that benefits from written specification and planning
 - Before `/prizmkit-implement` — to create the spec + task breakdown
-- When a feature idea needs to go from concept to executable plan
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", "break it down"
 
 ### When NOT to Use
-- Bug fix with clear root cause → fast path (skip Phase 0, simplified plan → implement → commit)
-- Config tweaks, typo fixes → edit directly
-- User already has a detailed spec → start from Phase 1
+- 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 (WHAT)
+### Phase 0: Specify (→ spec.md)
 
-Transforms natural language into a structured spec. Skip this phase when:
-- A `spec.md` already exists for this feature
-- Running in refactor mode (input is `refactor-analysis.md`)
-- Running in bugfix mode (input is `fix-plan.md` or caller-provided description)
+**Skip condition**: If `spec.md` already exists in the artifact directory, skip to Phase 1.
 
 **Steps:**
 
-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/`:
-   - List existing `###-*` directories, find highest numeric prefix
-   - Next = highest + 1 (zero-padded to 3 digits)
-   - If empty or doesn't exist, start at `001`
-4. Create directory: `.prizmkit/specs/###-feature-name/`
-5. Load project context (use first available):
-   - If `context-snapshot.md` exists in the feature dir → read Section 3 'Prizm Context' (skip re-reading .prizm-docs/)
-   - Otherwise → read `.prizm-docs/root.prizm` and relevant L1/L2 docs
-6. Generate `spec.md` from template (`${SKILL_DIR}/assets/spec-template.md`):
-   - Feature title and description
-   - User stories (As a... I want... So that...) with acceptance criteria (Given/When/Then)
-   - Scope boundaries (In scope / Out of scope)
-   - Dependencies and constraints
+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 `.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
-7. **Database design detection**: If feature involves data persistence (new entities, fields, schema changes), add a `## Data Model` section to spec.md — scan existing schema files to extract naming conventions, ID strategy, constraint patterns. Mark uncertain decisions with `[NEEDS CLARIFICATION]`.
-8. Run quality validation (max 3 iterations): all stories have criteria? scope defined? DB conventions documented?
-9. **Auto-clarification**: If any `[NEEDS CLARIFICATION]` markers remain, enter interactive clarification immediately.
+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 user story needs acceptance criteria. Scope boundaries must be explicit. Mark all genuine ambiguities — the clarification phase resolves them.
+**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.
 
-### Phase 1: Design (HOW)
+### Phase 1: Design (spec.md → plan.md)
 
-**Precondition:**
-
-| Mode | Required Input | Directory |
-|---|---|---|
-| **Feature** (default) | `spec.md` (from Phase 0) + `.prizm-docs/root.prizm` | `.prizmkit/specs/###-feature-name/` |
-| **Refactor** | `refactor-analysis.md` | `.prizmkit/refactor/<refactor-slug>/` |
-| **Bugfix** | `fix-plan.md` or caller-provided description | `.prizmkit/bugfix/<BUG_ID>/` |
-
-If no input document exists, prompt user to describe the feature (triggers Phase 0).
+**Precondition**: `spec.md` exists in the artifact directory.
 
 **Steps:**
 
-1. Read the input document (spec.md / refactor-analysis.md / fix-plan.md)
-2. Load project context if not already loaded in Phase 0:
-   - If `context-snapshot.md` exists → read it for docs + code structure
-   - Otherwise → read `.prizm-docs/root.prizm` and relevant L1/L2 docs
+1. Read `spec.md` from the artifact directory
+2. Load project context if not already loaded in Phase 0: read `.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`):
-   - Architecture approach, component design
+   - 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)
-   - Integration points, testing strategy, risk assessment
-5. Cross-check: every user story maps to plan components — unmapped stories = coverage gaps
+   - 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 `.prizm-docs/root.prizm` RULES section
-7. **Deployment strategy check:**
+7. **Deployment strategy check** (skip if no deployment impact):
    - Read `.prizmkit/config.json` `deploy_strategy` field
-   - No strategy → ask user, write to config.json
-   - Strategy exists + new tech stack detected → ask about new component only
-   - Skipped in fast-path mode (bug fixes / simple refactors)
+   - No strategy and new infra needed → ask user, write to config.json
 
-### Phase 2: Task Generation
+### Phase 2: Task Generation (plan.md → Tasks section)
 
-1. Ask user for strategy (or infer): MVP-first / Incremental / Parallel
-2. Append `## Tasks` section to `plan.md` using tasks template in `${SKILL_DIR}/assets/plan-template.md`:
-   - Phases: Setup (T-001~T-009) → Foundational (T-010~T-099) → User Stories (T-100+) → Polish (T-900+)
-   - Each task: `- [ ] [T-NNN] [P?] [US?] Description — file: path/to/file`
+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
-3. Verify coverage:
-   - Every user story → at least one task
-   - Every task → a target file path
-   - Risk assessment → at least one risk with mitigation
-4. Output: `plan.md` path, summary of design decisions, task count
+   - 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`
 
-## Example
+## Examples
+
+### Example 1: New Feature
 
 **Input:** "I want users to upload avatars"
 
 **Phase 0 output:** `.prizmkit/specs/003-user-avatar/spec.md`
 ```markdown
-# Feature: User Avatar Upload
-## User Stories
-### US-1: Upload Avatar
+# User Avatar Upload
+## Overview
+Allow registered users to upload and manage profile pictures.
+## Goals
+### G-1: Upload Avatar
 As a registered user, I want to upload a profile picture,
 so that other users can visually identify me.
 **Acceptance Criteria:**
@@ -119,26 +111,75 @@ so that other users can visually identify me.
 
 **Phase 1-2 output:** `plan.md` excerpt:
 ```markdown
-## Architecture Approach
-Extend existing user profile module. Add S3 integration for file storage.
-
 ## Tasks
-### Phase: Data Layer (T-010~T-019)
-- [ ] [T-010] [US-1] Add avatar_url field to User model — file: src/models/user.ts
-- [ ] [T-011] [US-1] Create S3 upload utility — file: src/lib/s3.ts
-### Phase: API [P] (T-100~T-109)
-- [ ] [T-100] [P] [US-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
+### Phase: Foundation (T-010~T-019)
+- [ ] [T-010] [G-1] Add avatar_url field to User model — file: src/models/user.ts
+- [ ] [T-011] [G-1] Create S3 upload utility — file: src/lib/s3.ts
+### Phase: Core [P] (T-100~T-109)
+- [ ] [T-100] [P] [G-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
+```
+
+### Example 2: Refactoring
+
+**Input:** "Extract shared auth middleware from the API routes"
+
+**Phase 0 output:** `.prizmkit/specs/004-extract-auth-middleware/spec.md`
+```markdown
+# Extract Auth Middleware
+## Overview
+Consolidate duplicated authentication logic scattered across route files into a single shared middleware.
+## Goals
+### G-1: Extract Shared Authentication Logic
+Consolidate duplicated auth checks from 5 route files into a single middleware module.
+**Acceptance Criteria:**
+- All existing auth-related tests pass without modification
+- Auth logic exists in exactly one file (src/middleware/auth.ts)
+- No route file contains inline token verification
+## Scope
+- **In scope:** src/routes/users.ts, orders.ts, admin.ts, payments.ts, profile.ts
+- **Out of scope:** Authorization (role-based access), rate limiting
+## Behavior Preservation
+- All 23 existing API tests must pass unchanged
+- Response formats and HTTP status codes must not change
+- Error message strings must remain identical
+```
+
+### Example 3: Bug Fix
+
+**Input:** "Login page crashes when API returns 401"
+
+**Phase 0 output:** `.prizmkit/specs/005-login-401-crash/spec.md`
+```markdown
+# Fix: Login Crash on 401 Response
+## Overview
+Login page throws unhandled exception when auth API returns 401, causing a white screen.
+## Goals
+### G-1: Handle 401 Response Gracefully
+When the auth API returns 401, display an error message instead of crashing.
+**Acceptance Criteria:**
+- Given user submits invalid credentials, When API returns 401, Then error message "Invalid credentials" is displayed
+- Given user submits invalid credentials, When API returns 401, Then no unhandled exception is thrown
+## Root Cause
+- Error classification: Runtime
+- Root cause: `AuthService.handleLogin()` at src/services/auth.ts:42 does not handle null token
+- Affected files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
+## Scope
+- **In scope:** Null handling in auth service, error display in login page
+- **Out of scope:** Other HTTP error codes (403, 500), auth flow redesign
+## Behavior Preservation
+- All existing login success tests must pass unchanged
+- Auth token flow for valid credentials must not change
 ```
 
-## Templates
+## 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
 
-| Mode | Directory | Files |
-|---|---|---|
-| Feature | `.prizmkit/specs/###-feature-name/` | `spec.md` + `plan.md` |
-| Refactor | `.prizmkit/refactor/<refactor-slug>/` | `plan.md` |
-| Bugfix | `.prizmkit/bugfix/<BUG_ID>/` | `plan.md` |
+| Directory | Files |
+|---|---|
+| `artifact_dir` (provided or auto-generated `.prizmkit/specs/###-slug/`) | `spec.md` + `plan.md` |