prizmkit 1.0.13 → 1.0.14

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

@@ -1,580 +1,333 @@
 ---
 name: "app-planner"
-description: "Interactive app planning that produces feature-list.json for dev-pipeline. Invoke when user wants to plan an app, design features, or prepare for automated development."
+description: "Interactive planning for both new apps and incremental features on existing apps. This skill should be used whenever users discuss app planning, feature scoping/re-prioritization, continuing a feature plan, or preparing a validated feature-list.json for dev-pipeline execution."
 ---
 
 # App Planner
 
-This skill guides an AI assistant through a structured, interactive conversation with the user to plan a new application from scratch. The final output is a validated `feature-list.json` file that serves as the input contract for the `dev-pipeline` module, which will autonomously implement each feature via multi-agent team sessions.
+Plan deliverable features for dev-pipeline in two modes:
+- **New App Planning**: create a plan from scratch
+- **Incremental Feature Planning**: append new features to an existing app/plan
 
-## Installation
-
-The `${SKILL_DIR}` placeholder represents the absolute path to this skill's directory. It is automatically resolved by the environment when the skill is invoked.
+Always produce a validated `feature-list.json` that conforms to `dev-pipeline-feature-list`.
 
 ## When to Use
 
-**Trigger this skill when the user says any of the following (or similar):**
-
-- "Plan an app", "Design a new application", "I want to build an app"
-- "Create a feature list", "Prepare for dev-pipeline", "Generate feature-list.json"
-- "Let's plan what to build", "Help me scope out my project"
-- "I have an app idea", "Break down my app into features"
+Trigger this skill for requests like:
+- "规划应用", "设计项目", "Plan an app", "Design a new application"
+- "给现有系统加功能", "继续规划", "Add features", "Continue planning"
+- "准备 feature-list.json", "Prepare dev-pipeline input"
+- "重排优先级", "拆分功能", "reprioritize/scope features"
 
-Chinese triggers (zhong wen chu fa):
-- "规划一个应用", "设计一个新项目", "帮我拆分功能"
-- "生成功能列表", "准备 dev-pipeline 输入"
+Do NOT use this skill when:
+- user only wants to run pipeline now (invoke `dev-pipeline-launcher`)
+- user is debugging/refactoring unrelated to feature planning
 
-**Also trigger this skill when:**
+## Resource Loading Rules (Mandatory)
 
-- "Add new features to the plan", "Continue planning", "Plan next features"
-- "继续规划", "添加新功能到计划中"
+`SKILL_DIR` definition:
+- `SKILL_DIR` is the absolute path of this skill directory.
+1. **Choose scenario reference before planning**:
+   - New app → read `references/new-app-planning.md`
+   - Existing app incremental features → read `references/incremental-feature-planning.md`
 
-When adding features to an existing plan, read the existing `feature-list.json` first, then continue numbering from the next available F-NNN ID. Match the existing style (language, description detail level, acceptance criteria format).
+2. **Use shared quality examples as needed**:
+   - read `assets/planning-guide.md` for decomposition and acceptance criteria patterns
 
-**DO NOT use this skill when:**
+3. **Always validate output via script**:
+   - run:
+     ```bash
+     python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input <output-path> --mode <new|incremental>
+     ```
 
-- The user is fixing a bug or doing a refactor
-- The user just wants to run the dev-pipeline (direct them to `./dev-pipeline/run.sh` instead)
+4. **Use script output as source of truth**:
+   - if validation fails, fix and re-run until pass
 
 ## Prerequisites
 
