prizmkit 1.0.153 → 1.1.1

package/bundled/skills/app-planner/references/project-brief-guide.md

@@ -0,0 +1,110 @@
+# Project Brief — Real-Time Accumulation Guide
+
+> Distill the user's key requirements, design decisions, and project context into a concise `project-brief.md` during interactive planning. This file is injected into every headless `dev-pipeline` session so individual feature builds understand the bigger picture.
+
+## Purpose
+
+When `app-planner` generates 20+ features through conversation, each headless session only sees its own feature description and the tech stack (`global_context`). Cross-feature design decisions, business intent, and user-emphasized details exist only in the chat history and are lost. `project-brief.md` bridges this gap.
+
+## Persistence
+
+- **File**: `project-brief.md` at project root (same level as `feature-list.json`)
+- **Format**: Markdown with fixed sections, bullet-point style
+- **Size limit**: 500 words max (injected into every session's context window)
+- **Consumed by**: `dev-pipeline/scripts/generate-bootstrap-prompt.py` → `{{PROJECT_BRIEF}}` placeholder
+
+## Accumulation Trigger
+
+After each meaningful user response (skip acknowledgments, yes/no confirmations, or meta-conversation), evaluate whether the response contains:
+
+- Business/product intent or vision
+- Technical constraints or preferences
+- Cross-feature design decisions (e.g., "all APIs use JWT", "use Material Design 3")
+- Specific implementation preferences or details the user emphasized
+
+If yes → update the relevant section in `project-brief.md`.
+
+## File Template
+
+```markdown
+# Project Brief
+
+## Vision
+- [What the project is, who it's for, core value proposition]
+
+## Core Constraints
+- [Technical constraints, business constraints, immutable decisions]
+
+## Design Decisions
+- [Cross-feature decisions: API style, auth method, state management, etc.]
+
+## Key Requirements
+- [Details and preferences the user specifically emphasized]
+```
+
+## Update Rules
+
+- **First update**: Create the file with all four sections. Populate whichever sections have content; leave others with a single placeholder bullet `- (to be determined)`.
+- **Subsequent updates**: Use Edit tool to update only the changed section — do not rewrite the entire file.
+- Keep each bullet to **one sentence** — no paragraphs.
+- Total file size **must not exceed 500 words**. If approaching the limit, merge or condense existing bullets.
+- Language: match the user's language (Chinese or English).
+- Content is append/modify only — never delete bullets unless the user explicitly requests it.
+
+## Checkpoint
+
+Verified at **CP-AP-5.3**: Before CP-AP-6 (`feature-list.json` generation), `project-brief.md` must exist with the Vision section plus at least one other populated section (not placeholder bullets).
+
+## How the Pipeline Uses It
+
+`generate-bootstrap-prompt.py` reads `project-brief.md` and injects its content into the `{{PROJECT_BRIEF}}` section of every bootstrap prompt (tier1/tier2/tier3). The section appears between Acceptance Criteria and Dependencies, with this framing:
+
+> "Distilled summary of the project's key requirements and design decisions, captured during planning. When your feature implementation touches any of these key points, ensure alignment."
+
+If the file does not exist, the placeholder is replaced with `(No project brief available)` — the pipeline runs normally without it.
+
+## Examples
+
+### Minimal Brief (early in conversation)
+
+```markdown
+# Project Brief
+
+## Vision
+- B2B SaaS platform for restaurant inventory management, targeting small-to-medium restaurant chains
+
+## Core Constraints
+- (to be determined)
+
+## Design Decisions
+- (to be determined)
+
+## Key Requirements
+- Must support offline mode for kitchen tablets with unreliable WiFi
+```
+
+### Mature Brief (after several rounds of discussion)
+
+```markdown
+# Project Brief
+
+## Vision
+- B2B SaaS platform for restaurant inventory management, targeting small-to-medium restaurant chains (5-50 locations)
+- Core value: reduce food waste by 30% through predictive ordering
+
+## Core Constraints
+- Must work on iPad Safari (no native app)
+- Backend must be deployable to customer's own cloud (multi-tenant but self-hostable)
+- Budget: MVP in 4 weeks
+
+## Design Decisions
+- RESTful API with JWT auth; no GraphQL
+- Use Supabase for auth + database (PostgreSQL)
+- TailwindCSS + shadcn/ui for all frontend components
+- All monetary values stored as integers (cents) to avoid floating point
+
+## Key Requirements
+- Dashboard must load in under 2 seconds on 3G connection
+- Supplier integration API must support webhook callbacks
+- All user-facing text in Simplified Chinese; admin panel in English
+```

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

@@ -148,6 +148,8 @@ Ask the user: "Is this summary accurate? Any details to add?"
 
 **Goal**: Locate affected code, identify root cause, classify severity.
 
+> **Reference**: This phase incorporates the logic of `prizmkit-tool-error-triage`. Classify error into: Runtime / Network / Auth / Data / Resource / Logic / Config / External. Check `.prizm-docs/` TRAPS for known patterns first. If a TRAPS match is found, use documented solution and reference the specific `.prizm-docs/` entry. If no match, trace the call chain from the stack frame to identify root cause from first principles.
+
 1. **Read project context**: `.prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
 2. **Locate affected code**: read the files mentioned in the error/stack trace or identified during diagnosis
 3. **Check known issues**: search `.prizm-docs/` TRAPS sections for matching patterns
@@ -169,6 +171,8 @@ Ask the user: "Is this summary accurate? Any details to add?"
 
 **Goal**: Create a failing test that proves the bug exists.
 
+> **Reference**: This phase incorporates the logic of `prizmkit-tool-bug-reproducer`. For API bugs: generate curl/HTTP request sequence with assertions. For UI bugs: generate step-by-step interaction guide. For logic bugs: generate unit test (arrange/act/assert). For data bugs: generate seed data + query sequence. The reproduction must FAIL with current behavior and be designed to PASS after the fix is applied — making it a regression guard.
+
 1. **Write a reproduction test** that demonstrates the bug:
    - Name: `<module>.test.ts` → add a test case named `should handle <bug scenario>`
    - The test captures the exact failure condition

package/bundled/skills/bug-planner/SKILL.md

@@ -44,7 +44,7 @@ Launch the interactive bug planning process through 4 phases.
 1. **Identify project**: Read project name and description from existing `feature-list.json` or ask user
 2. **Identify tech stack**: Read from `.prizmkit/config.json` `tech_stack` (preferred), then `feature-list.json` global_context, then `.prizm-docs/root.prizm`. Only ask user if none of these sources provide tech stack info.
 3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
-4. **Clarify context** — apply `/prizmkit-clarify` principles: if the project context, affected systems, or bug scope is unclear, ask questions one at a time until you fully understand the environment. No limit on rounds or number of questions.
+4. **Clarify context** — if the project context, affected systems, or bug scope is unclear, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand the environment. No limit on rounds or number of questions.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
@@ -117,7 +117,7 @@ ALERT: Error rate spike: 500 errors/min on /api/login endpoint
 - Verification type (suggest `automated` by default, ask user)
 - Acceptance criteria (auto-suggest based on description, user can edit)
 
-**Per-bug clarification** — apply `/prizmkit-clarify` principles: if the bug's root cause, reproduction steps, expected behavior, or scope is unclear from the provided information, ask focused questions until the bug is fully understood. Do not finalize a bug entry with ambiguous details. No limit on the number of questions per bug.
+**Per-bug clarification** — if the bug's root cause, reproduction steps, expected behavior, or scope is unclear from the provided information, ask focused questions one at a time (cite the unclear point, give a recommended answer with rationale) until the bug is fully understood. Do not finalize a bug entry with ambiguous details. No limit on the number of questions per bug.
 
 **Multiple bugs per session**: After each bug, ask "Any more bugs to add? (yes/no)"
 

package/bundled/skills/dev-pipeline-launcher/SKILL.md

@@ -42,7 +42,7 @@ Three execution modes are available. The user chooses one before configuring oth
 **Do NOT use this skill when:**
 - User wants to plan features (use `app-planner` instead)
 - User wants to implement a single feature manually within current session (use `prizmkit-implement`)
-- User wants to define specs/plan (use `prizmkit-specify` / `prizmkit-plan`)
+- User wants to define specs/plan (use `prizmkit-plan`)
 
 ### Prerequisites
 

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

@@ -10,47 +10,27 @@ PrizmKit is a comprehensive, independent AI development toolkit that covers the
 
 ## When to Use the Full Workflow
 
-**Use full workflow (specify -> plan -> implement):**
-- Difficult features or user-facing capabilities
-- Multi-file coordinated changes
-- Architectural decisions
-- Data model or API changes
-
-The full workflow generates spec, plan, and task artifacts that create a traceable record of what was built and why — this matters for future maintainability and AI context loading.
-
-**Use fast path (plan → implement → commit):**
-- Bug fixes with clear root cause
-- Simple refactors (rename, extract)
-- Documentation-only changes
-- Test additions for existing code
-
-The fast path skips specify and analyze but still generates a simplified plan.md (with Tasks section) so that implement has a task list to follow.
-
-For fast-path changes, you can directly generate a simplified plan.md, then use implement and commit commands.
-
-## Workflow Example
-
-**Full workflow** for adding a user avatar upload feature:
+**Full workflow** — forms a continuous loop for feature development:
 ```
-/prizmkit-specify    → writes .prizmkit/specs/001-avatar-upload/spec.md
-/prizmkit-plan       → writes plan.md with tasks (architecture, data model, API, UI)
-/prizmkit-analyze    → checks spec↔plan consistency, finds gaps
-/prizmkit-implement  → executes tasks in order, marks [x] as done
-/prizmkit-code-review → diagnoses issues + produces Fix Instructions
-/prizmkit-retrospective → syncs .prizm-docs/ with code changes
-/prizmkit-deploy     → generates/updates DEPLOY.md with deployment procedures
-/prizmkit-committer  → commits feat(avatar): add upload
+read .prizm-docs → plan (specify + design + tasks) → implement → code-review → retrospective → committer
+                      ↑                                                              ↓
+                      └────────────────────── next feature ←─────────────────────────┘
 ```
+- New features or user-facing capabilities
+- Multi-file coordinated changes
+- Architectural decisions, data model or API changes
 
-**Fast path** for fixing a null pointer bug:
+Each cycle produces spec, plan, and task artifacts that create a traceable record of what was built and why — `.prizm-docs/` stays in sync through retrospective, so the next cycle starts with up-to-date context.
+
+**Fast path** — for small, well-scoped changes:
 ```
-/prizmkit-plan       → "fix null check in UserService.getAvatar()" (simplified plan.md)
-/prizmkit-implement  → executes tasks from plan.md
-/prizmkit-committer  → commits fix(user): handle null avatar gracefully
+/prizmkit-plan → /prizmkit-implement → /prizmkit-committer
 ```
+- Bug fixes with clear root cause
+- Simple refactors (rename, extract)
+- Documentation-only changes, test additions for existing code
 
-### Fast Path Commands
- `/prizmkit-plan` → `/prizmkit-implement` → `/prizmkit-committer`
+Fast path skips specify/analyze/review but still generates a simplified plan.md so implement has a task list to follow.
 
 ### Bug Fix Documentation Policy
 
@@ -69,16 +49,14 @@ PrizmKit produces two complementary knowledge layers:
 
 ```
 .prizm-docs/           → Architecture Index (structure, interfaces, dependencies, traps, rules, decisions)
-.prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → code(implement))
+.prizmkit/specs/       → Feature artifacts (spec → plan → implement → review cycle)
 ```
 
 ## Core Skill Reference
 
 | Skill | Purpose | Trigger Phrases |
 |-------|---------|-----------------|
-| `/prizmkit-specify` | Natural language → structured spec.md | "specify", "new feature", "I want to add..." |
-| `/prizmkit-clarify` | Resolve spec ambiguities interactively | "clarify", "refine spec", "resolve ambiguities" |
-| `/prizmkit-plan` | Spec → plan.md with architecture + tasks | "plan", "architect", "break it down", "create tasks" |
+| `/prizmkit-plan` | Specify + plan: natural language → spec.md → plan.md + tasks | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
 | `/prizmkit-analyze` | Cross-doc consistency check (read-only) | "analyze", "check consistency", "validate spec" |
 | `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
 | `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
@@ -108,15 +86,8 @@ Interactive installer auto-detects your platform and guides you through configur
 **Option 2: Claude Code Plugin**
 Install the `prizmkit` plugin via Claude Code's plugin system, then run `/prizmkit-init`.
 
-**Option 3: Manual Install (CodeBuddy)**
-```bash
-python3 ${SKILL_DIR}/scripts/install-prizmkit.py --target <project-skills-dir>
-```
-
 ## Hook / Rules Configuration
 
-Both CodeBuddy and Claude Code use unified commands for automatic doc updates and commit enforcement.
-Hooks and rules are configured automatically by `prizmkit-init`. See:
-- The commit hook template is configured automatically during `prizmkit-init`
+Hooks and rules are configured automatically by `prizmkit-init`:
 - `assets/project-memory-template.md` for the project memory template
 - The init skill creates `prizm-documentation.md` and `prizm-commit-workflow.md` rules

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

@@ -35,6 +35,6 @@ Not every change needs the full spec -> plan workflow. Use fast path for:
 - Documentation-only changes, test additions for existing code
 - Fast path: `/prizmkit-plan` (simplified) → `/prizmkit-implement` → `/prizmkit-committer`
 
-Use the full workflow (/prizmkit-specify -> /prizmkit-plan -> /prizmkit-analyze -> /prizmkit-implement) for:
+Use the full workflow (/prizmkit-plan -> /prizmkit-analyze -> /prizmkit-implement) for:
 - New features, multi-file coordinated changes, architectural decisions, data model or API changes
 <!-- PRIZMKIT:END -->

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

@@ -16,7 +16,7 @@ Perform a non-destructive cross-artifact consistency and quality analysis across
 
 | Required Artifact | Directory | Check | If Missing |
 |---|---|---|---|
-| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists | Run `/prizmkit-specify` |
+| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists | Run `/prizmkit-plan` |
 | `plan.md` (with Tasks section) | `.prizmkit/specs/###-feature-name/` | File exists + has Tasks section | Run `/prizmkit-plan` |
 
 ## Operating Constraints
