prizmkit 1.1.12 → 1.1.14

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.12",
-  "bundledAt": "2026-04-09T03:04:37.064Z",
-  "bundledFrom": "231d62a"
+  "frameworkVersion": "1.1.14",
+  "bundledAt": "2026-04-09T16:24:45.739Z",
+  "bundledFrom": "b887e13"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.12",
+  "version": "1.1.14",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

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

@@ -70,25 +70,57 @@ Do NOT use this skill when:
    - User wants to explore ideas before committing → read `${SKILL_DIR}/references/brainstorm-guide.md`
    - During brainstorm Phase C → also read `${SKILL_DIR}/references/red-team-checklist.md`
 
-3. **Project conventions check** — after Intent Confirmation, before brainstorm or vision work:
+3. **Project conventions discovery** — after Intent Confirmation, before brainstorm or vision work:
    → Read `CLAUDE.md` / `CODEBUDDY.md` and check for `### Project Conventions` section
-   → If section exists and all conventions are answered → skip silently
-   → If section is missing or incomplete → ask the following conventions as a single batched prompt:
-     - **UI Display Language** (`ui_language`): Primary language for the app's UI (e.g., English, 中文, 日本語). If non-English, confirm whether ALL UI text should use that language.
-     - **Multi-Language Support** (`i18n`): Whether i18n is needed. If yes, which target languages? If enabled, note i18n infrastructure early in dependency graph.
-     - **Date/Time/Currency**: Date format (YYYY-MM-DD, MM/DD/YYYY, etc.), timezone strategy (UTC storage + local display, user-selected, server only), currency format (if applicable).
-     - **Code & Git Language**: Language for code comments and git commit messages (default: English for both).
+   → If section exists and covers the project well → skip silently
+   → If section is missing or incomplete → run the **AI-driven convention discovery** below:
+
+   **Do NOT follow any fixed checklist.** Every project is different. You must analyze the project first, then reason about what system-level conventions this specific project needs.
+
+   **Step 1: Analyze the project**
+   - Read tech stack, dependencies, existing code, config files, README, any existing style guides or linter configs
+   - For brownfield: also read actual source code patterns (naming, file structure, error handling, etc.)
+   - For greenfield: use the user's stated goals and intended tech stack
+
+   **Step 2: Reason about what conventions matter for THIS project**
+   Think about what decisions, if left unstandardized, would cause inconsistency as the project grows. Consider all dimensions relevant to the project — these might include (but are NOT limited to):
+   - Language and localization choices
+   - Code style and naming patterns
+   - Architecture and communication patterns
+   - Data format and storage decisions
+   - Security and auth approaches
+   - UI/UX patterns
+   - Testing strategies
+   - Deployment and environment patterns
+   - ...anything else you observe that needs a project-level decision
+
+   The point is: YOU decide what's relevant based on what you see. A Next.js SaaS app needs completely different conventions than a Python data pipeline or a Go microservice.
+
+   **Step 3: Present findings as two groups**
+   > Based on analyzing your project, here are the system-level conventions I recommend establishing:
+   >
+   > **Already decided** (detected from your codebase):
+   > - [convention]: [value] (source: [where you found it])
+   > - [convention]: [value] (source: [where you found it])
+   >
+   > **Need your input** (would impact consistency if left unaddressed):
+   > **1. [Convention name]** — [why this matters for your project]
+   > [A] option  [B] option  [C] option
+   >
+   > **2. [Convention name]** — [why this matters for your project]
+   > [A] option  [B] option
+   >
+   > Anything I missed that you'd like to standardize?
+
+   **Rules:**
+   - Every proposed convention must be justified by something you observed in the project — explain WHY it matters
+   - Auto-confirm anything already evident from the codebase (show as "detected", let user override)
+   - No fixed upper/lower limit on count — propose as many as the project genuinely needs, but don't pad with irrelevant ones
+   - Always end with "Anything I missed?" to let the user add things you didn't think of
+   - Present options (not open-ended questions) for each convention that needs input
+
    → Save answers to `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
-   → Example output:
-     ```markdown
-     ### Project Conventions
-     - UI language: 中文
-     - i18n: disabled
-     - Date format: YYYY-MM-DD, timezone: UTC storage + local display
-     - Currency: CNY ¥
-     - Code comments: English
-     - Git commits: English
-     ```
+   → Output format will naturally vary per project — that is the intended behavior
 
 4. **Project brief accumulation** — throughout all interactive phases:
    → Read `${SKILL_DIR}/references/project-brief-guide.md` for template and rules
@@ -112,25 +144,60 @@ Note:
 - This skill does **not** create `.prizmkit/config.json` directly.
 - Creation/update is handled by bootstrap/init flows (e.g., `prizmkit-init`, `dev-pipeline/scripts/init-dev-team.py`).
 
-## Intent Confirmation (Mandatory First Step)
+## Interaction Style (Hard Rule)
+
+**ALL decision points MUST use numbered/lettered options.** Never ask open-ended questions when the answer can be structured as a choice. This applies to:
+- Intent confirmation
+- Project conventions
+- Tech stack selection
+- Architecture decisions
+- Handoff recommendations
+- Session exit gates
+
+**Format**: Present options as a numbered or lettered list. The user picks a number/letter. Include a recommended default where appropriate.
 
-After initial greeting, confirm the user's deliverable intent:
+Example:
+> What would you like to do next?
+>
+> **[A] Produce a project plan** — capture vision, stack, constraints → project-brief.md (recommended)
+> **[B] Explore ideas first** — brainstorm freely before committing to a plan
+> **[C] Skip to feature planning** — if you already know what to build
 
-1. **Ask explicitly**:
-   - "Is the goal to produce a project plan for eventual pipeline execution, or just explore ideas first?"
+**When gathering information** (e.g., target users, problem statement), use a hybrid approach:
+- If common answers exist → offer options + "Other" choice
+- If truly open-ended (e.g., "describe your app idea") → ask directly, but follow up with option-based clarifications
 
-2. **Route by answer**:
-   - **"Produce a plan"** → Continue to Core Workflow. Set session goal = `produce`.
-   - **"Just explore ideas"** → Enter **Exploration Mode**:
-     - Run project conventions check first
-     - Load `${SKILL_DIR}/references/brainstorm-guide.md` and follow its structured ideation process (Phases A-D)
-     - Brainstorm Phase D output serves as the Vision Summary (CP-AP-2)
-     - After brainstorm completes, ask: "Ideas are taking shape. Ready to hand off to `feature-planner` for feature decomposition, or continue refining?"
-     - If ready → proceed to Phase 2 (constraints + frontend design check if applicable) then handoff
-     - If not ready → continue exploring, or save draft to `.prizmkit/planning/` and exit
-     - **Checkpoints in explore mode**: CP-AP-0 (required), CP-AP-1 (required), CP-AP-2 (from brainstorm output), CP-AP-3 (only if user proceeds to Phase 2), CP-AP-4 and CP-AP-5 (only if user transitions to produce mode)
+## Intent Confirmation (Mandatory First Step)
 
-3. **Session goal tracking**: Track the intent (`produce` or `explore`) throughout the session. If `explore`, always re-prompt before ending.
+After initial greeting, present options:
+
+> Welcome to App Planner! What would you like to do?
+>
+> **[A] Produce a project plan** — define vision, tech stack, and constraints → generates project-brief.md for pipeline use (recommended)
+> **[B] Explore ideas first** — brainstorm and refine ideas before committing to a plan
+> **[C] Generate project context only** — for an existing project that needs a project brief without full planning
+
+Route by answer:
+- **A** → Continue to Core Workflow. Set session goal = `produce`.
+- **B** → Enter **Exploration Mode**:
+  - Run project conventions check first
+  - Load `${SKILL_DIR}/references/brainstorm-guide.md` and follow its structured ideation process (Phases A-D)
+  - Brainstorm Phase D output serves as the Vision Summary (CP-AP-2)
+  - After brainstorm completes, present options:
+    > Ideas are taking shape. What's next?
+    >
+    > **[A] Proceed to feature decomposition** — hand off to feature-planner
+    > **[B] Continue refining** — keep brainstorming
+    > **[C] Save draft & exit** — save progress to .prizmkit/planning/
+  - **Checkpoints in explore mode**: CP-AP-0 (required), CP-AP-1 (required), CP-AP-2 (from brainstorm output), CP-AP-3 (only if user proceeds to Phase 2), CP-AP-4 and CP-AP-5 (only if user transitions to produce mode)
+- **C** → Enter **Quick Context Mode** (brownfield only):
+  - Run Project State Detection → if greenfield, redirect to option A
+  - Proactively scan the project (same as brownfield behavior)
+  - Generate project-brief.md from inferred context
+  - Skip extensive brainstorming and constraint phases
+  - Present brief for user confirmation → write → done
+
+Session goal tracking: Track the intent (`produce`, `explore`, or `quick_context`) throughout the session. If `explore`, always re-prompt before ending.
 
 ## Project State Detection (after Intent Confirmation)
 
@@ -153,6 +220,40 @@ Proceed with the standard Core Workflow — ask all questions from scratch.
 
 When an existing project is detected:
 
+**Step 1: Prerequisite Check (Mandatory)**
+
+Before ANY planning work, check if AI-essential project context files exist:
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `.prizm-docs/root.prizm` | Project architecture context for AI | exists / missing |
+| `.prizmkit/config.json` | Tech stack + runtime config | exists / missing |
+| `.prizmkit/plans/project-brief.md` | Product vision checklist | exists / missing |
+
+**If ANY are missing**, present this recommendation:
+
+> I detected this is an existing project, but some AI context files are missing:
+>
+> | File | Status |
+> |------|--------|
+> | `.prizm-docs/` | ❌ missing |
+> | `.prizmkit/config.json` | ❌ missing |
+> | `.prizmkit/plans/project-brief.md` | ❌ missing |
+>
+> These files help AI understand your project structure, tech stack, and goals — making planning much more effective.
+>
+> **[A] Run project init first** — invoke `prizmkit-init` to scan your codebase and generate these files, then return to planning (recommended)
+> **[B] Continue without init** — I'll scan the project manually during this session (less thorough)
+> **[C] I'll set these up later** — proceed with planning using only what's available
+
+- **A** → Invoke `prizmkit-init`, then resume app-planner from where it left off
+- **B** → Continue with Step 2 below (manual scan)
+- **C** → Continue with Step 3, skip scanning
+
+**Step 2: Proactive Project Scanning**
+
+Do NOT ask the user to describe their project — read it yourself first:
+
 1. **Scan project structure** to understand the codebase layout:
    ```bash
    find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
