prizmkit 1.1.57 → 1.1.60

package/bundled/skills-windows/feature-planner/assets/planning-guide.md

@@ -0,0 +1,214 @@
+# Feature Planning Reference Guide
+
+This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and session granularity decisions. Use during feature-planner sessions.
+
+For app-level design references (vision templates, tech stack matrix), see `app-planner/assets/app-design-guide.md`. For feature decomposition patterns (CRUD, SaaS, Social, E-commerce), see `${SKILL_DIR}/references/decomposition-patterns.md`.
+
+---
+
+## Feature Description Writing Guide
+
+Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess — producing worse code. Invest in rich descriptions upfront.
+
+### Minimum Word Counts
+
+| Complexity | Hard Minimum (error) | Recommended Minimum (warning below) |
+|------------|---------------------|-------------------------------------|
+| low        | 15                  | 30+                                 |
+| medium     | 15                  | 50+                                 |
+| high       | 15                  | 80+                                 |
+| critical   | 15                  | 100+                                |
+
+Below 15 words is a validation error. Below the recommended minimum triggers a warning.
+
+**There is NO upper limit** — the more detail the better. Rich descriptions prevent the AI from guessing, producing higher quality code. Always aim to describe the feature as thoroughly as possible: what to build, how it should behave, what data it touches, and what edge cases to handle.
+
+### What to Include
+
+Every description should cover these aspects (adapt per feature type):
+
+1. **What to build** — concrete deliverables (API endpoints, UI pages/components, CLI commands, data models)
+2. **Key behaviors** — business rules, validation, state transitions, workflows
+3. **Integration points** — which existing modules, services, or APIs it connects to
+4. **Data model** — entities, relationships, key fields, storage approach (when applicable)
+5. **Error/edge cases** — failure modes, empty states, limits, unauthorized access
+
+### Good vs Bad Examples
+
+**Bad** (17 words — too thin):
+```
+"Build user authentication with login and registration. Support email/password and social login options."
+```
+
+**Good** (78 words — implementation-ready):
+```
+"Implement user authentication with email/password registration and login. Create a User model with fields: id, email (unique), password_hash, display_name, created_at, last_login. Build POST /api/auth/register (validate email format, enforce 8+ char password, check uniqueness, hash with bcrypt, return JWT), POST /api/auth/login (verify credentials, issue JWT with 7-day expiry), and GET /api/auth/me (return current user from JWT). Add auth middleware that validates JWT on protected routes. Handle errors: duplicate email (409), invalid credentials (401), expired token (401)."
+```
+
+**Bad** (12 words):
+```
+"Create the main dashboard page showing project overview and recent activity."
+```
+
+**Good** (65 words):
+```
+"Build a dashboard page at /dashboard as the post-login landing screen. Display: (1) summary cards showing total projects count, active tasks count, and recent activity count; (2) a recent activity feed listing the last 10 actions across all projects with timestamps; (3) a quick-access project list showing the 5 most recently updated projects. Fetch data via GET /api/dashboard/summary. Show loading skeleton on initial load, empty state when user has no projects."
+```
+
+### Headless Execution Requirements
+
+Feature descriptions are consumed by **autonomous AI sessions running in headless mode** — no human is available to clarify ambiguities. This raises the bar for description quality:
+
+**Must include for headless readiness:**
+1. **Concrete deliverables** — specific files, endpoints, components, or models to create
+2. **Integration points** — which existing APIs to call, which models to import, which modules to extend
+3. **Key behaviors** — validation rules, state transitions, error codes, edge cases
+
+**Dependency descriptions:**
+When a feature depends on others, explicitly state what it needs from them:
+- ✅ "Uses the User model (id, email, display_name) from F-001 to create a foreign key user_id on the Project model"
+- ❌ "depends on F-001" — the AI won't know what F-001 built
+
+**Self-test:** Read the description as if you have no other context. Could you implement it without asking a single question? If not, add more detail.
+
+---
+
+## Acceptance Criteria Writing Guide
+
+Acceptance criteria define what "done" means for a feature. They should be specific, testable, and unambiguous.
+
+### Format: Given/When/Then
+
+```
+Given [precondition/context]
+When [action performed]
+Then [expected outcome]
+```
+
+### Examples by Feature Type
+
+**Authentication:**
+
+- Given a new user, When they submit a valid registration form, Then an account is created and a confirmation email is sent.
+- Given a registered user, When they enter correct credentials, Then they are logged in and redirected to the dashboard.
+- Given a logged-in user, When their session expires, Then they are redirected to the login page with a message.
+
+**CRUD Operations:**
+
+- Given an authenticated user, When they create a new [entity] with valid data, Then the entity is saved and appears in the list.
+- Given an entity list, When the user applies filters, Then only matching entities are displayed.
+- Given an entity owner, When they delete the entity, Then it is removed after confirmation.
+
+**Real-time:**
+
+- Given two users viewing the same board, When one makes a change, Then the other sees it within 2 seconds without a page refresh.
+- Given a user is offline, When they reconnect, Then missing updates are synced.
+
+### Writing Principles
+
+1. **One behavior per criterion.** Each criterion tests exactly one thing.
+2. **No implementation details.** Criteria describe what, not how. Say "user is redirected" not "React Router navigates to /dashboard."
+3. **Include edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions.
+4. **Be measurable.** Where performance matters, include specific thresholds (e.g., "within 2 seconds").
+5. **Keep the count manageable.** A feature with more than 8 acceptance criteria may need to be split into sub-features.
+
+---
+
+## Complexity Estimation Guide
+
+| Complexity | Characteristics | Typical Scope | Pipeline Tier |
+|------------|----------------|---------------|---------------|
+| low | Single module, straightforward CRUD, minimal UI | 1-2 API endpoints, 1-2 pages | lite (1 agent) |
+| medium | Multiple modules, business logic, moderate UI | 3-5 API endpoints, 2-4 pages | lite (1 agent) |
+| high | Cross-cutting concerns, complex state, advanced UI | 5+ API endpoints, complex interactions | standard (3 agents) |
+| critical | Architectural changes, 10+ files, multi-module API surface changes | System-wide refactoring, new infrastructure + app logic | full (5 agents + critic) |
+
+### Complexity Red Flags
+
+Consider splitting a feature if it exhibits any of the following:
+
+- More than 8 acceptance criteria.
+- Touches more than 3 distinct modules or layers.
+- Requires both frontend and backend architectural decisions.
+- Involves third-party service integration AND non-trivial business logic.
+- Contains both real-time and batch processing requirements.
+- Needs new infrastructure (e.g., message queue, search index) AND application logic.
+
+### Estimation Consistency Rules
+
+- If a feature is marked as "low" complexity, it should not have more than 5 acceptance criteria.
+- If a feature is marked as "high" complexity, it should have a clear justification (e.g., "involves payment processing with webhook handling and idempotency").
+- Use "critical" complexity only for features requiring architectural changes that touch 10+ files, involve cross-module API surface changes, or need multi-critic voting for safety.
+- When in doubt, estimate higher -- it is better to over-allocate than to under-allocate.
+
+---
+
+## Dependency Graph Rules
+
+These rules ensure the feature dependency graph is valid and buildable.
+
+1. **F-001 has zero dependencies.** The first feature is always infrastructure or project setup. It must be buildable from scratch with no preconditions.
+
+2. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG). If A depends on B and B depends on A, restructure the features.
+
+3. **Minimal dependency sets.** Each feature should depend only on the features it directly needs. Do not add transitive dependencies explicitly. If F-003 depends on F-002 and F-002 depends on F-001, then F-003 does NOT need to list F-001 as a dependency.
+
+4. **Auth comes early.** Most features depend on authentication. Place auth-related features (registration, login, session management) as early in the graph as possible, typically F-002.
+
+5. **Data model before display.** Features that create or define data entities must precede features that display, search, or manipulate that data.
+
+6. **Infrastructure before everything.** Database setup, project scaffolding, CI/CD configuration, and environment setup belong in F-001.
+
+7. **Independent features can be parallel.** If two features share no dependencies on each other, they can be built in parallel. The dependency graph should reflect this by not artificially linking them.
+
+### Validation Checklist
+
+- [ ] F-001 has an empty dependency list.
+- [ ] No feature depends on itself.
+- [ ] No circular dependency chains exist.
+- [ ] Every feature ID referenced in a dependency list is defined in the plan.
+- [ ] The graph can be topologically sorted (i.e., there exists a valid build order).
+
+---
+
+## Session Granularity Decision Rules
+
+Session granularity determines whether a feature is implemented in a single coding session or split across multiple sub-feature sessions.
+
+### Decision Table
+
+| Condition | Granularity | Notes |
+|-----------|-------------|-------|
+| Acceptance criteria <= 5 | `feature` | Single session can handle it |
+| Acceptance criteria 6-8 | `feature` or `auto` | Use judgment based on complexity |
+| Acceptance criteria > 8 | `auto` | Define sub_features |
+| Touches <= 2 modules | `feature` | Focused enough for one session |
+| Touches 3+ modules | `auto` | Split by module boundary |
+| Complexity "low" | `feature` | Always single session |
+| Complexity "high" + many criteria | `auto` | Always consider splitting |
+
+### Sub-Feature Naming Convention
+
+When using `auto` granularity with sub-features, name each sub-feature with the parent feature ID as a prefix:
+
+```
+F-003-A: Backend API for [entity] CRUD
+F-003-B: Frontend UI for [entity] management
+F-003-C: Integration tests for [entity] workflows
+```
+
+### Sub-Feature Design Principles
+
+1. **Independently testable.** Each sub-feature should produce a verifiable result on its own. A backend API sub-feature can be tested via API calls without the frontend.
+
+2. **Single concern.** Each sub-feature focuses on one layer or aspect: backend API, frontend UI, data migration, integration, etc.
+
+3. **Clear boundaries.** The interface between sub-features should be well-defined (e.g., API contracts between backend and frontend sub-features).
+
+4. **Ordered when necessary.** Sub-features within a feature may have internal ordering (e.g., backend before frontend), but this should be captured in the sub-feature dependencies.
+
+### When NOT to Split
+
+- If the feature is inherently atomic (e.g., "add a favicon" or "configure environment variables").
+- If splitting would create sub-features that are too small to justify a separate session (fewer than 2 acceptance criteria each).
+- If the feature involves tightly coupled frontend and backend logic where splitting would require extensive mocking.