-Before starting the planning conversation, check for optional context files. These are NOT required -- the skill works on blank projects.
-
-1. **Existing project context** (optional): If `.prizm-docs/root.prizm` exists, read it for architecture and tech stack context.
-2. **Existing config** (optional): If `.prizmkit/config.json` exists, read it for pre-configured tech stack preferences.
-3. **Existing spec** (optional): If the user mentions a specification document, read it and use it to pre-populate feature ideas.
-
-If none of these exist, proceed directly to Phase 1. Do not block on missing files.
-
-## Interactive Planning Workflow
-
-CRITICAL: This is a conversation-driven skill. You MUST ask questions and wait for user responses at each phase. Do NOT generate the entire plan in one shot. The value of this skill is the iterative dialogue.
-
----
-
-### Phase 1: App Vision (1-3 questions)
-
-**Goal**: Understand the core purpose, audience, and differentiation of the application.
-
-Ask these questions one at a time (or grouped if the user prefers concise interaction):
-
-1. **What is the app?** -- "Describe the application you want to build. What problem does it solve?"
-2. **Who are the target users?** -- "Who will use this app? What are their primary needs?"
-3. **What makes it unique?** -- "What is the core value proposition? What differentiates it from existing solutions?"
-
-**AI Behavior:**
-- Summarize the user's vision back to them in 2-3 sentences before proceeding.
-- If the vision is vague, ask follow-up questions to clarify scope.
-- If the user provides a spec document, extract answers from it and confirm with the user.
-
----
-
-### Phase 2: Tech Stack Decision (1-2 questions)
-
-**Goal**: Establish the technical foundation that will populate `global_context` in the output.
-
-Present a structured choice for each category. Suggest defaults based on the app type, but let the user override.
-
-**Categories to decide:**
-
-| Category | Common Options | Default Suggestion |
-|----------|---------------|-------------------|
-| Frontend | React/Next.js, Vue/Nuxt, Svelte/SvelteKit, Angular | Next.js 14 |
-| Backend | Express, FastAPI, Django, NestJS, Go/Gin | Express.js |
-| Database | PostgreSQL, MySQL, MongoDB, SQLite | PostgreSQL |
-| ORM | Prisma, TypeORM, Drizzle, SQLAlchemy | Prisma |
-| Auth | NextAuth, Clerk, Supabase Auth, custom JWT | NextAuth |
-| Design System | shadcn/ui, Ant Design, Material UI, Chakra UI | shadcn/ui + Tailwind CSS |
-| Testing | Jest + Playwright, Vitest + Cypress, pytest | Jest + Playwright |
-| Language | TypeScript, Python, Go | TypeScript |
-
-**AI Behavior:**
-- Present the table above (adapted to the app type) and let the user confirm or modify.
-- If the user has no preference, use the defaults.
-- Record the final tech stack -- it maps directly to `global_context` in the output.
-- If `.prizmkit/config.json` was read in Prerequisites, pre-fill from that config.
-
----
-
-### Phase 3: Feature Brainstorming (iterative)
-
-**Goal**: Collaboratively build a comprehensive, well-structured feature list.
-
-**Step 3a: Initial Proposal**
-
-Based on the app vision and tech stack, propose an initial feature breakdown. Follow these rules:
-
-- Feature F-001 MUST be "Project Infrastructure Setup" (scaffolding, configs, CI basics). This is always the first feature with zero dependencies.
-- Feature F-002 is typically "User Authentication" (if applicable).
-- Subsequent features should follow a logical build order.
-- Aim for 5-12 features for an MVP. Fewer than 5 usually means features are too coarse. More than 15 usually means features are too granular.
-
-Present each feature as:
-
-```
-F-001: Project Infrastructure Setup
-  Description: Initialize the project with [framework], database connection, linting, and CI config.
-  Complexity: medium
-  Dependencies: (none)
-  Acceptance Criteria:
-    - [framework] app runs on expected port
-    - Database connection verified
-    - TypeScript compiles without errors
-    - Linter and formatter configs applied
-```
-
-**Step 3b: User Review**
-
-Ask the user to review the proposed features:
-- Add any missing features
-- Remove features that are out of scope
-- Modify descriptions or acceptance criteria
-- Split features that are too large
-- Merge features that are too small
-
-**Step 3c: Detail Refinement**
-
-For each feature (after the user approves the overall list), ensure:
-
-1. **Description** is detailed enough for a development team to implement without additional context. It should describe WHAT to build, not HOW to build it.
-2. **Acceptance Criteria** follow Given/When/Then style where applicable, with a minimum of 3 criteria per feature. Examples:
-   - "Given a logged-in user, when they click 'Create Task', then a new task form appears"
-   - "Users can register with email and password"
-   - "API returns 401 for unauthenticated requests"
-3. **Dependencies** are explicitly listed by F-NNN ID.
-4. **Complexity** is estimated as low/medium/high.
-
-Iterate on Step 3b and 3c until the user says they are satisfied.
-
----
-
-### Phase 4: Dependency Graph and Ordering
-
-**Goal**: Validate the dependency chain and confirm execution order.
-
-**Step 4a: Dependency Validation**
-
-Check the proposed dependencies for:
-- **No cycles**: Dependencies MUST form a Directed Acyclic Graph (DAG). If a cycle is detected, ask the user to resolve it.
-- **No orphans with unmet deps**: Every dependency target must exist in the feature list.
-- **F-001 has no dependencies**: The infrastructure feature is always the root.
-
-**Step 4b: Execution Order Visualization**
-
-Present the dependency chain as a text-based graph:
-
+Before questions, check optional context files (never block if absent):
+- `.prizm-docs/root.prizm` (architecture/project context)
+- `.prizmkit/config.json` (existing stack preferences)
+- existing `feature-list.json` (required for incremental mode)
+
+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`, `dev-pipeline/scripts/init-dev-team.py`).
+
+## Scenario Routing
+
+Classify user intent first:
+
+### Route A: New App Planning
+Use when user starts from idea/blank slate or asks for initial end-to-end plan.
+
+Actions:
+1. Load `references/new-app-planning.md`
+2. Run interactive planning phases
+3. Generate initial `feature-list.json`
+
+### Route B: Incremental Feature Planning
+Use when user already has app/code/plan and asks to add or adjust features.
+
+Actions:
+1. Load `references/incremental-feature-planning.md`
+2. Read existing `feature-list.json` first (if missing, ask whether to start new plan)
+3. Append features with next sequential `F-NNN` IDs
+4. Preserve style/language/detail consistency with existing plan
+
+## Core Workflow
+
+Execute the selected scenario workflow in conversation mode with mandatory checkpoints:
+
+### Interactive Phases
+1. clarify business goal and scope
+2. confirm constraints and tech assumptions
+3. propose feature set with dependencies
+4. refine descriptions and acceptance criteria
+5. verify DAG/order/priorities
+6. build or append `feature-list.json`
+7. validate and fix until pass
+8. summarize final feature table
+
+### Checkpoints (Mandatory Gates)
+
+Never skip checkpoints. If any checkpoint fails, follow error recovery flow (see §Error Recovery).
+
+| Checkpoint | Artifact/State | Criteria | Phase |
+|-----------|----------------|----------|-------|
+| **CP-AP-1** | Vision Summary | Goal/users/differentiators confirmed by user | 1-2 |
+| **CP-AP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
+| **CP-AP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 6 |
+| **CP-AP-4** | `feature-list.json` Generated | Schema validates, all required keys present | 6 |
+| **CP-AP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 7 |
+
+**Resume Detection**: See §Resume Support for checkpoint-based resumption.
+
+## Fast Path — Incremental Shortcuts
+
+For simple incremental planning, skip detailed Phase 2-3 analysis to accelerate delivery:
+
+### Eligibility Criteria (ALL must apply)
+- **Incremental mode only** — not new app planning
+- **Adding 1-2 features max** to existing plan
+- **Each feature**: ≤5 acceptance criteria, <100 words description
+- **Dependencies**: depends on ≤2 existing features (no chains)
+- **Complexity**: "low" or "medium" only
+- **No architectural changes** to existing tech stack
+
+### Fast Path Workflow
+1. Read existing `feature-list.json` and confirm scope
+2. Generate next sequential feature IDs
+3. Draft features (title + description + acceptance_criteria + dependencies)
+4. Run validation script immediately
+5. If valid → summarize and recommend next step
+6. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+
+### When NOT to Use Fast Path
+- New app planning (always use full workflow)
+- Adding >2 features in one session
+- Features with complex interdependencies (>2 dependencies)
+- High complexity features requiring architecture decisions
+- Changes affecting >3 existing features
+
+### Example Fast Path Session
 ```
