prizmkit 1.1.57 → 1.1.60

package/bundled/skills-windows/app-planner/assets/app-design-guide.md

@@ -0,0 +1,101 @@
+# App Design Reference Guide
+
+This guide provides structured templates, decision matrices, and decomposition patterns for new application planning. Use during the vision and architecture phases of app-planner sessions.
+
+---
+
+## 1. App Vision Template
+
+Use this template to capture the app vision during the initial planning phase.
+
+```markdown
+# App Vision: [APP_NAME]
+
+## Problem Statement
+[What problem does this app solve?]
+
+## Target Users
+- Primary: [Who are the main users?]
+- Secondary: [Any secondary user types?]
+
+## Core Value Proposition
+[What makes this app valuable? What's the "elevator pitch"?]
+
+## Key Differentiators
+[What sets this apart from existing solutions?]
+```
+
+### Guidance
+
+- **Problem Statement**: Should describe a real pain point in 1-3 sentences. Avoid vague statements like "improve productivity." Be specific about who suffers and why.
+- **Target Users**: Identify at least one primary user persona. Secondary users are optional but useful for prioritization decisions later.
+- **Core Value Proposition**: Should be expressible in one sentence. If it takes a paragraph, the scope is likely too broad.
+- **Key Differentiators**: List 1-3 concrete differentiators. If none exist, reconsider whether the app needs to be built.
+
+---
+
+## 2. Tech Stack Decision Matrix
+
+Use these tables to guide tech stack selection based on project requirements.
+
+### Frontend Frameworks
+
+| Framework | Best For | Ecosystem |
+|-----------|----------|-----------|
+| Next.js | Full-stack React, SSR, API routes | React ecosystem, Vercel |
+| Nuxt 3 | Full-stack Vue, SSR | Vue ecosystem |
+| SvelteKit | Performance-focused, smaller teams | Svelte ecosystem |
+| Remix | Nested routes, data loading | React ecosystem |
+
+### Backend Frameworks
+
+| Framework | Best For | Language |
+|-----------|----------|----------|
+| Express.js | Flexible, minimal | Node.js/TS |
+| FastAPI | High-perf APIs, Python ML | Python |
+| NestJS | Enterprise, structured | Node.js/TS |
+| Django | Batteries-included, admin | Python |
+| Go (Gin/Echo) | High concurrency | Go |
+
+### Databases
+
+| Database | Best For | Type |
+|----------|----------|------|
+| PostgreSQL | Complex queries, ACID | Relational |
+| MySQL | Read-heavy, simple | Relational |
+| MongoDB | Flexible schema, documents | Document |
+| SQLite | Embedded, prototyping | Relational |
+| Redis | Caching, sessions, pub/sub | Key-Value |
+
+### Design Systems
+
+| System | Best For | Framework |
+|--------|----------|-----------|
+| shadcn/ui | Modern, customizable | React/Next.js |
+| Ant Design | Enterprise, data-heavy | React |
+| Material UI | Google-style, full-featured | React |
+| Vuetify | Material Design for Vue | Vue |
+| Tailwind CSS | Utility-first, any framework | Any |
+
+### Common Service Patterns
+
+| Need | Options |
+|------|---------|
+| Auth | NextAuth.js, Auth0, Clerk, Supabase Auth, custom JWT |
+| Real-time | WebSocket, Socket.io, SSE, Supabase Realtime |
+| File Storage | S3, Cloudflare R2, Supabase Storage |
+| Email | SendGrid, Resend, Postmark |
+| Payments | Stripe, LemonSqueezy |
+| Search | Algolia, Meilisearch, Elasticsearch |
+
+### Selection Heuristics
+
+- If the user has no strong preference, default to **Next.js + PostgreSQL + shadcn/ui + Tailwind CSS** as a general-purpose stack.
+- If the project involves ML/AI backends, prefer **FastAPI** on the backend.
+- If the project requires high concurrency with minimal resource usage, consider **Go**.
+- If rapid prototyping is the goal, consider **SQLite** initially with a migration path to PostgreSQL.
+- Always ask about deployment preferences (Vercel, AWS, self-hosted) as this influences framework choice.
+
+
+
+> **Note**: Feature decomposition patterns (CRUD, SaaS, Social, E-commerce) have been moved to `feature-planner/references/decomposition-patterns.md`. Load that reference during feature decomposition phase.