@@ -166,19 +267,32 @@ When an existing project is detected:
    - `.prizmkit/config.json` → previously detected tech stack
    - `.prizm-docs/root.prizm` → existing architecture context
 
-3. **Present inferred summary** to the user:
-   > "I see this is a [framework] project using [language] with [key dependencies]. Here's what I inferred about the project: [summary]. Is this correct? Anything to add or change?"
+3. **Read key source files** (entry points, main routes, core models) to understand what the project actually does — don't rely solely on metadata.
+
+**Step 3: Present inferred summary with confirmation options**
+
+> Based on my analysis of your codebase:
+>
+> **Project**: [name] — [inferred description]
+> **Tech Stack**: [framework] + [language] + [key dependencies]
+> **Key Features Found**: [list 3-5 detected capabilities]
+> **Architecture**: [e.g., monolithic, microservices, serverless]
+>
+> **[A] This looks correct** — proceed with planning
+> **[B] Mostly correct, with changes** — I'll note corrections
+> **[C] This is off** — let me describe the project
+
+**Step 4: Pre-fill and focus**
 
-4. **Pre-fill where possible** — skip questions already answerable from the codebase:
-   - Phase 2 tech stack selection → largely pre-filled from dependencies
-   - Vision/problem statement → inferred from README or package description (user confirms)
-   - Existing features → note them as `[x]` items in project brief
+- Phase 2 tech stack selection → largely pre-filled from dependencies
+- Vision/problem statement → inferred from README or package description (user confirms)
+- Existing features → note them as `[x]` items in project brief
 