-F-001: Project Infrastructure Setup
-  |
-  +-- F-002: User Authentication
-  |     |
-  |     +-- F-003: Task CRUD Operations
-  |           |
-  |           +-- F-004: Project & Team Management
-  |           |
-  |           +-- F-005: Real-time Updates
-  |                 |
-  |                 +-- F-006: Analytics Dashboard (also depends on F-004)
+User: "Add email verification to existing user module."
+AI: [Detects incremental mode] 
+AI: [Checks existing plan: found 8 features, user module exists]
+AI: [Qualifies for fast path: 1 feature, low complexity, ≤2 deps]
+AI: "Fast path available. Drafting F-009..."
+AI: [Validates immediately]
+AI: "Ready to proceed to dev-pipeline."
 ```
 
-**Step 4c: Priority Assignment**
-
-Assign priority numbers (1 = highest) based on dependency order and user input. Features with no dependents and early in the chain get higher priority.
+## Output Rules
 
-Ask the user: "Does this execution order look correct? Any features you want prioritized differently?"
+`feature-list.json` must satisfy:
+- `$schema` = `dev-pipeline-feature-list-v1`
+- non-empty `features`
+- sequential feature IDs (`F-001`, `F-002`, ...)
+- valid dependency DAG
+- new items default `status: "pending"`
+- English feature titles for stable slug generation
 
----
+## Next-Step Execution Policy (after planning)
 
-### Phase 5: Granularity Decision
+Recommend these three options in this strict order:
 
-**Goal**: Determine whether complex features need sub-feature decomposition.
-
-Apply these rules to each feature:
-
-| Condition | Action |
-|-----------|--------|
-| More than 8 acceptance criteria | Consider splitting into sub_features |
-| Touches more than 3 distinct modules (e.g., API + DB + UI + auth) | Consider splitting into sub_features |
-| Estimated complexity is "high" | Recommend sub_features with `session_granularity: "auto"` |
-| Infrastructure or setup feature | Always use `session_granularity: "feature"` |
-| Simple CRUD or utility feature | Use `session_granularity: "feature"` |
-
-When splitting, create sub_features with IDs like `F-004-A`, `F-004-B`, etc. Each sub_feature needs:
-- `id`: F-NNN-X pattern (X is uppercase letter)
-- `title`: concise title
-- `description`: what this sub-feature covers
-
-Present the granularity decisions to the user and get confirmation.
-
----
-
-### Phase 6: Generate Output
-
-**Goal**: Produce the validated `feature-list.json` file.
-
-**Step 6a: Construct the JSON**
-
-Build the complete JSON object following this exact schema:
-
-```json
-{
-  "$schema": "dev-pipeline-feature-list-v1",
-  "app_name": "<from Phase 1>",
-  "app_description": "<1-2 sentence summary from Phase 1>",
-  "created_at": "<current ISO 8601 datetime>",
-  "created_by": "app-planner",
-  "source_spec": "<path to spec file if one was used, otherwise omit>",
-  "features": [
-    {
-      "id": "F-001",
-      "title": "<feature title>",
-      "description": "<detailed description>",
-      "priority": 1,
-      "estimated_complexity": "low | medium | high",
-      "dependencies": [],
-      "acceptance_criteria": [
-        "<criterion 1>",
-        "<criterion 2>",
-        "<criterion 3>"
-      ],
-      "status": "pending",
-      "session_granularity": "feature | sub_feature | auto",
-      "sub_features": []
-    }
-  ],
-  "global_context": {
-    "tech_stack": "<from Phase 2, e.g. Next.js 14 + Express.js + PostgreSQL + Prisma>",
-    "design_system": "<from Phase 2, e.g. shadcn/ui + Tailwind CSS>",
-    "testing_strategy": "<from Phase 2, e.g. Jest (unit) + Playwright (e2e)>",
-    "language": "<from Phase 2, e.g. TypeScript>"
-  }
-}
-```
-
-**Step 6b: Write and Validate**
-
-1. Write the JSON to the project root `feature-list.json` (this is the default path that `dev-pipeline/run.sh` reads from). If a `feature-list.json` already exists, append new features to the existing `features` array (continuing from the last F-NNN ID) and update `global_context` if needed — do NOT overwrite the existing features.
-2. Ask the user if they want a different output path before writing.
-3. Run the validation script:
-
-```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py --input <path-to-written-file> --output <final-output-path>
-```
-
-4. If validation fails, report the errors and fix them.
-5. If validation succeeds, proceed to the summary.
-
-**Step 6c: Summary Table**
-
-Present a summary table of the plan:
-
-```
-+-------+-----------------------------------+----------+--------+--------------+
-| ID    | Title                             | Priority | Cmplx  | Dependencies |
-+-------+-----------------------------------+----------+--------+--------------+
-| F-001 | Project Infrastructure Setup      | 1        | medium | (none)       |
-| F-002 | User Authentication               | 2        | medium | F-001        |
-| F-003 | Task CRUD Operations              | 3        | medium | F-002        |
-| ...   | ...                               | ...      | ...    | ...          |
-+-------+-----------------------------------+----------+--------+--------------+
-Total features: N | Estimated sessions: M
-```
-
-Where "Estimated sessions" counts features plus sub_features (each sub_feature is one session when granularity is "auto").
-
----
-
-### Phase 7: Integration with dev-pipeline
-
-**Goal**: Tell the user how to proceed.
-
-After the feature-list.json is generated and validated, present these next steps:
-
-1. **Review the file**: "The feature list has been saved to `feature-list.json`. Please review it before running the pipeline."
-
-2. **Run the pipeline**:
+1. **Preferred**: invoke `dev-pipeline-launcher` skill (natural-language handoff)
+2. **Fallback A**: run daemon wrapper
    ```bash