@@ -35,7 +35,7 @@ Derive absolute paths:
 - SPEC = `.prizmkit/specs/###-feature-name/spec.md`
 - PLAN = `.prizmkit/specs/###-feature-name/plan.md` (must include a Tasks section)
 
-Abort with an error message if spec.md or plan.md is missing — instruct the user to run the missing prerequisite command (`/prizmkit-specify` or `/prizmkit-plan`).
+Abort with an error message if spec.md or plan.md is missing — instruct the user to run `/prizmkit-plan`.
 
 ### Step 2: Load Artifacts (Progressive Disclosure)
 
@@ -161,7 +161,7 @@ At end of report, output a concise Next Actions block:
 - If CRITICAL issues exist: **Recommend resolving before `/prizmkit-implement`**
 - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
 - Provide explicit command suggestions:
-  - "Run `/prizmkit-specify` to refine requirements"
+  - "Run `/prizmkit-plan` to refine requirements"
   - "Run `/prizmkit-plan` to adjust architecture or tasks"
   - "Edit plan.md Tasks section to add coverage for requirement X"
   - "Proceed to `/prizmkit-implement`" (if clean)
@@ -194,7 +194,7 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t
 | E1 | Coverage Gap | HIGH | spec.md §FR-3 | "User can export reports as PDF" has no corresponding task in plan.md Tasks section | Add export task to Phase 3 of plan.md |
 ```
 
-**HANDOFF:** `/prizmkit-implement` (if clean) or `/prizmkit-specify` / `/prizmkit-plan` (if issues found)
+**HANDOFF:** `/prizmkit-implement` (if clean) or `/prizmkit-plan` (if issues found)
 
 ## Loop Protection
 

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

@@ -16,7 +16,7 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 ### 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-specify`
+- User wants to start a feature → skip init if already initialized, go to `/prizmkit-plan`
 
 ### Error Handling
 - If `.prizm-docs/` already exists: ask user if they want to reinitialize (overwrites) or update (preserves)