-5. **Focus remaining questions** on what CANNOT be inferred:
-   - Target users and core value proposition
-   - Future direction and planned capabilities
-   - Non-functional requirements (performance, scale, security)
-   - Design direction (for frontend projects)
+**Focus remaining questions** (as options where possible) on what CANNOT be inferred:
+- Target users and core value proposition
+- Future direction and planned capabilities
+- Non-functional requirements (performance, scale, security)
+- Design direction (for frontend projects)
 
 ## Core Workflow
 
@@ -186,11 +300,18 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
 
 ### Interactive Phases
 1. Clarify business goal and scope
-   1.1 Confirm deliverable intent (→ Intent Confirmation)
-   1.2 **Requirement clarification** — for ANY unclear aspect of the user's vision, goals, target users, or scope, ask questions one at a time until fully understood. No limit on rounds. Do not proceed to Phase 2 with unresolved ambiguities.
+   1.1 Confirm deliverable intent (→ Intent Confirmation — option-based)
+   1.2 **Requirement clarification** — for ANY unclear aspect of the user's vision, goals, target users, or scope, use option-based questions where possible. When common patterns exist, present them as choices. Only use open-ended questions for truly unique input (e.g., "describe your app idea"). Follow up with option-based clarifications.
 2. Confirm constraints and tech assumptions
-   2.1 Tech stack selection — use `${SKILL_DIR}/assets/app-design-guide.md` §2 decision matrix
-   2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, ask user if they want to establish design direction via `${SKILL_DIR}/references/frontend-design-guide.md`
+   2.1 Tech stack selection — use `${SKILL_DIR}/assets/app-design-guide.md` §2 decision matrix. Present as options:
+       > **Frontend framework?**
+       > [A] Next.js (recommended)  [B] Nuxt 3  [C] SvelteKit  [D] Other
+   2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, present options:
+       > No UI/UX design docs found. Would you like to:
+       >
+       > **[A] Establish design direction now** — guided questions about style, layout, color
+       > **[B] Skip for now** — decide during implementation
+       > **[C] I have external designs** — link or describe them
 3. Capture architecture decisions and finalize project brief
 4. Hand off to `feature-planner` for feature decomposition
 