-   ./dev-pipeline/run.sh run
+   ./dev-pipeline/launch-daemon.sh start feature-list.json
+   ./dev-pipeline/launch-daemon.sh status
    ```
-
-3. **Monitor progress**:
+3. **Fallback B**: run direct foreground script
    ```bash
+   ./dev-pipeline/run.sh run
    ./dev-pipeline/run.sh status
    ```
 
-4. **Adjust if needed**: "You can edit the feature-list.json manually at any time. The pipeline will pick up changes on the next iteration."
+When launcher is available, do not prioritize raw scripts.
 
-If the dev-pipeline directory does not exist in the project, inform the user that they need to set it up first and point them to the dev-pipeline documentation.
+## Error Recovery
 
-## Output Format Specification
+Structured error handling for interrupted sessions and validation failures.
 
-The `feature-list.json` file is the input contract for `dev-pipeline/run.sh`. It MUST conform to the `dev-pipeline-feature-list-v1` schema. The file is read by:
+### Validation Failures
 
-1. **`run.sh`** — iterates features by dependency order, passes each to `generate-bootstrap-prompt.py`
-2. **`generate-bootstrap-prompt.py`** — extracts feature fields and injects them into the bootstrap prompt template as `{{PLACEHOLDER}}` variables
-3. **`update-feature-status.py`** — reads/writes `status` field to track pipeline progress
-4. **`init-pipeline.py`** — validates the file and initializes pipeline state
+When `python3 scripts/validate-and-generate.py validate --input <file> --mode <mode>` returns errors:
 
-### File Location
+#### Parse validation output
+Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]`
 