@@ -179,8 +179,8 @@ Tech stack detected:
 Saved to: `.prizmkit/config.json` → `tech_stack` field
 
 Include platform-specific guidance:
-- CodeBuddy: "Use `/prizmkit-specify` to start your first feature"
-- Claude Code: "Use `/prizmkit-specify` to start your first feature"
+- CodeBuddy: "Use `/prizmkit-plan` to start your first feature"
+- Claude Code: "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:
@@ -239,7 +239,7 @@ 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-specify to start your first feature
+Next: Use /prizmkit-plan to start your first feature
 ```
 
 UPDATE SUPPLEMENT (runs after tech stack merge in Update mode):

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

@@ -1,137 +1,155 @@
 ---
 name: "prizmkit-plan"
-description: "Generate technical implementation plan and executable task breakdown from feature spec. Produces plan.md with architecture, data model, API contracts, and a Tasks section. Use this skill whenever the user wants to design how a feature will be built, break work into tasks, or think through architecture. Trigger on: 'plan', 'architect', 'how to build', 'design', 'break it down', 'break this into tasks', 'create tasks', 'implementation strategy', 'how should we implement'. Always use after /prizmkit-specify and before /prizmkit-implement. (project)"
+description: "Specify and plan features in one step. Transforms natural language into structured spec.md, then generates plan.md with architecture and executable tasks. Use this skill whenever the user wants to define a feature, write requirements, design implementation, or break work into tasks. Trigger on: 'specify', 'plan', 'new feature', 'I want to add...', 'I want to build...', 'architect', 'design', 'break it down', 'create tasks', 'how to build', 'let's add', 'feature idea'. Always use before /prizmkit-implement. Skip specify phase for bug fixes or simple refactors. (project)"
 ---
 
 # PrizmKit Plan
 
-Generate a comprehensive technical implementation plan from a feature specification. Produces plan.md with architecture approach, component design, data model, API contracts, testing strategy, risk assessment, and an executable Tasks section.
+Define WHAT to build, then design HOW to build it — in one continuous flow. Phase 0 produces `spec.md` (requirements), Phase 1-2 produce `plan.md` (architecture + tasks).
 
 ### When to Use
-- After `/prizmkit-specify` when ready to plan the implementation
-- User says "plan", "architect", "how to build", "design", "break it down", "create tasks"
-- Before `/prizmkit-implement` to create the task breakdown
-- When user wants to understand the full implementation approach before coding
+- New feature — user says "specify", "plan", "new feature", "I want to add..."
+- Before `/prizmkit-implement` — to create the spec + task breakdown
+- When a feature idea needs to go from concept to executable plan
 
 ### When NOT to Use
-- No input document exists yet (no spec.md, no refactor-analysis.md, no fix-plan.md) → run `/prizmkit-specify` or the appropriate upstream skill first
-- Simple bug fix or config change → use fast path (`/prizmkit-plan` with simplified output → `/prizmkit-implement` → `/prizmkit-committer`)
-- User just wants to explore/research → answer directly, no plan artifact needed
-
-**PRECONDITION:**
-
-| Mode | Required Artifact | Directory | Check | If Missing |
-|---|---|---|---|---|
-| **Feature** (default) | `spec.md` + `.prizm-docs/root.prizm` | `.prizmkit/specs/###-feature-name/` | File exists | Prompt: "No spec found — run `/prizmkit-specify` first?" |
-| **Refactor** | `refactor-analysis.md` | `.prizmkit/refactor/<refactor-slug>/` | File exists | Run upstream refactor workflow |
-| **Bugfix** | `fix-plan.md` or bug description from caller | `.prizmkit/bugfix/<BUG_ID>/` | File exists or caller-provided | Run `/bug-fix-workflow` |
-
-**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
-
-## Execution Steps
-
-**Phase 0 — Research:**
-1. Read the input document for requirements:
-   - **Feature mode**: Read `spec.md` for feature requirements
-   - **Refactor mode**: Read `refactor-analysis.md` for refactoring goals, scope boundary, and baseline tests
-   - **Bugfix mode**: Read bug description / `fix-plan.md` for reproduction steps and expected fix
-2. Load project context (use first available source):
-   - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read it for all context (Section 3 'Prizm Context' for docs, Section 4 'File Manifest' for code structure and interfaces). The context-snapshot consolidates project context into one read, saving significant tokens.
-   - Otherwise → read `.prizm-docs/root.prizm` and relevant `.prizm-docs/` L1/L2 docs for affected modules
+- 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
+
+## Execution
+
+### Phase 0: Specify (WHAT)
+
+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)
+
+**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), append `-MMDD` timestamp suffix for collision prevention
+   - If empty or doesn't exist, start at `001`
+4. Create directory: `.prizmkit/specs/###-feature-name-MMDD/`
+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
+   - `[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.
+   → Read `${SKILL_DIR}/references/clarify-guide.md` for question strategy and update rules.
+   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.
+
+### Phase 1: Design (HOW)
+
+**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).
+
+**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
 3. Resolve any remaining `[NEEDS CLARIFICATION]` by proposing solutions
-4. Research technical approach based on project's tech stack
-
-**Phase 1 — Design:**
-5. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
-   - Architecture approach (how feature fits into existing structure)
-   - Component design (new/modified components)
-   - Data model changes (new entities, modified schemas)
-   - **Database design gate** (when feature involves DB changes):
-     1. Read ALL existing schema/migration/model files to understand current conventions (naming, constraints, relationships, ID strategy, timestamps)
-     2. Ensure new schema follows existing patterns — do NOT introduce new conventions unless explicitly justified
-     3. Verify every new table/field has: purpose, type, constraints, and relationship to existing entities
-     4. If any data model decision is uncertain → mark as `[NEEDS CLARIFICATION]` and resolve via `/prizmkit-clarify` BEFORE generating the Tasks section
-     5. **RULE**: The Tasks section MUST NOT be generated until all `[NEEDS CLARIFICATION]` items in Data Model are resolved. Unresolved DB design leads to implementation rework that is expensive to fix after code is written.
-   - Interface design (API endpoints, request/response formats, module interfaces)
-   - Integration points (external services, internal modules)
-   - Testing strategy (unit, integration, e2e)
-   - Risk assessment
-6. Cross-check plan against spec: every user story should map to plan components — unmapped stories mean the plan has coverage gaps that will surface during implementation
-7. Check alignment with project rules from `.prizm-docs/root.prizm` RULES section — violating project rules causes CRITICAL findings in the analyze phase
-8. **Deployment strategy check:**
-   - Read `.prizmkit/config.json` `deploy_strategy` field (if `config.json` does not exist, treat as "no deploy_strategy")
-   - Compare tech stack used in this plan (from Architecture Approach, Integration Points, Data Model) against the stored strategy
-   - **No `deploy_strategy` in config** → first time: ask user for deployment approach (e.g. Docker, Vercel, static hosting, traditional server, cloud platform, etc.) → write to `config.json` as `deploy_strategy` object with `"_user_confirmed": true`. If `config.json` does not exist, create `.prizmkit/` directory and `config.json` with the `deploy_strategy` field (preserve any existing fields if the file already exists).
-   - **`deploy_strategy` exists, no new tech stack** → skip (no question asked)
-   - **`deploy_strategy` exists, new tech stack detected** (e.g. plan introduces Redis, message queue, new database) → ask user only about the deployment approach for the new component → merge into existing `deploy_strategy`
-   - Store format in `config.json`:
-     ```json
-     {
-       "deploy_strategy": {
-         "primary": "docker",
-         "components": {
-           "app": "Docker container → AWS ECS",
-           "database": "RDS PostgreSQL",
-           "cache": "ElastiCache Redis"
-         },
-         "notes": "user-provided context about their deployment",
-         "_user_confirmed": true
-       }
-     }
-     ```
-   - This step is **skipped entirely in fast-path mode** (bug fixes / simple refactors do not affect deployment)
-
-**Phase 2 — Task Generation:**
-9. Ask user for implementation strategy (or infer from context): MVP-first / Incremental / Parallel
-10. Append `## Tasks` section to `plan.md` using the tasks template at the end of `${SKILL_DIR}/assets/plan-template.md`:
-    - Organized by 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`
-    - `[P]` marker for tasks that can run in parallel within their phase
-    - Checkpoint tasks between phases for validation
-11. Verify coverage and traceability:
-    - Every user story maps to at least one task — orphan stories become orphan features
-    - Every task references a target file path — pathless tasks leave implementers guessing where to write code
-    - Risk assessment includes at least one risk with mitigation — helps the implementer prepare for known challenges
-12. Output: `plan.md` path, summary of design decisions, and task count
-
-**Task ID Conventions:**
-- Task IDs use zero-padded numbering: `[T-001]`, `[T-010]`, `[T-100]` — this ensures consistent sorting and visual alignment
-- Each user story section should be independently testable — this enables incremental verification during implementation
-
-**HANDOFF:** `/prizmkit-analyze` or `/prizmkit-implement`
+4. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
+   - Architecture approach, component design
+   - 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
+6. Check alignment with `.prizm-docs/root.prizm` RULES section
+7. **Deployment strategy check:**
+   - 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)
+
+### Phase 2: Task Generation
+
+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`
+   - 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
+
+**HANDOFF:** `/prizmkit-implement`
+
+## Handling Vague Inputs
+
+When the user's description is vague:
+1. Extract what IS clear and write it into the spec
+2. Mark ambiguous parts with `[NEEDS CLARIFICATION]` + recommended default
+3. Auto-clarification (Phase 0, step 9) resolves interactively before planning
+
+Never block progress — always produce a usable spec, even with open questions.
 
 ## Example
 