@@ -236,16 +357,25 @@ Activate when ALL true:
 
 When the session appears to be ending:
 1. **Remind**: "You set out to produce a project plan but `.prizmkit/plans/project-brief.md` isn't complete yet."
-2. **Offer 3 options**:
-   - **(a) Continue to completion**
-   - **(b) Save draft & exit** — write current progress as draft to `.prizmkit/planning/`
-   - **(c) Abandon** — exit without saving
+2. **Present options**:
+   > **[A] Continue to completion** — finish the project brief
+   > **[B] Save draft & exit** — write current progress as draft to `.prizmkit/planning/`
+   > **[C] Abandon** — exit without saving
 
 ## Handoff to feature-planner
 
-After all checkpoints pass, present a summary and recommend next steps:
+After all checkpoints pass, present a summary and offer next steps as options:
 
 1. **Summary**: List captured vision, tech stack, constraints, architecture decisions, and project brief status
-2. **Primary recommendation**: Invoke `feature-planner` to decompose the application into features and generate `.prizmkit/plans/feature-list.json` (schema: `dev-pipeline-feature-list-v1`, uses `project_name` field for the app name)
-3. **Alternative**: If the user wants to continue refining the vision or constraints, stay in app-planner
-4. **Artifacts produced**: List files written (`.prizmkit/plans/project-brief.md`, project conventions and architecture decisions in `CLAUDE.md` / `CODEBUDDY.md`)
+2. **Present options**:
+   > Planning complete! Here's what was captured:
+   > - Tech stack: [summary]
+   > - Project brief: `.prizmkit/plans/project-brief.md` ([N] items)
+   > - Conventions: saved to `CLAUDE.md` / `CODEBUDDY.md`
+   >
+   > **What's next?**
+   >
+   > **[A] Proceed to feature decomposition** — invoke `feature-planner` to break down features into `.prizmkit/plans/feature-list.json` (recommended)
+   > **[B] Continue refining** — stay in app-planner to adjust vision or constraints
+   > **[C] Done for now** — exit with artifacts saved
+3. **Artifacts produced**: List files written (`.prizmkit/plans/project-brief.md`, project conventions and architecture decisions in `CLAUDE.md` / `CODEBUDDY.md`)

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

@@ -29,7 +29,7 @@ User says:
 ```
 feature-workflow <idea / requirements>
    │
-   ├── Phase 1: Brainstorm → deep interactive Q&A until requirements are crystal clear
+   ├── Phase 1: Brainstorm → collect materials → parallel deep read → discuss requirements
    │
    ├── Phase 2: Plan → feature-planner → .prizmkit/plans/feature-list.json
    │
@@ -42,7 +42,7 @@ feature-workflow <idea / requirements>
 
 | Phase | Action | Result |
 |-------|--------|--------|
-| 1 | **Brainstorm** — interactive Q&A with user | Fully clarified requirements document |
+| 1 | **Brainstorm** — collect reference materials, parallel deep read code & docs, discuss requirements grounded in real context | Fully clarified requirements document |
 | 2 | Call `feature-planner` with clarified requirements | `.prizmkit/plans/feature-list.json` with N features |
 | 3 | Call `feature-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
 | 4 | Monitor progress | Status updates, completion report |
@@ -100,7 +100,7 @@ When user says "add features to existing project" or the project already has fea
 
 ## Phase 1: Brainstorm — Deep Requirement Clarification
 
-**Goal**: Through interactive Q&A, transform the user's rough idea into fully clarified, implementation-ready requirements. This phase is the foundation for high-quality code generation — vague requirements produce vague code.
+**Goal**: Through interactive Q&A and deep context reading, transform the user's rough idea into fully clarified, implementation-ready requirements. This phase is the foundation for high-quality code generation — vague requirements produce vague code.
 
 **CRITICAL RULE**: The number of questions is **unlimited**. Do NOT rush through this phase. Ask as many rounds as needed until every aspect is clear. The framework strives for perfect code generation, which requires perfect understanding of requirements.
 
@@ -111,25 +111,49 @@ Ask the user to describe what they want to build. Listen for:
 - **Who** uses it (user roles, personas)
 - **Why** it's needed (business value, problem being solved)
 
-### Step 1.2: Context Gathering
+### Step 1.2: Collect Reference Materials
 
-Before asking detailed questions, gather existing project context:
-- If `.prizm-docs/root.prizm` exists → read it to understand existing architecture, tech stack, patterns
-- If `.prizmkit/config.json` exists → read tech stack preferences
-- If existing source code exists → scan directory structure:
-  ```bash
-  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
-  ```
-- If database/schema files exist → scan them to understand existing data model:
-  ```bash
-  find . -maxdepth 4 -type f \( -name "*.prisma" -o -name "*.sql" -o -path "*/migrations/*" -o -path "*/models/*" -o -name "schema.*" -o -name "*.entity.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' | head -20
-  ```
+**Ask the user explicitly** what resources they have. Do NOT skip this step — user-provided materials are far more valuable than blind directory scanning.
 