-The file MUST be at **project root `feature-list.json`**. This is the default path that `run.sh` reads:
+#### Decision Tree
 
-```bash
-# run.sh defaults:
-main() {
-    local feature_list="${1:-feature-list.json}"
-    ...
-}
-```
+**if `error_count == 0` (warnings only):**
+- Proceed with user approval
+- Show warnings and ask: "Continue? (Y/n)"
 
-Usage:
-```bash
-./dev-pipeline/run.sh run                    # reads ./feature-list.json
-./dev-pipeline/run.sh run feature-list.json  # same (explicit)
-./dev-pipeline/run.sh status                 # reads ./feature-list.json
-```
+**elif `error_count > 0` (critical errors):**
+
+Group errors by type and apply targeted fixes:
 
-### Top-Level Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `$schema` | string | Yes | Must be `"dev-pipeline-feature-list-v1"` |
-| `app_name` | string | Yes | Application name (min 1 char) |
-| `app_description` | string | No | Brief description of the application |
-| `created_at` | string | No | ISO 8601 datetime of creation |
-| `created_by` | string | No | Should be `"app-planner"` |
-| `source_spec` | string | No | Path to source specification file |
-| `features` | array | Yes | Array of feature objects (min 1) |
-| `global_context` | object | No | Shared context for all features |
-
-### Feature Object Fields
-
-Each feature object maps to one `cbc` session (or multiple sessions if `session_granularity` is `"auto"` with sub_features). The pipeline extracts these fields into the bootstrap prompt template:
-
-| Field | Type | Required | Pipeline Usage (template placeholder) | Description |
-|-------|------|----------|--------------------------------------|-------------|
-| `id` | string | Yes | `{{FEATURE_ID}}` | Pattern: `F-NNN` (e.g., F-001, F-012). Used as directory key in `state/features/F-NNN/` |
-| `title` | string | Yes | `{{FEATURE_TITLE}}` | Concise English feature title. Also used to compute `{{FEATURE_SLUG}}` (e.g., "Shared UI Package Extraction" → `011-shared-ui-package-extraction`). The slug determines the `.prizmkit/specs/{slug}/` directory |
-| `description` | string | Yes | `{{FEATURE_DESCRIPTION}}` | Detailed implementation description in English. Injected verbatim into the bootstrap prompt. Must contain enough context for a dev team to implement without additional clarification. Include: component names, API endpoints, data models, file paths, behavior specs |
-| `priority` | integer | Yes | — | Execution priority (1 = highest). Pipeline processes features by dependency order, not strictly by priority, but priority is used as tiebreaker |
-| `estimated_complexity` | string | No | `{{COMPLEXITY}}`, `{{PIPELINE_MODE}}` | `"low"` → lite mode, `"medium"` → standard mode, `"high"` → full mode. Determines how many pipeline phases are executed (lite skips spec.md + analyze, standard runs all, full adds clarify) |
-| `dependencies` | array | Yes | `{{COMPLETED_DEPENDENCIES}}` | Array of F-NNN IDs this feature depends on. Pipeline will not start this feature until all dependencies have `status: "completed"`. Injected into prompt as a list of completed dependency names |
-| `acceptance_criteria` | array | Yes | `{{ACCEPTANCE_CRITERIA}}` | Array of testable criteria (min 3, recommend 5+ for medium/high). Injected as markdown bullet list into the bootstrap prompt. Each criterion should be independently verifiable |
-| `status` | string | Yes | — | Pipeline-managed: `"pending"` → `"in_progress"` → `"completed"` / `"failed"`. New features MUST be `"pending"`. Do not manually set to other values |
-| `session_granularity` | string | No | — | `"feature"` (default): one session for the whole feature. `"auto"`: pipeline may split into sub_feature sessions. `"sub_feature"`: always run sub_features as separate sessions |
-| `sub_features` | array | No | — | Array of sub-feature objects. Only used when `session_granularity` is `"auto"` or `"sub_feature"` |
-
-### Sub-Feature Object Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Pattern: `F-NNN-X` (e.g., F-004-A, F-011-B). X is uppercase letter |
-| `title` | string | Yes | Sub-feature title |
-| `description` | string | Yes | What this sub-feature covers |
-
-### Global Context Fields
-
-Injected as `{{GLOBAL_CONTEXT}}` into every bootstrap prompt (formatted as markdown key-value list):
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `tech_stack` | string | Frameworks, runtimes, and databases |
-| `design_system` | string | UI framework and CSS approach |
-| `testing_strategy` | string | Testing tools and approach |
-| `language` | string | Programming language(s) |
-| Any additional keys | string | Deployment strategy, encryption, communication patterns, etc. |
-
-### How Fields Flow Through the Pipeline
+| Error Type | Symptom | Fix Offered | Auto-Fix? |
+|-----------|---------|------------|-----------|
+| **Schema mismatch** | `$schema` invalid, missing `app_name`, wrong `features` type | "Set `$schema` to `dev-pipeline-feature-list-v1`, `app_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], status not pending | "Show field, valid values" | Yes |
+
+#### Execution
 
 ```
-feature-list.json
-    │
-    ├─ generate-bootstrap-prompt.py
-    │   ├─ id          → {{FEATURE_ID}}
-    │   ├─ title       → {{FEATURE_TITLE}}, {{FEATURE_SLUG}} (computed: NNN-kebab-case-title)
-    │   ├─ description → {{FEATURE_DESCRIPTION}}
-    │   ├─ acceptance_criteria → {{ACCEPTANCE_CRITERIA}} (markdown bullet list)
-    │   ├─ dependencies → {{COMPLETED_DEPENDENCIES}} (resolved to names + status)
-    │   ├─ estimated_complexity → {{COMPLEXITY}}, {{PIPELINE_MODE}} (low→lite, medium→standard, high→full)
-    │   └─ global_context → {{GLOBAL_CONTEXT}} (all key-value pairs)
-    │
-    ├─ bootstrap-prompt.md (rendered template)
-    │   └─ Fed to: cbc --print -y < bootstrap-prompt.md
-    │       └─ prizm-dev-team session
-    │           ├─ PM: generates .prizmkit/specs/{{FEATURE_SLUG}}/spec.md, plan.md, tasks.md
-    │           ├─ Dev: implements code based on plan + tasks
-    │           ├─ Reviewer: validates against acceptance_criteria
-    │           └─ Coordinator: commits with feat({{FEATURE_ID}}): {{FEATURE_TITLE}}
-    │
-    └─ update-feature-status.py
-        └─ status: "pending" → "in_progress" → "completed" / "failed"
+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"
 ```
 