package/bundled/skills-windows/app-planner/references/architecture-decisions.md

@@ -0,0 +1,52 @@
+# Architecture Decision Capture
+
+During planning, key **framework-level** architectural decisions may emerge. When they do, capture them in the project instruction file so all future AI sessions have this context.
+
+## What Qualifies (ALL must apply)
+
+Only capture decisions that are **framework-shaping** — NOT individual feature details. Qualifying categories:
+
+| Category | Examples |
+|----------|----------|
+| Tech stack choices | PostgreSQL over MongoDB, React over Vue, Node.js runtime |
+| Communication patterns | REST vs GraphQL, WebSocket vs SSE vs polling |
+| Architectural patterns | Monorepo, microservices, monolith, event-driven |
+| Data model strategies | Relational vs document, event sourcing, CQRS |
+| Security architecture | JWT vs session, OAuth provider, RBAC model |
+
+**Do NOT capture**: individual feature implementation details, UI component choices, specific API endpoint designs, or anything scoped to a single feature.
+
+**This is conditional** — most planning sessions will NOT produce architecture decisions. Only capture when genuinely impactful decisions are made during the discussion.
+
+## When to Capture
+
+After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Capture architecture decisions and finalize project brief). At this point decisions are settled.
+
+## How to Capture
+
+1. **Detect platform** — determine which project instruction file to update:
+   - If `.prizmkit/manifest.json` exists, read `platform` and use it as the source of truth.
+   - `codex` → append to `AGENTS.md`
+   - `claude` → append to `CLAUDE.md`
+   - `codebuddy` → append to `CODEBUDDY.md`
+   - `both` → append to `CLAUDE.md` and `CODEBUDDY.md`; `all` → append to all three files.
+   - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, `.codebuddy/skills/prizm-kit/SKILL.md`.
+   - Do not treat a generic `.agents/` directory as Codex; it may contain unrelated third-party skills.
+   - If no platform can be determined, skip (no project instruction file).
+
+2. **Check for existing section** — read the target file and look for `### Architecture Decisions` heading:
+   - If heading exists → append new entries below it (avoid duplicates with existing entries)
+   - If heading does not exist → create it at the end of the file
+
+3. **Format** — one line per decision, no feature IDs:
+   ```markdown
+   ### Architecture Decisions
+   - WebSocket for real-time: sub-second latency required for collaboration features
+   - PostgreSQL: relational data model with complex queries, ACID compliance needed
+   - Monorepo structure: shared types between frontend and backend
+   ```
+
+4. **User confirmation** — before writing, show the collected decisions and ask:
+   > "These architecture decisions were identified during planning. Record them to [AGENTS.md / CLAUDE.md / CODEBUDDY.md]? (Y/n)"
+
+   If user declines, skip without further prompting.

package/bundled/skills-windows/app-planner/references/brainstorm-guide.md