package/bundled/skills-windows/feature-planner/references/browser-interaction.md

@@ -0,0 +1,59 @@
+# Browser Interaction Planning
+
+For web apps with UI, features that involve user-facing pages or interactive flows can optionally include a `browser_interaction` field. This enables the dev-pipeline to verify UI behavior automatically after implementation using the configured browser tool (`playwright-cli` or `opencli`).
+
+## Browser Tool Selection (Mandatory — Ask User)
+
+Before auto-generating `browser_interaction` for features, you MUST ask the user which browser tool to use as the project default via `AskUserQuestion`:
+
+**Question**: "Which browser verification tool should this project use by default?"
+- **Auto — AI chooses per feature (Recommended)** — `playwright-cli` for local UI, `opencli` for authenticated flows. AI decides per-feature at planning time.
+- **playwright-cli** — isolated browser instance, no login state. Best for local dev server, forms, components.
+- **opencli** — reuses Chrome's logged-in sessions via Browser Bridge. Best for OAuth, third-party dashboards, SSO.
+
+Store the user's choice as the project-level default. Individual features can still override (see Tool Selection per Feature below).
+
+## How to Capture
+
+During Phase 4.2, auto-generate `browser_interaction` for all qualifying features (see SKILL.md §Browser Interaction Planning for auto-detection rules). Present a **batch summary** to the user showing which features received `browser_interaction` — do NOT ask per-feature. The user can opt out specific features from the summary.
+
+For each qualifying feature, generate the `browser_interaction` object:
+
+```json
+{
+  "browser_interaction": {
+    "tool": "auto",
+    "verify_steps": [
+      "Verify login form renders with email and password fields",
+      "Verify valid credentials redirect to dashboard",
+      "Verify invalid password shows error message"
+    ]
+  }
+}
+```
+
+## Field Rules
+
+- `tool` selects the browser verification tool. Values: `"playwright-cli"`, `"opencli"`, `"auto"` (default).
+  - **`"auto"`** (default): AI chooses at runtime based on available tools and scenario. Recommended for most cases.
+  - **`"playwright-cli"`**: Isolated browser instance, no login state. Best for local dev server verification, form testing, component rendering checks.
+  - **`"opencli"`**: Reuses Chrome's logged-in sessions via Browser Bridge. Best for verifying third-party integrations (OAuth callbacks, API dashboards), features requiring real authentication state, or pages behind SSO.
+
+  | Scenario | Recommended `tool` |
+  |----------|-------------------|
+  | Local dev server, pure frontend components | `playwright-cli` |
+  | Needs real login state (e.g., OAuth redirect page) | `opencli` |
+  | Third-party API integration dashboard verification | `opencli` |
+  | Headless CI environment | `playwright-cli` |
+  | Unsure / mixed scenarios | `auto` |
+
+- `verify_steps` are **verification goals**, not specific tool commands. Describe WHAT to verify, not HOW to verify it. The pipeline AI will:
+  1. Auto-detect the dev server start command from project config (`package.json`, `Makefile`, etc.)
+  2. Start the server and discover the URL/port at runtime
+  3. Use `playwright-cli snapshot` to discover real element refs
+  4. Decide the concrete click/fill/assert operations itself
+  This works better than prescribing URLs/commands at planning time because: (1) ports may differ across environments, (2) element refs don't exist yet, (3) UI structure may change during implementation, (4) the AI has full context of the actual code when it runs verification.
+  - **Good**: `"Verify login form accepts valid credentials and redirects to dashboard"`
+  - **Bad**: `"click <ref> — click login button"` (guesses at refs that don't exist yet)
+- Do NOT specify `url`, `setup_command`, or `port` — the AI detects these at runtime from the actual project configuration
+- An empty `browser_interaction: {}` object (no verify_steps) is valid — the AI will explore the app and verify the feature works as expected

package/bundled/skills-windows/feature-planner/references/completeness-review.md

@@ -0,0 +1,57 @@
+# Pre-Generation Completeness Review
+
+Before generating `.prizmkit/plans/feature-list.json`, review the full feature set holistically. Individual features may look fine in isolation but have gaps when viewed together.
+
+## Step 1: Description Adequacy Scan
+
+For each feature, evaluate against the word-count thresholds in `planning-guide.md`:
+- Does the description cover: what to build, key behaviors, integration points, data model (if applicable), error/edge cases?
+- Is the description specific enough for an AI coding session to implement without guessing?
+- Flag any feature below the recommended minimum word count for its complexity level (30+/50+/80+/100+ words for low/medium/high/critical). There is no upper limit — more detail is always better.
+
+**Implementation clarity check** — Every feature description will be consumed by an autonomous AI session. Verify each description specifies:
+1. Concrete deliverables (files to create, endpoints to build, components to implement, models to define)
+2. Key behaviors and business rules (validation, state transitions, error handling)
+3. Integration points with other modules (which APIs to call, which models to use)
+
+**Dependency context check** — If the feature depends on others, the description should reference what it needs from them:
+- Good: "Uses User model from F-001 to link projects to users via userId foreign key"
+- Bad: "depends on F-001" (too vague)
+
+**Ambiguity check** — Flag vague phrases:
+- Bad: "Create a nice dashboard" (what components? what data? what layout?)
+- Good: "Create dashboard at /dashboard with: (1) summary cards showing total projects count, active tasks count; (2) recent activity feed (last 10 items); (3) quick-access project list (5 most recent). Fetch data via GET /api/dashboard/summary."
+
+If any feature description is unclear, **expand it now** before generating the output file.
+
+## Step 2: Cross-Feature Completeness Check
+
+Look at the feature set as a whole:
+- **Implied functionality gaps**: Does feature A's acceptance criteria assume a capability that no other feature provides?
+- **Missing integration seams**: If two features share data or interact at runtime, is the interface specified?
+- **Scope leaks**: Does any feature's description reference functionality outside the agreed scope?
+
+## Step 3: Present Review to User
+
+Show a structured summary table:
+
+```
+Feature    | Description | Cross-Feature        | Recommendation
+           | Adequacy    | Issues               |
+F-001      | ✓ (65 words)| —                    | Ready
+F-002      | ⚠ (28 words)| —                    | Expand: add API endpoints, error handling
+F-003      | ✓ (52 words)| Assumes email from   | Clarify: who sends the notification?
+           |             | F-006 (not yet defined)|
+```
+
+Then ask if any features need further discussion.
+
+## Step 4: Interactive Supplementation
+
+For each feature the user wants to discuss:
+1. Ask targeted questions about the unclear aspects
+2. Propose concrete description supplements
+3. Update the feature description with agreed details
+4. Re-check: does the supplement resolve the gap?
+
+Continue until the user confirms all features are implementation-ready. Fixing thin descriptions here costs minutes; fixing misimplemented features downstream costs hours.

package/bundled/skills-windows/feature-planner/references/decomposition-patterns.md

@@ -0,0 +1,75 @@
+# Feature Decomposition Patterns
+
+Use these patterns as starting points when breaking an app into features. Adapt them to the specific project.
+
+For app-level design references (vision templates, tech stack decision matrix), see `app-planner/assets/app-design-guide.md`.
+
+## Pattern A: CRUD-Based App
+
+Examples: CMS, project management tools, inventory systems.
+
+```
+F-001: Infrastructure Setup (no deps)
+F-002: User Authentication (deps: F-001)
+F-003: Core Entity CRUD (deps: F-002)
+F-004: Entity Relationships (deps: F-003)
+F-005: Search & Filtering (deps: F-003)
+F-006: Notifications (deps: F-003)
+F-007: Admin Dashboard (deps: F-004, F-005)
+F-008: Analytics & Reporting (deps: F-007)
+```
+
+## Pattern B: SaaS Platform
+
+Examples: subscription services, multi-tenant tools, B2B products.
+
+```
+F-001: Infrastructure + Multi-tenant Setup (no deps)
+F-002: User Auth + Organization Management (deps: F-001)
+F-003: Core Product Feature (deps: F-002)
+F-004: Subscription & Billing (deps: F-002)
+F-005: Usage Tracking & Limits (deps: F-003, F-004)
+F-006: Admin Portal (deps: F-005)
+F-007: API & Integrations (deps: F-003)
+F-008: Analytics Dashboard (deps: F-006, F-007)
+```
+
+## Pattern C: Social/Community App
+
+Examples: forums, social networks, community platforms.
+
+```
+F-001: Infrastructure Setup (no deps)
+F-002: User Auth + Profiles (deps: F-001)
+F-003: Content Creation (posts/media) (deps: F-002)
+F-004: Social Graph (follow/friend) (deps: F-002)
+F-005: Feed Algorithm (deps: F-003, F-004)
+F-006: Interactions (likes, comments) (deps: F-003)
+F-007: Real-time Messaging (deps: F-004)
+F-008: Notifications (deps: F-005, F-006, F-007)
+F-009: Discovery & Search (deps: F-005)
+```
+
+## Pattern D: E-commerce App
+
+Examples: online stores, marketplaces, booking platforms.
+
+```
+F-001: Infrastructure Setup (no deps)
+F-002: User Auth (deps: F-001)
+F-003: Product Catalog (deps: F-001)
+F-004: Shopping Cart (deps: F-002, F-003)
+F-005: Checkout & Payment (deps: F-004)
+F-006: Order Management (deps: F-005)
+F-007: Inventory Management (deps: F-003)
+F-008: Reviews & Ratings (deps: F-002, F-003)
+F-009: Search & Recommendations (deps: F-003, F-008)
+F-010: Admin Dashboard (deps: F-006, F-007)
+```
+
+## Decomposition Guidelines
+
+- Every app starts with an infrastructure/setup feature (F-001) that has zero dependencies.
+- Authentication almost always comes second unless the app is fully public.
+- Group related functionality into single features rather than splitting too finely. A feature should represent a coherent unit of user-facing value.
+- If a pattern does not match the app being planned, combine elements from multiple patterns or define a custom decomposition from scratch.

package/bundled/skills-windows/feature-planner/references/error-recovery.md

@@ -0,0 +1,90 @@
+# Error Recovery & Resume Support
+
+Structured error handling for validation failures, interrupted sessions, and checkpoint-based resumption.
+
+## Validation Failures
+
+When `Invoke-PrizmPython scripts/validate-and-generate.py validate --input <file> --mode <mode>` returns errors:
+
+### Parse validation output
+Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]`
+
+### Decision Tree
+
+**if `error_count == 0` (warnings only):**
+- Proceed with user approval
+- Show warnings and ask: "Continue? (Y/n)"
+
+**elif `error_count > 0` (critical errors):**
+
+Group errors by type and apply targeted fixes:
+
+| Error Type | Symptom | Fix Offered | Auto-Fix? |
+|-----------|---------|------------|-----------|
+| **Schema mismatch** | `$schema` invalid, missing `project_name`, wrong `features` type | "Set `$schema` to `dev-pipeline-feature-list-v1`, `project_name` to string" | Yes |
+| **Feature ID issues** | Invalid format (not `F-NNN`), duplicate IDs, undefined refs | "Suggest corrected IDs, show duplicates" | Yes |
+| **Dependency errors** | Circular dependency, undefined target features | "Show cycle chain (e.g., `F-003 → F-005 → F-003`), suggest break point" | No |
+| **Missing fields** | Feature missing required keys (title, description, AC) | "List each feature + missing keys, guide patch" | Partial |
+| **Insufficient AC** | Feature has <2 acceptance criteria | "Show feature, suggest AC examples" | No |
+| **Invalid values** | complexity not in [low/medium/high/critical], status not pending | "Show field, valid values" | Yes |
+
+### Execution
+
+```
+For auto-fixable errors:
+  1. Show summary: "Found N schema/ID/format issues"
+  2. Offer: auto-fix? (Y/n)
+  3. Apply fix → regenerate file
+  4. Re-run validation
+  5. If new errors → loop (max 2 more attempts)
+
+For manual fixes (dependencies, AC content):
+  1. Show concise prompt: "Edit line X-Y in feature-list.json"
+  2. Wait for user action
+  3. Retry validation (max 2 more attempts)
+
+if all_retries_exceeded:
+  → Escalate: "After 3 attempts, validation still fails.
+              (a) Review file manually, OR
+              (b) Restart planning from Phase 1"
+```
+
+## Resume Support
+
+feature-planner sessions can be resumed from the last completed checkpoint when artifacts are found.
+
+### Detection Logic
+
+Check for artifact files in `.prizmkit/plans/`:
+
+| Artifacts Found | Resume Action |
+|-----------------|---------------|
+| None | Start fresh planning (Phase 1) |
+| `feature-list.json` exists but not validated | Offer to validate or extend (Phase 9) |
+| `feature-list.json` + validation passed | Offer: handoff to `feature-pipeline-launcher` |
+| `feature-list.draft.json` only | Resume interactive planning from last checkpoint |
+
+When existing file detected, suggest:
+> "Existing plan found with N features. Resume incremental planning? (Y/n)"
+
+### Incremental Mode Abort
+
+If in Incremental mode but existing `feature-list.json` not found:
+- Ask: "Start new plan or provide existing file?"
+- If new plan chosen → switch to Route A (New Feature Set)
+
+### Artifact Path Convention
+
+**CRITICAL PATH RULE**: `feature-list.json` MUST be written to `.prizmkit/plans/` directory.
+
+Before writing, verify the directory exists: `New-Item -ItemType Directory -Force -Path .prizmkit/plans | Out-Null`
+
+```
+<project-root>/
+  └── .prizmkit/plans/
+      ├── feature-list.json              # Primary output
+      ├── feature-list.draft.json        # Draft backup (Session Exit Gate)
+      └── <ISO-timestamp>.backup.json    # Optional incremental backups
+```
+
+> **Note**: For cross-session workflow recovery (e.g., interrupted pipeline execution, branch-level state detection), use `recovery-workflow` instead. This error-recovery reference handles only within-session validation retries and checkpoint resumption.

package/bundled/skills-windows/feature-planner/references/incremental-feature-planning.md

@@ -0,0 +1,112 @@
+# Incremental Feature Planning Reference
+
+Use this reference when the user adds features to an existing app/plan.
+
+## Pre-Checks
+
+1. Read existing `feature-list.json`.
+2. Determine current max ID and continue from next `F-NNN`.
+3. **Detect existing writing style** (see §Style Detection below).
+4. Preserve compatibility with existing dependency structure.
+5. **Project conventions** — handled by the main SKILL.md flow (rule #6) before incremental planning begins. No additional action needed here; conventions are loaded automatically.
+
+If `feature-list.json` is missing, ask whether to initialize a new plan.
+
+## Style Detection (Automatic)
+
+Before drafting new features, analyze existing plan to preserve consistency:
+
+1. **Language Detection**
+   - Scan `title` and `description` fields
+   - If >70% English titles → default to English
+   - If >70% Chinese titles → suggest Chinese (or allow bilingual)
+
+2. **Description Density**
+   - Calculate avg word count per description
+   - If avg <30 words → draft concise descriptions
+   - If avg 30-80 words → draft standard detail
+   - If avg >80 words → draft detailed descriptions
+
+3. **Acceptance Criteria Patterns**
+   - Count avg AC per feature
+   - Identify dominant format (Given/When/Then Gherkin, BDD, or loose)
+   - Draft new AC in same format
+
+4. **Complexity Distribution**
+   - Count low/medium/high distribution in existing features
+   - Alert if new features deviate significantly (>20 percentile points)
+   - Suggest rebalancing if needed
+
+### Style Consistency Prompt
+
+If new features deviate significantly from detected style:
+
+```
+"Your new features use avg X words/description, but existing features use Y.
+Current ratio: low:M%, medium:N%, high:O%.
+Adjust new features to match? (Y/n)"
+```
+
+Accept user choice, then adjust draft accordingly before JSON generation.
+
+## Incremental Planning Flow
+
+### Step 1: Clarify Increment Scope
+Capture:
+- business objective of the new increment
+- affected existing modules/features
+- timeline or priority constraints
+
+### Step 2: Impact Mapping
+For each candidate feature, identify:
+- upstream dependencies
+- downstream impacts
+- risk hotspots (auth, data migration, API compatibility)
+
+### Step 3: Append Features
+Append new items only (do not rewrite old validated features unless user asks).
+
+For each new feature:
+- assign next ID
+- set `status: "pending"`
+- link dependencies to existing IDs where needed
+- keep title in English
+- **write rich descriptions** (see `planning-guide.md` §4):
+  - minimum 15 words (validation error below this)
+  - recommended minimum: 30+ (low), 50+ (medium), 80+ (high), 100+ (critical) — no upper limit, more detail is always better
+  - include: what to build, key behaviors, integration points, data model, error/edge cases
+
+### Step 4: Rebalance Priority
+Allow priority updates for both old and new features if user requests reprioritization.
+Keep dependency correctness as first constraint.
+
+### Step 5: Validate
+Run after defining `Invoke-PrizmPython` from the main `SKILL.md`:
+```powershell
+Invoke-PrizmPython ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json --mode incremental
+```
+
+Fix and re-run until pass.
+
+## Merge/Rewrite Rules
+
+- Default: append only
+- Rewrite existing features only when user explicitly asks
+- Never break valid IDs/references
+- Never set new features to `in_progress` or `completed`
+
+## Practical Prompts
+
+Use concise prompts during interaction:
+- "What is the goal of this increment? Which user problem is the priority?"
+- "Which existing Feature IDs do these new features depend on?"
+- "Do you want to reprioritize at the same time, or just append to the current sequence?"
+
+## Final Delivery Checklist
+
+- [ ] Existing file read before edits
+- [ ] New IDs continue sequence
+- [ ] Existing style preserved
+- [ ] Dependency graph still DAG
+- [ ] Validation passes
+- [ ] Next step recommendation: `feature-pipeline-launcher`