-### Feature Slug Convention
+### Interrupted Planning Resume
 
-The pipeline computes a **feature slug** from `id` + `title` for the `.prizmkit/specs/` directory:
+| Scenario | Detection | Action |
+|----------|-----------|--------|
+| Partial `feature-list.json` exists | File found in working dir | Read file, show summary, ask: "Resume from checkpoint or restart?" |
+| Checkpoint CP-AP-4 passed | File generates valid schema | Offer: "Jump to Phase 7 (final validation)" |
+| Checkpoint CP-AP-5 passed | Full validation passes | Offer: "Feature plan complete, proceed to dev-pipeline" |
+| User restarts mid-session | User says "restart" | Return to Phase 1 Vision, or load previous checkpoint if requested |
+| Max validation retries exceeded | 3 failed validation loops | Offer: (a) manual review, (b) restart from Phase 1 |
 
-```
-F-003 + "Task CRUD Operations" → "003-task-crud-operations"
-```
+### Incremental Mode Abort
 
-Rules:
-- Extract numeric part from id (F-011 → 011), zero-pad to 3 digits
-- Convert title to lowercase kebab-case (remove non-alphanumeric, spaces → hyphens)
-- Concatenate: `{NNN}-{kebab-title}`
+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 App Planning)
+- If existing file uploaded → continue Route B
 
-This slug is used as:
-- `.prizmkit/specs/{slug}/spec.md`
-- `.prizmkit/specs/{slug}/plan.md`
-- `.prizmkit/specs/{slug}/tasks.md`
-- Git commit: `feat(F-003): Task CRUD Operations`
+## Incremental Feature Planning — Style Matching
 
-### Complexity → Pipeline Mode Mapping
+When appending features to an existing plan, preserve style and detail level automatically.
 
-The `estimated_complexity` field determines which pipeline phases are executed:
+### Style Detection (Automatic)
 
-| Complexity | Mode | Phases Run | When to Use |
-|-----------|------|------------|-------------|
-| `"low"` | lite | plan + tasks → implement → review → commit (skip spec, skip analyze) | Simple setup, config, or utility features |
-| `"medium"` | standard | spec + plan + tasks → analyze → implement → review → commit | Standard features with clear scope |
-| `"high"` | full | spec + clarify + plan + tasks → analyze → implement → review (3 fix rounds) → commit | Complex features touching multiple modules, requiring sub_features |
+Before drafting new features, analyze existing plan:
 