-This context informs better questions — e.g., if the project uses PostgreSQL + Prisma, ask about schema design in those terms.
+Ask:
+1. **Existing code** — "Is there existing code I should look at? Which files or directories are relevant?"
+2. **Design documents** — "Do you have any design docs, wireframes, API specs, or PRDs I should read?"
+3. **Knowledge docs** — "Are there related `.prizm-docs/`, README files, or internal wiki pages?"
+4. **Reference projects** — "Any reference implementations or similar projects I should look at for inspiration?"
 
-### Step 1.3: Adaptive Deep-Dive Questioning
+Record everything the user provides — these become inputs for Step 1.3.
 
-Based on the user's description, ask questions across these dimensions. **Adapt question depth to the feature complexity** — a simple CRUD feature needs fewer questions than a real-time collaboration system.
+### Step 1.3: Parallel Deep Reading
+
+**Goal**: Build comprehensive understanding of the project context before discussing detailed requirements. Spawn multiple agents in parallel to read all relevant materials simultaneously.
+
+**Parallel reading tasks** (launch concurrently):
+
+| Agent | What to read | Purpose |
+|-------|-------------|---------|
+| Agent A | User-provided code paths — read existing source files | Understand current architecture, patterns, conventions |
+| Agent B | User-provided documents — design docs, specs, PRDs | Understand intended requirements and constraints |
+| Agent C | `.prizm-docs/` — root.prizm, L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
+| Agent D | Database/schema files + `.prizmkit/config.json` | Understand data model and tech stack preferences |
+
+**Also gather** (can be included in any agent's task):
+- Directory structure of the project
+- Existing test patterns and conventions
+- Dependency relationships between existing modules
+
+**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+
+### Step 1.4: Discuss Requirements
+
+**Now** — with deep knowledge of the actual codebase and documents — discuss the requirements with the user. This discussion is grounded in real context, not abstract questions.
+
+Present what you learned from the parallel reading:
+- Current project structure and patterns (with specific references)
+- Existing data model and schema conventions
+- Known TRAPS and pitfalls from `.prizm-docs/`
+- Integration points with existing modules
+
+Then ask targeted questions based on what you read. **Adapt question depth to the feature complexity** — a simple CRUD feature needs fewer questions than a real-time collaboration system.
 
 **Functional Requirements:**
 - What are the core user actions/workflows?
@@ -152,7 +176,7 @@ Based on the user's description, ask questions across these dimensions. **Adapt
 - Are there any specific UI/UX requirements?
 
 **Integration & Architecture:**
-- Does this feature depend on or affect other features/modules?
+- "Based on the existing code, this feature would integrate with [modules]. Does that match your expectations?"
 - Any external APIs or services involved?
 - What authentication/authorization model applies?
 - Any real-time requirements (WebSocket, SSE, polling)?
@@ -167,14 +191,14 @@ Based on the user's description, ask questions across these dimensions. **Adapt
 - Scalability considerations?
 - Security requirements? (encryption, audit logs, compliance)
 
-### Step 1.4: Iterative Clarification Loop
+### Step 1.5: Confirm and Supplement
 
-After the initial deep-dive:
+After the discussion:
 
-1. **Summarize** what you've understood so far — present it back to the user
-2. **Identify gaps** — explicitly list any areas that are still unclear or ambiguous
-3. **Ask follow-up questions** for each gap
-4. **Repeat** until the user confirms: "Yes, that covers everything" or "That's clear enough"
+1. **Summarize** the requirements — present it back to the user
+2. **Ask explicitly**: "Is there anything else you'd like to discuss or supplement before we proceed to formal planning?"
+3. **Identify gaps** — if any areas are still unclear, list them explicitly and ask follow-up questions
+4. **Repeat** until the user confirms: "That covers everything" or "Let's proceed"
 
 **Signs that brainstorming is complete:**
 - All functional requirements have concrete acceptance criteria
@@ -189,7 +213,7 @@ After the initial deep-dive:
 - Data relationships are unclear ("somehow connected")
 - User says "I'm not sure" — help them think through it with concrete options
 
-### Step 1.5: Requirements Summary
+### Step 1.6: Requirements Summary
 
 Once brainstorming is complete, produce a structured requirements summary:
 
@@ -220,6 +244,9 @@ Once brainstorming is complete, produce a structured requirements summary:
 ### Non-Functional Requirements
 - [Requirement]
 
+### Reference Materials Reviewed
+- [List of code paths, documents, .prizm-docs/ files that were read]
+
 ### Confirmed by user: ✓
 ```
 
@@ -389,14 +416,14 @@ While the pipeline runs, the user can continue the conversation:
 
 | Dimension | feature-workflow | bug-fix-workflow | refactor-workflow |
 |-----------|-----------------|------------------|-------------------|
-| **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring |
-| **Brainstorming** | Yes — deep interactive Q&A | No (bug report is input) | No (analysis built-in) |
-| **Planning Skill** | `feature-planner` | None (triage built-in) | None (analysis built-in) |
-| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | `refactor/<slug>` |
-| **Execution** | Foreground or background daemon | In-session, interactive | In-session |
-| **Input** | Rough idea or requirements | Bug report / stack trace | Module / code target |
-| **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
-| **User verification** | Yes (Phase 1 brainstorm confirmation) | Yes (Phase 5) | Yes (Phase 5) |
+| **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring (batch) |
+| **Brainstorming** | Yes — collect materials, parallel read, discuss | No (bug report is input) | Yes — clarify type, collect materials, parallel read, discuss |
+| **Planning Skill** | `feature-planner` | None (triage built-in) | `refactor-planner` |
+| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | Pipeline manages per-refactor |
+| **Execution** | Foreground or background daemon | In-session, interactive | Foreground or background daemon |
+| **Input** | Rough idea or requirements | Bug report / stack trace | Rough refactoring idea or target |
+| **Output** | Multiple `feat()` commits | Single `fix()` commit | Multiple `refactor()` commits |
+| **Behavior Change** | Expected (new functionality) | Fix behavior | Forbidden (structure only) |
 | **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | (this is the batch flow) |
 
 ---

package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md

@@ -1,12 +1,8 @@
 # Structural Sync — Detailed Steps
 
-**1a.** Get changed files:
+**1a.** Get changed files (staged + unstaged vs HEAD):
 ```bash
-git diff --cached --name-status
-```
-If nothing staged, fallback:
-```bash
-git diff --name-status
+git diff HEAD --name-status
 ```
 
 **1b.** Read `.prizm-docs/root.prizm` to get MODULE_INDEX (or MODULE_GROUPS). Map each changed file to its module.
@@ -19,7 +15,7 @@ git diff --name-status
 
 **1d.** Update affected docs (bottom-up: L2 → L1 → L0):
 
-- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 with these sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS, CHANGELOG. Populate from source.
+- **L2**: If L2 exists → update **only the sections affected by the diff files in this module**. For example, if only `api.js` changed: update its KEY_FILES entry, its INTERFACES (if exports changed), its DEPENDENCIES (if imports changed). Do NOT re-scan unchanged files in the module. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 with these sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS, CHANGELOG. Populate **only from the diff files** (the Added/Modified files in this module from step 1a), not from the entire module directory.
 - **L1**: Update FILES count, KEY_FILES (if major files added/removed), DEPENDENCIES (if module-level deps changed). **L1 does NOT contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS** — those belong in L2 only.
 - **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed). **Preserve** any `PROJECT_BRIEF:` line — it is managed by prizmkit-init.
 

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

@@ -29,7 +29,7 @@ User says:
 ```
 refactor-workflow <target / goals>
    │
-   ├── Phase 1: Brainstorm → interactive Q&A until refactoring goals are clear
+   ├── Phase 1: Brainstorm → clarify type → collect materials → parallel deep read → discuss plan
    │
    ├── Phase 2: Plan → refactor-planner → .prizmkit/plans/refactor-list.json
    │
@@ -42,7 +42,7 @@ refactor-workflow <target / goals>
 
 | Phase | Action | Result |
 |-------|--------|--------|
-| 1 | **Brainstorm** — interactive Q&A with user | Fully clarified refactoring goals |
+| 1 | **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code | Fully clarified refactoring goals |
 | 2 | Call `refactor-planner` with clarified goals | `.prizmkit/plans/refactor-list.json` with N refactor items |
 | 3 | Call `refactor-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
 | 4 | Monitor progress | Status updates, completion report |
@@ -100,57 +100,85 @@ When user says "add more refactors" or the project already has a .prizmkit/plans
 
 ## Phase 1: Brainstorm — Deep Refactoring Goal Clarification
 
-**Goal**: Through interactive Q&A, transform the user's rough refactoring idea into fully clarified, implementation-ready refactoring goals. This phase is the foundation for safe, behavior-preserving code changes — vague goals produce risky refactors.
+**Goal**: Through interactive Q&A and deep code reading, transform the user's rough refactoring idea into fully clarified, implementation-ready refactoring goals. This phase is the foundation for safe, behavior-preserving code changes — vague goals produce risky refactors.
 
 **CRITICAL RULE**: The number of questions is **unlimited**. Do NOT rush through this phase. Ask as many rounds as needed until every aspect is clear. Refactoring is inherently risky — thorough understanding prevents broken behavior.
 
-### Step 1.1: Understand the User's Refactoring Goals
+### Step 1.1: Clarify Refactoring Type
 
-Ask the user to describe what they want to refactor. Listen for:
+**First question** — ask the user to classify the refactoring approach:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Incremental** | Piece-by-piece restructuring, each step independently safe | "Gradually extract shared utilities over several PRs" |
+| **Comprehensive** | Full rewrite of a module/area in one pass | "Rewrite the auth module with new architecture" |
+| **Targeted** | Specific, focused change to a particular part | "Extract the validation logic from the controller" |
+
+Then ask:
 - **What** code needs restructuring (modules, files, patterns)
 - **Why** it needs refactoring (tech debt, coupling, complexity, readability, performance structure)
 - **What outcome** they want (target architecture, desired structure, quality goals)
 
-### Step 1.2: Context Gathering
+### Step 1.2: Collect Reference Materials
+
+**Ask the user explicitly** what resources they have. Do NOT skip this step — user-provided materials are far more valuable than blind directory scanning.
+
+Ask:
+1. **Code paths** — "Which files or directories are the main targets? Any specific files I should look at?"
+2. **Design documents** — "Do you have any design docs, architecture diagrams, or refactoring proposals I should read?"
+3. **Knowledge docs** — "Are there related `.prizm-docs/`, README files, or internal wiki pages for the target area?"
+4. **Related issues/PRs** — "Any related issues, PRs, or previous refactoring attempts I should be aware of?"
+
+Record everything the user provides — these become inputs for Step 1.3.
+
+### Step 1.3: Parallel Deep Reading
+
+**Goal**: Build comprehensive understanding of the target code and context before discussing plans. Spawn multiple agents in parallel to read all relevant materials simultaneously.
+
+**Parallel reading tasks** (launch concurrently):
+
+| Agent | What to read | Purpose |
+|-------|-------------|---------|
+| Agent A | User-provided code paths — read full source files | Understand current structure, interfaces, dependencies |
+| Agent B | User-provided documents — design docs, proposals, wiki pages | Understand intended direction and constraints |
+| Agent C | `.prizm-docs/` for affected modules — L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
+| Agent D | Test files for the target area — find and read existing tests | Understand current test coverage and behavior contracts |
+
+**Also gather** (can be included in any agent's task):
+- `.prizmkit/config.json` → tech stack preferences
+- Directory structure of the target area
+- Dependency relationships (imports/exports between target and other modules)
+
+**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
 
-Before asking detailed questions, gather existing project context:
-- If `.prizm-docs/root.prizm` exists → read it to understand existing architecture, tech stack, patterns
-- If `.prizmkit/config.json` exists → read tech stack preferences
-- If existing source code exists → scan directory structure:
-  ```bash
-  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
-  ```
-- Check test suite existence and coverage for the target area:
-  ```bash
-  find . -maxdepth 4 -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -path "*/tests/*" -o -path "*/__tests__/*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20
-  ```
+### Step 1.4: Discuss Refactoring Plan
 
-This context informs better questions — e.g., if the target module has no tests, the conversation must address test coverage before refactoring.
+**Now** — with deep knowledge of the actual code and documents — discuss the refactoring plan with the user. This discussion is grounded in real code, not abstract questions.
 
-### Step 1.3: Adaptive Deep-Dive Questioning
+Present what you learned from the parallel reading:
+- Current code structure and its problems (with specific file/function references)
+- Existing test coverage status (which areas are safe, which are risky)
+- Known TRAPS and pitfalls from `.prizm-docs/`
+- Dependencies and potential impact on other modules
 
-Based on the user's description, ask questions across these dimensions. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
+Then ask targeted questions based on what you read. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
 
 **Code Structure:**
-- What's wrong with the current structure? What specific pain points exist?
+- "I see the current structure does X — is the target state Y, or something different?"
 - What's the target state? What should the code look like after refactoring?
-- Are there specific code smells? (duplication, deep nesting, god classes, tight coupling)
-- What are the dependency relationships between the target and other modules?
+- Are there specific code smells you've noticed? (duplication, deep nesting, god classes, tight coupling)
 
 **Scope:**
-- Which files/modules are in scope? Which are explicitly out of scope?
-- Is this a single-module refactor or does it span multiple modules?
-- Should the refactoring be incremental (piece by piece) or comprehensive?
+- Based on the code I read, these modules are affected: [list]. Anything else in/out of scope?
+- For incremental refactoring: what's the order of priority?
 
 **Behavior Preservation:**
-- What behavior must stay identical? Are there contracts/APIs that must not change?
-- What tests exist for the target area? Are they passing currently?
-- Are there integration tests or end-to-end tests that cover this area?
+- "These public APIs/interfaces exist: [list]. Which must remain unchanged?"
+- "I found these tests: [list]. Are they passing currently?"
 - Any undocumented behavior that callers depend on?
 
 **Risk Assessment:**
-- What could break? Are there fragile or undocumented areas?
-- Are there known gotchas or traps in this code? (check `.prizm-docs/` TRAPS)
+- "I found these TRAPS in .prizm-docs/: [list]. Any other known gotchas?"
 - Does this code have external consumers (other teams, published APIs)?
 - Any concurrent development happening in the target area?
 
@@ -159,14 +187,14 @@ Based on the user's description, ask questions across these dimensions. **Adapt
 - Team coordination needed? (other developers working in the same area)
 - Deployment concerns? (feature flags, backward compatibility, migration)
 
-### Step 1.4: Iterative Clarification Loop
+### Step 1.5: Confirm and Supplement
 
-After the initial deep-dive:
+After the discussion:
 
-1. **Summarize** what you've understood so far — present it back to the user
-2. **Identify gaps** — explicitly list any areas that are still unclear or ambiguous
-3. **Ask follow-up questions** for each gap
-4. **Repeat** until the user confirms: "Yes, that covers everything" or "That's clear enough"
+1. **Summarize** the refactoring plan — present it back to the user
+2. **Ask explicitly**: "Is there anything else you'd like to discuss or supplement before we proceed to formal planning?"
+3. **Identify gaps** — if any areas are still unclear, list them explicitly and ask follow-up questions
+4. **Repeat** until the user confirms: "That covers everything" or "Let's proceed"
 
 **Signs that brainstorming is complete:**
 - All refactoring goals have concrete target state descriptions
@@ -182,7 +210,7 @@ After the initial deep-dive:
 - Risk areas are handwaved ("it should be fine")
 - User says "I'm not sure" — help them think through it with concrete options
 
-### Step 1.5: Requirements Summary
+### Step 1.6: Requirements Summary
 
 Once brainstorming is complete, produce a structured goals summary:
 
@@ -191,11 +219,13 @@ Once brainstorming is complete, produce a structured goals summary:
 
 ### Target: [Module/area name]
 
+### Refactoring Type: [Incremental / Comprehensive / Targeted]
+
 ### Refactoring Objectives
 - [Bullet list of what structural changes are needed and why]
 
 ### Current Problems
-- [What's wrong with the current structure]
+- [What's wrong with the current structure — with specific code references]
 
 ### Target State
 - [What the code should look like after refactoring]
@@ -212,6 +242,9 @@ Once brainstorming is complete, produce a structured goals summary:
 ### Risk Assessment
 - [Risk]: [Mitigation strategy]
 
+### Reference Materials Reviewed
+- [List of code paths, documents, .prizm-docs/ files that were read]
+
 ### Constraints
 - [Timeline, coordination, deployment concerns]
 
@@ -368,34 +401,7 @@ While the pipeline runs, the user can continue the conversation:
 | User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
 | Behavior regression detected during pipeline | Pipeline handles per-item — failed items are retried or reported |
 
----
-
-## Relationship to Other Skills
-
-| Skill | Relationship |
-|-------|-------------|
-| `refactor-planner` | **Called by Phase 2** — generates .prizmkit/plans/refactor-list.json from clarified goals |
-| `refactor-pipeline-launcher` | **Called by Phase 3** — starts pipeline (handles execution mode selection) |
-| `feature-workflow` | **Alternative** — for new feature development |
-| `bug-fix-workflow` | **Alternative** — for bug fix workflows |
 
----
-
-## Comparison with Alternative Workflows
-
-| Dimension | refactor-workflow | feature-workflow | bug-fix-workflow |
-|-----------|-------------------|-----------------|------------------|
-| **Purpose** | Code restructuring (batch) | New features (batch) | Single bug fix (interactive) |
-| **Brainstorming** | Yes — deep interactive Q&A on refactoring goals | Yes — deep interactive Q&A on requirements | No (bug report is input) |
-| **Planning Skill** | `refactor-planner` | `feature-planner` | None (triage built-in) |
-| **Branch** | Pipeline manages per-refactor | Pipeline manages per-feature | `fix/<BUG_ID>-*` |
-| **Execution** | Foreground or background daemon | Foreground or background daemon | In-session, interactive |
-| **Input** | Rough refactoring idea or target | Rough idea or requirements | Bug report / stack trace |
-| **Output** | Multiple `refactor()` commits | Multiple `feat()` commits | Single `fix()` commit |
-| **Behavior Change** | Forbidden (structure only) | Expected (new functionality) | Fix behavior |
-| **Batch alternative** | (this is the batch flow) | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` |
-
----
 
 ## Output
 

package/package.json

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