@@ -0,0 +1,101 @@
+# Brainstorm Guide — Structured Ideation Before Implementation
+
+> Separate WHAT from HOW. Explore the problem space before committing to a solution.
+
+This guide provides the structured brainstorming framework used in Phase 1 of the workflow.
+The AI facilitates this process as a **design collaborator**, not a builder.
+
+## Four Phases
+
+### Phase A: Assess Clarity
+
+Evaluate the user's initial goal statement:
+
+- **Clear** — Specific and actionable (e.g., "add JWT auth to the API")
+- **Vague** — Direction exists but needs narrowing (e.g., "improve security")
+- **Exploring** — No firm goal yet, just a direction (e.g., "something with auth")
+
+If **vague** or **exploring**, ask follow-up questions to sharpen the goal.
+Do NOT proceed until there is a concrete, testable problem statement (one sentence).
+
+### Phase B: Understand the Idea
+
+Answer these questions (use codebase exploration as needed):
+
+1. **What problem does this solve?** — State the pain point in concrete terms.
+2. **Who benefits?** — End users, developers, operators?
+3. **What exists today?** — Current state, prior art in the codebase, adjacent systems.
+4. **What constraints matter?** — Performance, compatibility, security, timeline.
+
+Non-functional requirements to explicitly clarify or propose defaults for:
+- Performance expectations
+- Scale (users, data, traffic)
+- Security or privacy constraints
+- Reliability / availability needs
+- Maintenance and ownership expectations
+
+If the user is unsure on any point, propose reasonable defaults and clearly mark them as **assumptions**.
+
+Summarize findings before moving on. If anything is unclear, ask.
+
+### Phase C: Explore Approaches
+
+Generate **2-3 distinct approaches**. For each:
+
+- **Name** — Short label (e.g., "JWT middleware", "OAuth proxy")
+- **How it works** — 2-3 sentences
+- **Pros** — What it gets right
+- **Cons** — What it gets wrong or defers
+- **Effort** — Rough scope (small / medium / large)
+
+#### Adversarial Critique (Red Team)
+
+Before asking the user to choose, stress-test each approach using the red team checklist
+(`references/red-team-checklist.md`):
+
+1. What breaks first?
+2. What's the hidden cost?
+3. What assumption is wrong?
+4. Who disagrees?
+
+Mark any approach that fails 2+ red team questions as **HIGH RISK**.
+If all approaches fail, generate a hybrid addressing the weaknesses.
+
+Present the comparison and let the user pick an approach or request a hybrid.
+
+### Phase D: Capture Design
+
+Produce a structured summary:
+
+```markdown
+## Problem Statement
+[One sentence, testable]
+
+## Approaches Considered
+[2-3 approaches with pros/cons/effort]
+
+## Selected Approach
+[User's choice + rationale]
+
+## Assumptions
+[All assumptions explicitly listed]
+
+## Open Questions
+[Unresolved items, if any]
+
+## Key Decisions
+[What was decided and why — alternatives and rationale]
+```
+
+This summary becomes the input for the next phase (specification or planning).
+
+---
+
+## Rules
+
+- Ask as many questions as needed — no rushing
+- One topic at a time for complex clarifications
+- Prefer multiple-choice questions when possible
+- Assumptions must be explicit, never silent
+- YAGNI ruthlessly — avoid premature complexity
+- Do NOT implement, code, or modify behavior during brainstorming

package/bundled/skills-windows/app-planner/references/frontend-design-guide.md