-**Input:** spec.md for "User Avatar Upload" feature
+**Input:** "I want users to upload avatars"
 
-**Output:** plan.md excerpt:
+**Phase 0 output:** `.prizmkit/specs/003-user-avatar-0402/spec.md`
+```markdown
+# Feature: User Avatar Upload
+## User Stories
+### US-1: Upload Avatar
+As a registered user, I want to upload a profile picture,
+so that other users can visually identify me.
+**Acceptance Criteria:**
+- Given I am on my profile page
+- When I select an image file and click upload
+- Then my avatar is updated and visible across the platform
+## Scope
+- **In scope:** Upload, display, remove avatar; image format validation
+- **Out of scope:** Image cropping/editing, avatar history
+```
+
+**Phase 1-2 output:** `plan.md` excerpt:
 ```markdown
 ## Architecture Approach
 Extend existing user profile module. Add S3 integration for file storage.
-Reuse existing auth middleware for upload endpoint protection.
 
 ## Tasks
-
-### Phase 1: Data Layer (T-010~T-019)
+### 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
-- [ ] [T-012] CP: Data layer checkpoint — run migrations + unit tests
-
-### Phase 2: API [P] (T-100~T-109)
+### Phase: API [P] (T-100~T-109)
 - [ ] [T-100] [P] [US-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
-- [ ] [T-101] [P] [US-2] DELETE /api/avatar endpoint — file: src/routes/avatar.ts
-- [ ] [T-102] CP: API checkpoint — integration tests pass
 ```
 
-## Template
+## Templates
 
-The plan template is located at `${SKILL_DIR}/assets/plan-template.md`.
+- Spec template: `${SKILL_DIR}/assets/spec-template.md`
+- Plan template: `${SKILL_DIR}/assets/plan-template.md`
 
 ## Output
 
-Output directory depends on mode:
-- **Feature mode**: `.prizmkit/specs/###-feature-name/plan.md`
-- **Refactor mode**: `.prizmkit/refactor/<refactor-slug>/plan.md`
-- **Bugfix mode**: `.prizmkit/bugfix/<BUG_ID>/plan.md`
-
-The plan.md includes architecture, component design, data model, interface design, testing strategy, risk assessment, and Tasks section.
+| 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` |

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

@@ -38,8 +38,7 @@
 - [ ] All fields have explicit nullability (NOT NULL or nullable)
 
 ### Unresolved Questions
-<!-- NONE — all DB design questions must be resolved before proceeding to Tasks -->
-<!-- If any remain, run /prizmkit-clarify to resolve them first -->
+<!-- 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]