prizmkit 1.1.57 → 1.1.60

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

@@ -0,0 +1,639 @@
+---
+name: "app-planner"
+description: "Plan an application through interactive conversation — capture vision, tech stack, constraints, dev rules, and project brief. Works for both new (greenfield) and existing (brownfield) projects that need app-level planning. Also use for configuring per-layer development rules (frontend/backend/database/mobile) that AI coding assistants should follow. Use this skill when users say 'plan an app', 'design a new project', 'start from scratch', 'build a new application', 'set up dev rules', 'configure frontend rules', 'configure backend rules', or discuss app-level architecture and design. Also use for existing projects that need a project brief or app-level context. For adding features to existing projects that already have a project brief, use feature-planner instead."
+---
+
+# app planner
+
+Plan an application from idea to actionable project context through interactive conversation. Works for both **greenfield** (new) and **brownfield** (existing) projects:
+- Vision and problem statement
+- Tech stack selection (or confirmation of existing stack)
+- Constraints and design direction
+- Architecture decision capture
+- Project brief accumulation (`.prizmkit/plans/project-brief.md`)
+
+This skill captures **project-level context only**: vision, tech stack, conventions, architecture decisions, and project brief. It does NOT do feature decomposition or generate `feature-list.json` — that is `feature-planner`'s job.
+
+For adding features to an **existing** project that already has a project brief, use `feature-planner` directly.
+
+## Invocation Commitment (Hard Rule)
+ You must NEVER:
+- Bypass the interactive phases because you judge the task to be "simple"
+
+If you believe the task is better suited for a different workflow, you MUST:
+1. **Explain why** you think a different path is more appropriate
+2. **Ask the user explicitly** whether they want to switch
+3. **Only switch if the user confirms**
+
+## Scope Boundary (Hard Rule)
+
+**This skill is PLANNING ONLY.** You must NEVER:
+- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
+- Create project scaffolding, directories, or boilerplate (exception: `.prizmkit/rules/` and `.prizmkit/prizm-docs/` directories may be created for dev rules and root.prizm output)
+- Run build/install/test commands (npm init, pip install, etc.)
+- Execute any implementation action beyond writing planning artifacts
+
+**Your ONLY writable outputs are:**
+1. `.prizmkit/plans/project-brief.md` (`.prizmkit/plans/` — accumulated project context brief)
+2. Project conventions and architecture decisions appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
+3. Infrastructure configuration (database conventions, deployment config, **cloud services**) appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section
+4. `.prizmkit/rules/<layer>-rules.md` — per-layer development rules generated by Rules Configuration
+5. `.prizmkit/prizm-docs/root.prizm` — `RULES:` pointer line only (not other root.prizm content; created minimally if absent)
+
+**Project instruction file selection**:
+- If `.prizmkit/manifest.json` exists, use its `platform` field as the source of truth.
+- Codex → `AGENTS.md`
+- Claude Code → `CLAUDE.md`
+- CodeBuddy → `CODEBUDDY.md`
+- `both` → `CLAUDE.md` and `CODEBUDDY.md`; `all` → all three files.
+- Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, or `.codebuddy/skills/prizm-kit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
+
+**After planning is complete**, you MUST:
+1. Present the summary of captured project-level context (vision, conventions, architecture decisions, project brief)
+2. List the artifacts produced and suggest possible next steps (e.g., `feature-planner`, `prizmkit-plan`, etc.) — but do NOT auto-invoke any of them
+3. **NEVER auto-execute** the pipeline, feature-planner, or any implementation step
+4. **NEVER generate `feature-list.json`** — that is exclusively `feature-planner`'s responsibility
+
+## When to Use
+
+Trigger this skill for requests like:
+- "Plan an app", "Design a project", "Design a new application"
+- "Start from scratch", "Build something new", "Create a new product"
+- "Help me figure out what to build", "Brainstorm an app idea"
+- "What tech stack should I use?", "Help me choose frameworks"
+- "Create a project brief for my existing project"
+- "Help me document what this project is about"
+- "I have a codebase but no project plan yet"
+
+Do NOT use this skill when:
+- The user already has a project brief and wants to add features → use `feature-planner`
+- The user wants to run the pipeline → use `feature-pipeline-launcher`
+- The user is debugging/refactoring or wants to write source code directly
+
+## Resource Loading Rules (Mandatory)
+
+1. **App design reference** — always load at session start:
+   - Read `${SKILL_DIR}/assets/app-design-guide.md` for vision templates and tech stack matrix
+
+2. **Load on-demand references when triggered**:
+   - Architecture decisions emerged → read `${SKILL_DIR}/references/architecture-decisions.md`
+   - Frontend/UI project detected → read `${SKILL_DIR}/references/frontend-design-guide.md`
+   - 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 discovery** — after Intent Confirmation, before brainstorm or vision work:
+   → Read `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` and check for `### Project Conventions` section
+   → 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 via `AskUserQuestion`**
+
+   First, show "Already decided" conventions as text:
+   > **Already decided** (detected from your codebase):
+   > - [convention]: [value] (source: [where you found it])
+   > - [convention]: [value] (source: [where you found it])
+
+   Then use `AskUserQuestion` for conventions that need user input (up to 4 questions per call, use multiple calls as needed — no limit on total rounds). Each question:
+   - Question text includes the convention name AND why it matters for this project
+   - Options are the reasonable choices (2-4 per question)
+   - Mark the recommended option first with "(Recommended)" in its label
+   - Use `description` field to explain trade-offs
+
+   After each batch of `AskUserQuestion` calls, reassess: are there more project-level conventions to cover? If yes, continue with more `AskUserQuestion` calls. Keep going until ALL project-level conventions are fully addressed.
+
+   Then ask in text: "Anything I missing that you'd like to standardize?" — if the user adds more, continue the discovery loop.
+
+   **Rules:**
+   - **No interaction limit** — keep asking until every project-level convention is covered. Do NOT stop early or batch-skip to save rounds.
+   - 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)
+   - Propose as many conventions as the project genuinely needs, but don't pad with irrelevant ones
+   - The "Anything I missing?" question is NOT the end — if the user adds items, ask follow-up `AskUserQuestion` calls to clarify those too
+
+   → Save answers to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
+   → Output format will naturally vary per project — that is the intended behavior
+
+   **Infrastructure Convention Discovery (Database + Deployment)**
+
+   After project conventions are captured, check `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` for `### Infrastructure` section:
+
+   - If `### Infrastructure` section does not exist → this project was not initialized with prizmkit-init's Phase 4.6. Treat as if both database and deployment are undecided — run full inquiry below.
+   - If `<!-- infrastructure: deferred -->` → user explicitly skipped at init time. Ask: "During project init you deferred infrastructure decisions. Would you like to configure them now?" (options: "Yes — configure now (Recommended)", "Skip — decide later")
+   - If `<!-- database: deferred -->` → only database was deferred, run database inquiry only
+   - If `<!-- deployment: deferred -->` or deployment section is missing → run deployment inquiry only
+   - If both sections exist with real values → read existing config, present as "Already decided", ask: "Anything to change?" If no → skip to next phase.
+
+   **Database Convention Deep Inquiry** (AI-driven, context-aware — select from pool based on project):
+
+   AI analyzes the detected database type, ORM, and tech stack, then selects relevant questions from this pool. Do NOT ask all questions — only those that matter for THIS project:
+
+   1. **Table naming convention**: snake_case / camelCase / PascalCase; prefix convention (e.g., `t_`, `tbl_`, none). For brownfield: detect from existing migration files or schema and present as "Already decided" with override option.
+   2. **Field naming convention**: snake_case / camelCase; common fields convention — are `created_at`, `updated_at`, `deleted_at` (soft delete) required on all tables? What about `id` vs `uuid` column naming?
+   3. **Migration conventions**:
+      - File storage directory (e.g., `db/migrations/`, `prisma/migrations/`, `alembic/versions/`)
+      - Naming rule (timestamp prefix `20240101_create_users`, sequence prefix `001_create_users`, ORM auto-generated)
+      - Migration tool (ORM built-in / Flyway / Liquibase / golang-migrate / manual SQL)
+      - For brownfield: detect existing migration directory and naming pattern, present as "Already decided"
+   4. **Primary key strategy**: Auto-increment integer / UUID v4 / ULID / Snowflake ID / Other
+   5. **Index naming convention**: e.g., `idx_{table}_{column}`, `ix_{table}_{column}`, or ORM default
+   6. **Environment separation**: dev/test/prod database separation strategy; connection config management (env vars / config files / secret manager)
+
+   Use `AskUserQuestion` for each batch (up to 4 questions per call). For brownfield projects, show detected patterns as recommended options. Each question MUST include a "Skip — decide later" option.
+
+   **Deployment Configuration Deep Inquiry** (AI-driven, context-aware):
+
+   Read the existing `### Infrastructure` → `#### Deployment` section for the deployment target, then ask relevant follow-up questions:
+
+   1. **Deployment target refinement**:
+      - Own server: SSH access method (key-based / password), OS (Ubuntu / CentOS / other), Docker installed?
+      - SaaS platform: specific platform confirmation, existing account and project? Already deployed before?
+      - Container: orchestration method (Docker Compose / K8s / ECS / Cloud Run)
+   2. **Existing infrastructure**:
+      - Remote machine availability — IP/domain? Existing server configuration?
+      - Existing CI/CD pipeline — GitHub Actions / GitLab CI / Jenkins / other? Already configured?
+      - Domain name and SSL — already owned? DNS provider? SSL management (Let's Encrypt / platform-managed / other)?
+   3. **AI-assisted deployment**:
+      - Whether AI should help execute deploy commands (via SaaS CLI like `vercel deploy`, `fly deploy`, `railway up`, `docker push`, or SSH remote commands)
+      - If yes: collect necessary info — API token storage method (env var name, e.g., `VERCEL_TOKEN`), project name/ID on the platform, target environment (production / staging)
+      - Explicitly inform: "AI will show each command and wait for your confirmation before executing"
+   4. **Environment variable management**: production env var strategy (SaaS platform dashboard / `.env.production` committed to repo / secret manager like AWS Secrets Manager, Vault / CI/CD secrets)
+
+   Use `AskUserQuestion` for each batch. Each question MUST include a "Skip — decide later" option.
+
+   **Cloud Services Deep Inquiry** (Two-round AskUserQuestion):
+
+   Many projects depend on third-party cloud services (object storage, CDN, managed DB, auth, domain, email, SMS, payment, AI APIs). Capture them now so feature-planner and prizmkit-deploy can reference them later.
+
+   *Round 1 — Cloud Vendors* (multi-select via `AskUserQuestion`):
+   - "Which cloud vendors will this project integrate with?"
+   - Options: `AWS`, `Aliyun`, `Tencent Cloud`, `Cloudflare`, `Vercel`, `Other` (free text), `None — skip`
+   - If `None — skip`, write `<!-- cloud-services: none -->` to the `#### Cloud Services` subsection and exit this inquiry.
+
+   *Round 2 — Service Types* (multi-select, only if Round 1 returned any vendor):
+   - "Which types of cloud services will you use?"
+   - Options: `Object Storage (COS/S3/OSS)`, `CDN`, `Managed Database`, `Functions/Serverless`, `Auth (OAuth/JWT/IDaaS)`, `Domain & DNS`, `Email`, `SMS`, `Payment`, `AI API (OpenAI/Anthropic/...)`, `Other`
+   - The list is multi-select. Skip the question entirely if user picks "None" in Round 1.
+
+   *After both rounds, write to `#### Cloud Services`*:
+   - For each chosen (vendor × service) pair, append a row to the subsection (see template below)
+   - **Do NOT** prompt for env var names, credentials, region, or SDK details — those belong to `prizmkit-deploy`'s scope, not planning
+   - If the user is unsure of the mapping, store the vendors and service types separately; deploy skill can refine later
+
+   Use `AskUserQuestion` for both rounds. Each question MUST include a "Skip — decide later" option.
+
+   **After infrastructure inquiry**:
+   - Update `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section with all collected information. Replace `<!-- deferred -->` markers with real values. Preserve any existing values that were confirmed unchanged. Full format:
+     ```markdown
+     ### Infrastructure
+
+     #### Database
+     - **Type**: [database type]
+     - **ORM**: [ORM name]
+     - **Table naming**: [convention, e.g., snake_case, no prefix]
+     - **Field naming**: [convention]; common fields: [list]
+     - **Primary key**: [strategy]
+     - **Migration directory**: [path]
+     - **Migration naming**: [rule]
+     - **Index naming**: [convention]
+     - **Environment separation**: [strategy]
+
+     #### Deployment
+     - **Target**: [platform/method]
+     - **AI-assisted deploy**: [yes/no]
+     - **Domain**: [domain or "not configured"]
+     - **SSL**: [management method]
+     - **CI/CD**: [tool or "not configured"]
+     - **Env var management**: [strategy]
+
+     #### Deployment Credentials Reference
+     - [platform]: [token/auth method description]
+
+     #### Cloud Services
+     - **Vendors**: [comma-separated list, e.g., "AWS, Cloudflare" or "none"]
+     - **Services**:
+       - [vendor]: [service type] — [optional one-line note, e.g., "user-upload images"]
+       - [vendor]: [service type]
+     <!-- If user picked "None" in Round 1, replace this block with: cloud-services: none -->
+     ```
+   - Items still marked "Skip — decide later" remain as `<!-- [topic]: deferred -->` in the selected project instruction file for `prizmkit-deploy` to pick up later.
+
+4. **Project brief accumulation** — throughout all interactive phases:
+   → Read `${SKILL_DIR}/references/project-brief-guide.md` for template and rules
+   → Update after each meaningful user response containing business intent, constraints, or design decisions
+
+## Rules Configuration (after Infrastructure)
+
+After Infrastructure configuration is complete (CP-AP-1.5), check whether the project's development layers have custom rules configured. Rules are per-layer documents (frontend-rules.md, backend-rules.md, database-rules.md, mobile-rules.md) that tell AI coding assistants how to generate code for that layer — UI framework, state management, naming conventions, etc.
+
+Rules are optional. If the user skips, AI uses general best practices freely — no reminders, no blocking.
+
+### Step 1: Detect which layers need rules
+
+1. Read `.prizmkit/config.json` to get `detected_layers` (written by `prizmkit-init` Phase 4.5).
+   - If `detected_layers` is present and non-empty → use it directly, jump to step 3.
+   - If `detected_layers` is absent or empty → run self-detection (step 2). Do NOT skip rules configuration just because this field is missing — the project may still have layers that need rules.
+
+2. **Self-detection** (only when `detected_layers` is absent/empty from config.json):
+
+   Scan the project to determine which development layers exist. Combine signal matching with your own judgment — the signals below are a guide, not exhaustive.
+
+   | Layer | Where to Look | Signals |
+   |-------|---------------|---------|
+   | **frontend** | `package.json` deps | `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `solid-js`, `preact`, `remix`, `astro`, `qwik` |
+   | **frontend** | `package.json` devDeps | `vite`, `webpack`, `parcel`, `turbo` |
+   | **frontend** | Directory | `src/components/`, `pages/`, `app/` with `.tsx`/`.jsx`/`.vue` files |
+   | **backend** | `package.json` deps | `express`, `fastify`, `koa`, `hono`, `nest` |
+   | **backend** | `pyproject.toml`/`requirements.txt` | `fastapi`, `django`, `flask`, `sanic`, `litestar` |
+   | **backend** | `go.mod` | `gin-gonic`, `echo`, `fiber`, `chi` |
+   | **backend** | `pom.xml`/`build.gradle` | `spring-boot`, `quarkus`, `micronaut`, `ktor` |
+   | **backend** | Directory | `routes/`, `controllers/`, `handlers/`, `api/` with server code |
+   | **database** | `package.json` deps | `prisma`, `typeorm`, `sequelize`, `mongoose`, `knex`, `drizzle-orm`, `kysely` |
+   | **database** | `pyproject.toml`/`requirements.txt` | `sqlalchemy`, `pony`, `peewee`, `tortoise-orm` |
+   | **database** | `go.mod` | `gorm`, `sqlx`, `sqlc`, `ent`, `bun` |
+   | **database** | Directory/Env | `migrations/`, `prisma/`, `alembic/`; `.env*` with `DATABASE_URL`, `DB_HOST`, `MONGO_URI` |
+   | **mobile** | File | `pubspec.yaml` (Flutter) |
+   | **mobile** | `package.json` deps | `react-native`, `expo` |
+   | **mobile** | Directory | Both `ios/*.xcodeproj` + `android/build.gradle` simultaneously |
+
+   **Apply your own judgment**: if you see clear evidence of a layer not covered above, include it. If a signal matches but context suggests it's misleading (e.g., a dependency present but not used as the primary tech), downgrade or ignore it.
+
+   After scanning, present findings via `AskUserQuestion`:
+
+   **Question**: "I detected these development layers: [list with brief evidence]. Is this correct?"
+   - **Yes, looks correct (Recommended)** — use detected layers
+   - **Mostly correct, adjust** — I'll note changes
+   - **No layers apply** — skip rules configuration (library/CLI project)
+
+   If user picks "No layers apply" → skip this entire section, proceed to Prerequisites.
+   If user picks "Mostly correct, adjust" → ask what to add, remove, or change, then reassemble `detected_layers`. Continue to step 3.
+   If user confirms → assemble `detected_layers` array and continue to step 3.
+
+3. For each layer in `detected_layers`, check if `.prizmkit/rules/<layer>-rules.md` exists:
+   - `frontend` → `.prizmkit/rules/frontend-rules.md`
+   - `backend` → `.prizmkit/rules/backend-rules.md`
+   - `database` → `.prizmkit/rules/database-rules.md`
+   - `mobile` → `.prizmkit/rules/mobile-rules.md`
+
+4. Display status:
+
+   ```
+   Rules Status Check:
+     [missing] frontend-rules.md — frontend code detected, no rules configured
+     [exists]  backend-rules.md  — already configured
+     [missing] database-rules.md — database interaction detected, no rules configured
+   ```
+
+5. If all detected layers already have rules → skip to Prerequisites.
+6. If missing rules found, proceed to Step 2.
+
+### Step 2: Ask configuration mode
+
+Use `AskUserQuestion`:
+
+**Question**: "{N} layer(s) without custom dev rules. How would you like to configure?"
+- **Quick setup (only core decisions, rest use recommended defaults)** — covers essential architecture, core technology decisions, and testing questions specific to each layer. Detailed configuration topics (design-system, i18n, performance tuning, deployment details, AI constraints) adopt recommended defaults. See Step 4 for exact per-layer coverage.
+- **Full setup (customize every detail)** — 15-25 questions per layer
+- **Skip — no custom rules needed**
+
+If user picks "Skip" → proceed to Prerequisites.
+
+### Step 3: Select layers to configure
+
+Use `AskUserQuestion` (multiSelect):
+
+**Question**: "Which layers do you want to configure?"
+- Options: the missing layers from Step 1, each with a brief description
+- All pre-selected by default
+
+### Step 4: Configure each selected layer
+
+For each selected layer, run the rules Q&A workflow. This follows the 4-phase rule generation pattern:
+
+**Phase A — Load layer resources:**
+- Read `${SKILL_DIR}/references/rules/<layer>/fixed-rules.md` — industry-consensus rules injected without asking
+- Read `${SKILL_DIR}/references/rules/<layer>/question-bank.md` — interactive questions organized in groups (G1→G10)
+
+**Phase B — Interactive Q&A:**
+- Ask questions one group at a time (max 3 questions per message), as defined in question-bank.md
+- Each question shows a "Recommended" option to reduce decision cost
+- **Quick mode**: ask only the following groups per layer. All other groups adopt recommended defaults silently.
+  - **Frontend**: G1 (Tech Stack), G2 (Styling), G3 (State & Data Fetching), G7 (Testing & Quality). Skip: G4 (Design System), G5 (Responsive), G6 (i18n), G8 (AI Vibecoding), G9 (Performance).
+  - **Backend**: G1 (Language & Runtime), G2 (Framework & Architecture), G3 (API Style), G4 (Data Layer), G7 (Testing & Quality). Skip: G5 (Auth), G6 (Infrastructure), G8 (Observability), G9 (AI Constraints).
+  - **Database**: G1 (Database Selection), G2 (Data Modeling), G3 (Migration), G7 (AI Constraints). Skip: G4 (Index & Performance), G5 (Security & Compliance), G6 (High Availability & Ops).
+  - **Mobile**: G1 (Platform & Language), G2 (Architecture), G3 (UI Framework), G4 (Navigation & State), G7 (Testing). Skip: G5 (Networking & Data), G6 (Platform Features), G8 (App Distribution), G9 (Performance & Accessibility), G10 (AI Constraints).
+- **Full mode**: ask all groups in order (G1→G9 for frontend/backend, G1→G7 for database, G1→G10 for mobile)
+- Shortcut commands work at any point:
+  - `recommended` / `default` → adopt all recommended for current group
+  - `all recommended` → adopt all recommended for all remaining groups
+  - `skip` → mark current group as "Not required at this stage"
+- Record answers in memory after each group.
+
+**Phase C — Auto-derivation:**
+- Read `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`
+- Match user answers against the trigger map using keyword matching
+- Derive platform-specific rules without asking the user (e.g., choosing Flutter → auto-inject Flutter widget/persistence/navigation rules)
+
+**Phase D — Render and write:**
+- Read `${SKILL_DIR}/references/rules/<layer>/template.md`
+- Fill all template placeholders with accumulated content from Phases A+B+C
+- **Post-render self-check**: scan for residual `{{ ` or ` }}` — count must be 0 before writing
+- Generate Appendix A (Deny List) and Appendix B (Recommended Tools) per template instructions
+- Create `.prizmkit/rules/` directory if it doesn't exist
+- Write `.prizmkit/rules/<layer>-rules.md`
+
+### Step 5: Update root.prizm
+
+After all selected layers are configured:
+1. Check if `.prizmkit/prizm-docs/root.prizm` exists.
+2. **If root.prizm exists**:
+   - Read the file.
+   - Check if `RULES:` line exists:
+     - If present: append new rules file paths to the existing line (check for duplicates first — skip paths already on the line).
+     - If absent: add `RULES: .prizmkit/rules/<layer>-rules.md, ...` at the end (after PROJECT_BRIEF line).
+3. **If root.prizm does not exist** (e.g., project without prizm-docs init):
+   - Create a minimal `root.prizm` with:
+     ```
+     PRIZM_VERSION: 2
+     PROJECT: <name>  — from package.json name, directory name, or git repo name
+     MODULE_INDEX:
+     RULES: .prizmkit/rules/<layer>-rules.md, ...
+     ```
+   - The file will be expanded when the project later runs `prizmkit-prizm-docs init`.
+4. The RULES pointer tells every AI session where to find custom dev rules — AI reads rules via this pointer on session start
+
+### After rules configuration
+
+Proceed to Prerequisites and continue the app-planner workflow.
+
+## Prerequisites
+
+Before questions, check optional context files (never block if absent):
+- `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
+- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
+- `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Project Conventions` section (previously answered project conventions)
+- `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section (database and deployment config from prizmkit-init or previous app-planner run)
+
+**Tech stack auto-population from config.json:**
+- If `.prizmkit/config.json` contains a `tech_stack` object, use it to pre-fill tech assumptions.
+- Map config fields: `language`, `runtime`, `frontend_framework`, `frontend_styling`, `backend_framework`, `database`, `orm`, `testing`, `bundler`, `project_type`.
+- Do NOT re-ask for tech stack info already in config.json. Show the detected stack and ask: "Is this correct? Any changes?"
+- If config.json has no `tech_stack`, fall back to asking during Phase 2.
+
+Note:
+- This skill **reads** `.prizmkit/config.json` if present.
+- This skill does **not** create `.prizmkit/config.json` directly.
+- Creation/update is handled by bootstrap/init flows (e.g., `prizmkit-init`, `.prizmkit/dev-pipeline/scripts/init-dev-team.py`).
+
+## Interaction Style (Hard Rule)
+
+**ALL decision points MUST use the `AskUserQuestion` tool** to present interactive, selectable options. Do NOT render options as plain text (e.g., `[A] option [B] option`) — the user must be able to click/select, not type a letter.
+
+This applies to:
+- Intent confirmation
+- Project conventions
+- Tech stack selection
+- Architecture decisions
+- Session exit gates
+- Brownfield prerequisite check
+- Any other decision point
+
+**How to use `AskUserQuestion`:**
+- Each decision point → one `AskUserQuestion` call with 1-4 questions. Use multiple calls as needed — there is NO limit on total rounds for project-level convention discovery. Keep going until everything is covered.
+- Each question has 2-4 selectable options (the tool auto-adds "Other" for custom input)
+- Use `multiSelect: true` when the user can pick more than one
+- Mark the recommended option first and append "(Recommended)" to its label
+- Use the `description` field to explain trade-offs or implications
+- **Every non-essential question MUST include a "Skip" option** (e.g., "Skip — decide later"). Users should never be forced to answer something they want to defer. Skipped items are simply not written to conventions — they can be added in a future session.
+
+**What can be skipped vs. what cannot:**
+- **Cannot skip**: Intent confirmation (must know the session goal)
+- **Everything else can be skipped**: conventions, tech stack choices, architecture decisions, design direction, etc. If the user skips, move on — do not re-ask or block progress.
+
+**When gathering open-ended information** (e.g., "describe your app idea"), use regular text questions — but follow up with `AskUserQuestion`-based clarifications wherever possible.
+
+## Intent Confirmation (Mandatory First Step)
+
+After initial greeting, use `AskUserQuestion` to confirm intent:
+
+**Question**: "What would you like to do?"
+- **Explore ideas first (Recommended)** — brainstorm and refine ideas before committing to a plan
+- **Produce a project plan** — define vision, tech stack, and constraints → generates project-brief.md for pipeline use
+- **Generate project context only** — for an existing project that needs a project brief without full planning
+
+Route by answer:
+- **Produce a project plan** → Continue to Core Workflow. Set session goal = `produce`.
+- **Explore ideas first** → 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, use `AskUserQuestion`: "Ideas are taking shape. What's next?"
+    - **Continue to project planning (Recommended)** — capture tech stack, conventions, and architecture decisions
+    - **Continue refining** — keep brainstorming
+    - **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)
+- **Generate project context only** → Enter **Quick Context Mode** (brownfield only):
+  - Run Project State Detection → if greenfield, redirect to produce mode
+  - 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)
+
+Detect whether this is a **greenfield** (new) or **brownfield** (existing) project and adapt the workflow accordingly.
+
+### Detection Signals
+
+| Signal | Greenfield | Brownfield |
+|--------|-----------|------------|
+| `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `pom.xml` | absent | present |
+| `src/` or `app/` directory with source files | absent | present |
+| `.git` with commit history | absent or initial commit only | present with history |
+| Empty or near-empty directory | yes | no |
+
+### Greenfield Behavior (default)
+
+Proceed with the standard Core Workflow — ask all questions from scratch.
+
+### Brownfield Behavior
+
+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 |
+|------|---------|--------|
+| `.prizmkit/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**, show the status table, then use `AskUserQuestion`:
+
+**Question**: "Some AI context files are missing. These help AI understand your project — making planning much more effective. How would you like to proceed?"
+- **Run project init first (Recommended)** — invoke `prizmkit-init` to scan your codebase and generate these files, then return to planning
+- **Continue without init** — I'll scan the project manually during this session (less thorough)
+- **Skip, I'll set these up later** — proceed with planning using only what's available
+
+- **Run project init first** → Invoke `prizmkit-init`, then resume app-planner from where it left off
+- **Continue without init** → Continue with Step 2 below (manual scan)
+- **Skip** → 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:
+   ```powershell
+   Get-ChildItem -Path . -Directory -Recurse -Depth 2 -ErrorAction SilentlyContinue |
+     Where-Object { $_.FullName -notmatch '\\(node_modules|\.git|dist|build|__pycache__|vendor)(\\|$)' } |
+     Select-Object -ExpandProperty FullName
+   ```
+
+2. **Read existing project metadata** to infer tech stack and purpose:
+   - `package.json` → name, description, dependencies, scripts
+   - `pyproject.toml` / `requirements.txt` → Python dependencies
+   - `go.mod` → Go module info
+   - `README.md` → project description and goals
+   - `.prizmkit/config.json` → previously detected tech stack
+   - `.prizmkit/prizm-docs/root.prizm` → existing architecture context
+
+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**
+
+Show the summary as text, then use `AskUserQuestion`:
+
+> 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]
+
+**Question**: "Does this look correct?"
+- **Yes, looks correct (Recommended)** — proceed with planning
+- **Mostly correct, with changes** — I'll note corrections
+- **This is off** — let me describe the project
+
+**Step 4: Pre-fill and focus**
+
+- 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
+
+**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
+
+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 — 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. Use `AskUserQuestion` for each major tech decision (framework, database, styling, etc.)
+   2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, use `AskUserQuestion`:
+       - Question: "No UI/UX design docs found. Would you like to establish design direction?"
+       - Options: "Establish design direction now (Recommended)", "Skip for now", "I have external designs"
+3. Capture architecture decisions and finalize project brief
+4. Present completion summary with artifacts produced and possible next steps
+
+### Checkpoints (Mandatory Gates)
+
+Checkpoints catch cascading errors early — skipping one means the next phase builds on unvalidated assumptions.
+
+| Checkpoint | Artifact/State | Criteria | Phase |
+|-----------|----------------|----------|-------|
+| **CP-AP-0** | Intent Confirmed | User confirmed session goal (produce / explore) | 1 |
+| **CP-AP-1** | Conventions Checked | Project conventions loaded or asked; `### Project Conventions` section in `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` up to date | 1 |
+| **CP-AP-1.5** | Infrastructure Checked | Infrastructure config loaded or asked; `### Infrastructure` section in `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` addressed — database, deployment **and cloud services** each configured or explicitly deferred | 1-2 |
+| **CP-AP-1.6** | Rules Configured | For each detected layer (from config.json or self-detection), rules file exists in `.prizmkit/rules/` or user explicitly skipped. `root.prizm` `RULES:` pointer up-to-date. | 2 |
+| **CP-AP-2** | Vision Summary | Goal/users/differentiators confirmed by user. For brownfield: existing purpose confirmed or refined. | 1-2 |
+| **CP-AP-3** | Frontend Design Evaluated | For frontend projects: checked for existing UI/UX design system; user was asked if missing. **Auto-pass** for backend-only or non-UI projects. | 2 |
+| **CP-AP-4** | Project Brief Accumulated | `.prizmkit/plans/project-brief.md` exists at `.prizmkit/plans/` with at least 3 ideas listed. For brownfield: already-implemented items marked `[x]` count toward this total. | 3 |
+| **CP-AP-5** | Planning Complete | All project-level context captured: conventions, infrastructure config, tech stack, architecture decisions, project brief finalized | 4 |
+
+## Architecture Decision Capture
+
+After Phase 2, if framework-shaping architecture decisions emerged during planning (tech stack, communication patterns, data model strategies — not individual feature details), read `${SKILL_DIR}/references/architecture-decisions.md` and follow the capture flow. Most sessions will NOT produce architecture decisions — only capture when genuinely impactful.
+
+**How it works**:
+1. If decisions are captured → append to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Architecture Decisions` section
+2. Downstream skills (feature-planner, prizmkit-plan, etc.) read `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` as standard context, so they automatically receive these decisions
+3. Do NOT write architecture decision content directly to `.prizmkit/prizm-docs/root.prizm` — that file is maintained by `prizmkit-prizm-docs` and `prizmkit-retrospective`. (The `RULES:` pointer line is managed by Rules Configuration, not by this section.) If the project needs `.prizmkit/prizm-docs/`, recommend the user run `prizmkit-prizm-docs` init after planning.
+
+## Project Brief Accumulation
+
+During interactive planning, maintain a `.prizmkit/plans/project-brief.md` at `.prizmkit/plans/` as a simple checklist of product ideas.
+
+→ Read `${SKILL_DIR}/references/project-brief-guide.md` for full format and rules.
+
+## Session Exit Gate
+
+Prevent accidental session exit without completing the planning artifacts.
+
+### Trigger Conditions
+
+Activate when ALL true:
+- Session goal = `produce`
+- `.prizmkit/plans/project-brief.md` has not been written or is incomplete (fewer than 3 ideas listed)
+
+### Gate Behavior
+
+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. Use `AskUserQuestion`: "How would you like to proceed?"
+   - **Continue to completion (Recommended)** — finish the project brief
+   - **Save draft & exit** — write current progress as draft to `.prizmkit/planning/`
+   - **Abandon** — exit without saving
+
+## Completion Summary
+
+After all checkpoints pass, present a summary and end the session:
+
+1. **Summary** (as text): List all project-level artifacts produced:
+   - Project conventions → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Project Conventions`
+   - Infrastructure config → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` (database conventions + deployment config)
+   - Tech stack → `.prizmkit/config.json`
+   - Architecture decisions (if any) → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Architecture Decisions`
+   - Dev rules (if configured) → `.prizmkit/rules/<layer>-rules.md` (with `root.prizm` `RULES:` pointer)
+   - Project brief → `.prizmkit/plans/project-brief.md`
+
+2. **Suggest possible next steps** (as text, NOT auto-invoked):
+   > Project-level planning is complete. When you're ready, here are some possible next steps:
+   > - `feature-planner` — decompose the project into features and generate `feature-list.json`
+   > - `prizmkit-plan` — start working on a specific feature directly
+   > - `prizmkit-prizm-docs` — initialize or update project documentation
+   > - `prizmkit-deploy` — supplement infrastructure config or execute deployment (if AI-assisted deploy was configured)
+
+   **Do NOT invoke any of these.** The user decides what to do next, in their own time.