-## Quality Guidelines
+1. **Language Detection**
+   - Scan `title` and `description` fields
+   - If >70% English titles → default to English
+   - If >70% Chinese titles → suggest Chinese (or allow bilingual)
 
-These rules MUST be enforced when generating the feature list:
+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
 
-1. **Minimum acceptance criteria**: Every feature MUST have at least 3 acceptance criteria. Aim for 5 on medium/high complexity features.
-2. **Valid DAG**: Dependencies MUST NOT contain cycles. Run a topological sort check before finalizing.
-3. **Root feature**: F-001 MUST have an empty dependencies array. It is always the infrastructure/setup feature.
-4. **Implementable scope**: Each feature should be implementable in a single prizm-dev-team session. If it cannot be, split it into sub_features.
-5. **Self-contained descriptions**: Feature descriptions MUST contain enough detail for a development team to implement the feature without asking clarifying questions. Include data models, API endpoints, and UI behavior where relevant. The description is injected verbatim into the bootstrap prompt — the dev agent reads only this text to understand what to build.
-6. **No status assumptions**: All new features MUST have `"status": "pending"`. The dev-pipeline manages status transitions (`pending` → `in_progress` → `completed`/`failed`). Do NOT manually set status to `"completed"` or `"in_progress"` for new features.
-7. **Consistent IDs**: Feature IDs MUST be sequential (F-001, F-002, ...). Sub-feature IDs MUST use the parent ID prefix (F-004-A, F-004-B). When appending to an existing feature list, continue from the next available ID (e.g., if F-010 exists, start new features from F-011).
-8. **Dependency completeness**: Every ID referenced in a `dependencies` array MUST exist as a feature `id` in the same file.
-9. **Style consistency**: When appending to an existing feature list, match the language (English/Chinese), description detail level, and acceptance criteria format of the existing features.
-10. **English titles**: Feature `title` MUST be in English because the pipeline uses it to compute the feature slug for directory naming (`.prizmkit/specs/{slug}/`). Non-ASCII characters in the title will produce invalid directory names.
-11. **Description language**: Feature `description` should use the same language as existing features in the file. When appending to an existing list, match the language and detail level of prior features.
+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
 
-## Validation Script Usage
+4. **Complexity Distribution**
+   - Count low/medium/high distribution in existing features
+   - Alert if new features deviate significantly (>20 percentile points)
+   - Suggest rebalancing if needed
 
-After constructing the feature-list.json, validate it:
+### Style Consistency Prompt
 
-```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json
-```
+If new features deviate significantly from detected style:
 
-The script performs:
-- JSON schema validation against `dev-pipeline-feature-list-v1`
-- Dependency cycle detection
-- ID format and uniqueness checks
-- Acceptance criteria minimum count enforcement
-- Dependency reference integrity checks
-
-On success, exits with code 0 and prints stats (total features, complexity distribution, max dependency depth).
-On failure, prints error details and exits with code 1.
-
-Note: Warnings about existing features having `status: "completed"` are expected when appending to an existing feature list — they apply only to new plans where all features should be `"pending"`.
-
-## Example: Well-Formed Feature
-
-```json
-{
-  "id": "F-003",
-  "title": "Task CRUD Operations",
-  "description": "Core task management: create, read, update, delete tasks. Tasks have title, description, status (todo/in-progress/done), priority, due date, and assignee. The API should expose RESTful endpoints under /api/tasks. The UI should include a task list view with filtering by status and a task detail modal for editing.\n\nData model: Task { id: uuid, title: string, description: text, status: enum(todo/in-progress/done), priority: enum(low/medium/high), dueDate: datetime, assigneeId: uuid FK→User, createdAt: datetime, updatedAt: datetime }.\n\nAPI endpoints: GET /api/tasks (list with pagination, filtering). POST /api/tasks (create). GET /api/tasks/:id (read). PATCH /api/tasks/:id (partial update). DELETE /api/tasks/:id (soft delete).\n\nUI: Task list page with status filter tabs, sortable columns, and a slide-out detail panel for editing.",
-  "priority": 3,
-  "estimated_complexity": "high",
-  "dependencies": ["F-002"],
-  "acceptance_criteria": [
-    "Create task with title, description, status, priority, due date, and assignee fields",
-    "List tasks with server-side pagination (default 20 per page)",
-    "Filter tasks by status, priority, and assignee via query parameters",
-    "Update task fields individually via PATCH /api/tasks/:id",
-    "Delete task with confirmation dialog and soft-delete in database",
-    "Task validation enforced on both client form and server API",
-    "API returns 404 for non-existent task IDs",
-    "API returns 401 for unauthenticated requests"
-  ],
-  "status": "pending",
-  "session_granularity": "auto",
-  "sub_features": [
-    {
-      "id": "F-003-A",
-      "title": "Task API & Data Model",
-      "description": "Create Task database model with migrations. Implement all RESTful API endpoints with validation, pagination, filtering, and error handling."
-    },
-    {
-      "id": "F-003-B",
-      "title": "Task UI Components",
-      "description": "Build task list page with filter tabs, sortable table, and slide-out detail panel. Connect to API with loading states and optimistic updates."
-    }
-  ]
-}
+```
+"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)"
 ```
 
-## Integration with dev-pipeline
+Accept user choice, then adjust draft accordingly before Phase 6 (JSON generation).
 
-### Running the Pipeline
+## Resume Support
 
-After the feature-list.json is generated and validated:
+App-planner sessions can be resumed from the last completed checkpoint without losing context.
 
-```bash
-# Initialize pipeline state (first time only)
-python3 dev-pipeline/scripts/init-pipeline.py \
-  --feature-list feature-list.json \
-  --state-dir dev-pipeline/state
+### Detection Logic
 