@@ -0,0 +1,71 @@
+# Frontend Design Guide — High-Quality UI Implementation
+
+> Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics.
+
+**app-planner context**: In the planning phase, use this guide to establish **design direction decisions** (aesthetic tone, typography approach, color strategy, layout philosophy). Do NOT produce CSS, code, or implementation artifacts — capture the design direction as decisions in the project instruction file (`AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md`). Downstream implementation skills will consume these decisions when building features.
+
+Load this guide **only when the feature involves frontend/UI work**. Skip for backend-only or infrastructure features.
+
+## Context Gathering (Required Before Design)
+
+Before any UI design work, gather:
+- **Target audience**: Who uses this product and in what context?
+- **Use cases**: What jobs are they trying to get done?
+- **Brand personality/tone**: How should the interface feel?
+
+You cannot infer this from codebase alone — ask the user.
+
+## Design Direction
+
+Commit to a **bold** aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an intentional aesthetic — minimalist, editorial, brutalist, organic, luxury, playful, retro-futuristic, industrial, art deco, etc.
+- **Differentiation**: What makes this unforgettable?
+
+## Typography
+
+- Choose distinctive fonts. Pair a display font with a refined body font.
+- Use a modular type scale with fluid sizing (`clamp()`)
+- Vary font weights and sizes for clear visual hierarchy
+- Avoid overused fonts: Inter, Roboto, Arial, Open Sans, system defaults
+- Avoid monospace as lazy shorthand for "technical" vibes
+
+## Color & Theme
+
+- Use modern CSS color functions (oklch, color-mix, light-dark)
+- Tint neutrals toward brand hue for subconscious cohesion
+- Avoid: pure black (#000) or pure white (#fff) — always tint
+- Avoid: the AI palette (cyan-on-dark, purple-to-blue gradients, neon accents on dark)
+- Avoid: gradient text for "impact", default dark mode with glowing accents
+
+## Layout & Space
+
+- Create visual rhythm through varied spacing — not uniform padding
+- Use fluid spacing with `clamp()` that breathes on larger screens
+- Embrace asymmetry and unexpected compositions
+- Avoid: wrapping everything in cards, nesting cards, identical card grids
+- Avoid: centering everything, uniform spacing
+
+## Motion
+
+- Focus on high-impact moments: one well-orchestrated page load > scattered micro-interactions
+- Use exponential easing for natural deceleration
+- Use `transform` and `opacity` only — avoid animating layout properties
+- Avoid: bounce/elastic easing, excessive animations
+
+## Interaction
+
+- Use progressive disclosure — start simple, reveal complexity through interaction
+- Design empty states that teach the interface
+- Use optimistic UI — update immediately, sync later
+- Avoid: making every button primary, redundant headers
+
+## Responsive
+
+- Use container queries (`@container`) for component-level responsiveness
+- Adapt the interface for different contexts, don't just shrink it
+- Never hide critical functionality on mobile
+
+## The AI Slop Test
+
+If you showed this interface to someone and said "AI made this", would they believe you immediately? If yes, redesign. A distinctive interface should make someone ask "how was this made?" not "which AI made this?"

package/bundled/skills-windows/app-planner/references/project-brief-guide.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-windows/app-planner/references/red-team-checklist.md

@@ -0,0 +1,40 @@
+# Red Team Checklist for Ideation
+
+Use these questions to stress-test approaches during brainstorm Phase C.
+
+## Structural Questions
+
+1. **What breaks first?** — Identify the weakest link under stress (load, concurrency, edge cases, adversarial input). If you can't name a specific failure mode, the approach is under-specified.
+
+2. **What's the hidden cost?** — Every approach has costs beyond implementation time: maintenance burden, cognitive load for new contributors, infrastructure requirements, monitoring needs, migration complexity.
+
+3. **What assumption is wrong?** — List the unstated assumptions. Which one, if false, invalidates the approach? Common false assumptions: "the API won't change", "data fits in memory", "users will read the docs", "this library is maintained".
+
+4. **Who disagrees?** — Steel-man the opposing view. A performance engineer and a UX designer will critique the same approach differently. What does the most skeptical qualified person say?
+
+## Scoring
+
+| Red Team Failures | Classification |
+|-------------------|---------------|
+| 0 | Strong approach |
+| 1 | Viable with mitigation |
+| 2+ | HIGH RISK — needs rethinking or mitigation plan |
+
+## When All Approaches Are HIGH RISK
+
+If every approach fails 2+ questions, the problem statement may be wrong. Consider:
+- Is the goal too broad? Split it.
+- Is there a constraint you haven't stated? Surface it.
+- Generate a hybrid approach that addresses the specific red team failures.
+
+## Common False Assumptions
+
+| Assumption | Why It Fails |
+|-----------|-------------|
+| "The API won't change" | External APIs change without notice; pin versions and add contract tests |
+| "Data fits in memory" | Works in dev, breaks in prod when dataset grows 10x |
+| "Users will read the docs" | They won't; make the happy path obvious and errors informative |
+| "This library is maintained" | Check commit history; many popular libraries are effectively abandoned |
+| "We can refactor later" | Technical debt compounds; later never comes without explicit scheduling |
+| "Performance doesn't matter yet" | Architecture decisions that ignore performance are expensive to fix |
+| "The team will adopt it" | New tools need champions, training, and visible wins to gain traction |