-# Run all pending features
-./dev-pipeline/run.sh run
+Check for artifact files in working directory:
 
-# Run a single feature
-./dev-pipeline/run.sh run F-003
+| Artifacts Found | Last Completed Checkpoint | Next Phase | Resume Action |
+|-----------------|--------------------------|-----------|----------------|
+| None | (new session) | Phase 1: Vision | Start fresh planning |
+| `feature-list.json` exists | CP-AP-4 (file generated) | Phase 7: Final validation | Offer to validate or extend |
+| `feature-list.json` + validation passed | CP-AP-5 (validation pass) | Handoff: dev-pipeline | Offer: execute pipeline now |
+| Partial state (incomplete file) | CP-AP-2 or CP-AP-3 | Next phase after last checkpoint | Resume interactive planning |
 
-# Dry-run: inspect generated prompt without executing
-./dev-pipeline/run.sh run F-003 --dry-run
+### Resume Command (Project Structure)
 
-# Check status
-./dev-pipeline/run.sh status
+For projects using `.prizmkit/` structure:
 
-# Reset a failed feature for retry
-./dev-pipeline/reset-feature.sh F-003 --clean --run
+```bash
+# Explicit resume (if file is not in current directory):
+app-planner --resume-from <path-to-existing-feature-list.json>
 ```
 
-### Pipeline State Directory
-
-Runtime state is stored in `dev-pipeline/state/` (gitignored):
-
+AI detects existing file → suggests:
 ```
-dev-pipeline/state/
-├── pipeline.json             # Pipeline run metadata
-├── current-session.json      # Currently executing session
-└── features/
-    └── F-003/
-        ├── status.json       # Feature status, retry count
-        └── sessions/
-            └── F-003-20260305120000/
-                ├── bootstrap-prompt.md  # Generated prompt
-                └── logs/
-                    └── session.log      # Full cbc session output
+"Existing plan found with N features, M newly added. 
+Resume incremental planning? (Y/n)"
 ```
 
-### PrizmKit Artifacts (per feature)
+### Artifact Path Convention
 
-Each feature session generates artifacts in `.prizmkit/specs/{feature-slug}/`:
+Recommended structure for feature planning artifacts:
 
 ```
-.prizmkit/specs/003-task-crud-operations/
-├── spec.md      # Feature specification (Phase 1)
-├── plan.md      # Implementation plan (Phase 2)
-├── tasks.md     # Task breakdown with [ ] checkboxes (Phase 3)
-├── checklists/  # Quality checklists (optional)
-└── contracts/   # API contracts (optional)
+.prizmkit/planning/
+  ├── feature-list.json              # Primary output (always here)
+  ├── feature-list.validated.json    # Checkpoint backup after CP-AP-5
+  └── <ISO-timestamp>.backup.json    # Optional incremental backups
 ```
 
-## Error Recovery
+Mention this path when summarizing (Phase 8 handoff) to help users organize future sessions.
+
+Maintainer note: evaluation workflow moved to `assets/evaluation-guide.md`.
 
-If the planning conversation is interrupted or the user wants to restart:
+## Handoff Message Template
 
-1. **Resume**: If a partial `feature-list.json` exists at the output path, offer to load it and continue from where the user left off.
-2. **Restart**: If the user explicitly says "start over" or "re-plan", discard any existing draft and begin from Phase 1.
-3. **Amend**: If the user wants to modify a completed plan, load the existing file, present the current features, and allow targeted edits without re-doing the entire workflow.
+After successful validation, report:
+1. output file path
+2. total features + newly added features
+3. dependency and priority highlights
+4. recommended next action: `dev-pipeline-launcher`