prizmkit 1.1.7 → 1.1.9

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

@@ -6,7 +6,7 @@ For app-level design references (vision templates, tech stack matrix), see `app-
 
 ---
 
-## 4. Feature Description Writing Guide
+## 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.
 
@@ -52,9 +52,25 @@ Every description should cover these aspects (adapt per feature type):
 "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.
+
 ---
 
-## 5. Acceptance Criteria Writing Guide
+## Acceptance Criteria Writing Guide
 
 Acceptance criteria define what "done" means for a feature. They should be specific, testable, and unambiguous.
 
@@ -95,7 +111,7 @@ Then [expected outcome]
 
 ---
 
-## 6. Complexity Estimation Guide
+## Complexity Estimation Guide
 
 | Complexity | Characteristics | Typical Scope |
 |------------|----------------|---------------|
@@ -122,7 +138,7 @@ Consider splitting a feature if it exhibits any of the following:
 
 ---
 
-## 7. Dependency Graph Rules
+## Dependency Graph Rules
 
 These rules ensure the feature dependency graph is valid and buildable.
 
@@ -150,7 +166,7 @@ These rules ensure the feature dependency graph is valid and buildable.
 
 ---
 
-## 8. Session Granularity Decision Rules
+## Session Granularity Decision Rules
 
 Session granularity determines whether a feature is implemented in a single coding session or split across multiple sub-feature sessions.
 

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

@@ -4,11 +4,9 @@ For web apps with UI, features that involve user-facing pages or interactive flo
 
 ## How to Capture
 
-During Phase 4 (refine descriptions and acceptance criteria), for qualifying features ask:
+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.
 
-> "This feature has UI behavior. Want to add browser verification so the pipeline can auto-check it after implementation? (Y/n)"
-
-If yes, generate the `browser_interaction` object:
+For each qualifying feature, generate the `browser_interaction` object:
 
 ```json
 {

package/bundled/skills/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 word count for its complexity level (30/50/80 words for low/medium/high).
+
+**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/feature-planner/references/error-recovery.md

@@ -51,59 +51,40 @@ if all_retries_exceeded:
 
 ## Resume Support
 
-feature-planner sessions can be resumed from the last completed checkpoint without losing context.
+feature-planner sessions can be resumed from the last completed checkpoint when artifacts are found.
 
 ### Detection Logic
 
-Check for artifact files in working directory:
+Check for artifact files in `.prizmkit/plans/`:
 
-| Artifacts Found | Last Completed Checkpoint | Next Phase | Resume Action |
-|-----------------|--------------------------|-----------|----------------|
-| None | (new session) | Phase 1: Scope | Start fresh planning |
-| `feature-list.json` exists | CP-FP-4 (file generated) | Phase 9: Final validation | Offer to validate or extend |
-| `feature-list.json` + validation passed | CP-FP-5 (validation pass) | Handoff: dev-pipeline | Offer: execute pipeline now |
-| Partial state (incomplete file) | CP-FP-1 or CP-FP-2 | Next phase after last checkpoint | Resume interactive planning |
-| 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 |
+| 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 |
 
-### Resume Command (Project Structure)
-
-For projects using `.prizmkit/` structure:
-
-```bash
-# Explicit resume (if file is not in current directory):
-feature-planner --resume-from <path-to-existing-feature-list.json>
-```
-
-AI detects existing file → suggests:
-```
-"Existing plan found with N features, M newly added.
-Resume incremental planning? (Y/n)"
-```
+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)
-- If existing file uploaded → continue Route B
 
 ### Artifact Path Convention
 
-**CRITICAL PATH RULE**: `feature-list.json` MUST be written to the project root directory
-(same level as `package.json` / `.git`).
-
-Before writing, verify: `ls package.json .git 2>/dev/null` — if these exist in the current
-directory, you are at the project root. NEVER write to `dev-pipeline/` or any subdirectory.
+**CRITICAL PATH RULE**: `feature-list.json` MUST be written to `.prizmkit/plans/` directory.
 
-After writing, verify: `ls -la feature-list.json` from project root.
+Before writing, verify the directory exists: `mkdir -p .prizmkit/plans`
 
 ```
 <project-root>/
-  ├── feature-list.json              # Primary output (always here, at project root)
-  └── .prizmkit/planning/            # Optional organization for backups
-      ├── feature-list.validated.json    # Checkpoint backup after CP-FP-5
+  └── .prizmkit/plans/
+      ├── feature-list.json              # Primary output
+      ├── feature-list.draft.json        # Draft backup (Session Exit Gate)
       └── <ISO-timestamp>.backup.json    # Optional incremental backups
 ```
 
-The pipeline reads `feature-list.json` from the project root by default. If the user specifies a custom path, the launcher accepts it as an argument.
+> **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/feature-planner/references/incremental-feature-planning.md

@@ -109,4 +109,4 @@ Use concise prompts during interaction:
 - [ ] Existing style preserved
 - [ ] Dependency graph still DAG
 - [ ] Validation passes
-- [ ] Next step recommendation follows priority: launcher → daemon → run-feature.sh
+- [ ] Next step recommendation: `feature-pipeline-launcher`

package/bundled/skills/feature-planner/references/new-project-planning.md

@@ -31,7 +31,7 @@ For each feature define:
 - `id`
 - `title`
 - `description`
-- `priority` — string: `"high"`, `"medium"`, or `"low"` (never numeric)
+- `priority` — string: `"critical"`, `"high"`, `"medium"`, or `"low"` (never numeric)
 - `estimated_complexity`
 - `dependencies`
 - `acceptance_criteria`
@@ -82,4 +82,4 @@ Split into `sub_features` when:
 - [ ] IDs are sequential
 - [ ] `status` initialized to `pending`
 - [ ] Validation passes
-- [ ] Next step recommendation follows priority: launcher → daemon → run-feature.sh
+- [ ] Next step recommendation: `feature-pipeline-launcher`

package/bundled/skills/feature-planner/scripts/validate-and-generate.py

@@ -4,15 +4,15 @@ validate-and-generate.py - Validate and generate feature-list.json files
 for the dev-pipeline system.
 
 Commands:
-  validate    Validate an existing feature-list.json
-  template    Generate a blank template feature-list.json
-  summary     Print a summary table of features from a feature-list.json
+  validate    Validate an existing .prizmkit/plans/feature-list.json
+  template    Generate a blank template .prizmkit/plans/feature-list.json
+  summary     Print a summary table of features from a .prizmkit/plans/feature-list.json
   grade       Generate grading results from eval runs (for npm run skill:review)
 
 Usage:
-  python3 validate-and-generate.py validate --input feature-list.json [--output validated.json] [--mode new|incremental]
-  python3 validate-and-generate.py template --output feature-list.json
-  python3 validate-and-generate.py summary --input feature-list.json [--format markdown|json]
+  python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json] [--mode new|incremental]
+  python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
+  python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
   python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
 
 Python 3.6+ required. No external dependencies.
@@ -34,7 +34,7 @@ SCHEMA_VERSION = "dev-pipeline-feature-list-v1"
 
 VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "split", "auto_skipped"}
 VALID_COMPLEXITIES = {"low", "medium", "high"}
-VALID_PRIORITIES = {"high", "medium", "low"}
+VALID_PRIORITIES = {"critical", "high", "medium", "low"}
 VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
 VALID_PLANNING_MODES = {"new", "incremental"}
 
@@ -446,7 +446,6 @@ def generate_template():
         "project_description": "YOUR_PROJECT_DESCRIPTION",
         "created_at": now,
         "created_by": "feature-planner",
-        "source_spec": "",
         "features": [
             {
                 "id": "F-001",
@@ -847,16 +846,16 @@ def cmd_grade(args):
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Validate and generate feature-list.json files for the dev-pipeline system.",
+        description="Validate and generate .prizmkit/plans/feature-list.json files for the dev-pipeline system.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
             "Examples:\n"
-            "  %(prog)s validate --input feature-list.json\n"
-            "  %(prog)s validate --input feature-list.json --mode incremental\n"
-            "  %(prog)s validate --input feature-list.json --output validated.json\n"
-            "  %(prog)s template --output feature-list.json\n"
-            "  %(prog)s summary --input feature-list.json\n"
-            "  %(prog)s summary --input feature-list.json --format json\n"
+            "  %(prog)s validate --input .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s validate --input .prizmkit/plans/feature-list.json --mode incremental\n"
+            "  %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
+            "  %(prog)s template --output .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
         ),
     )
 
@@ -865,10 +864,10 @@ def main():
     # -- validate --
     p_validate = subparsers.add_parser(
         "validate",
-        help="Validate an existing feature-list.json",
+        help="Validate an existing .prizmkit/plans/feature-list.json",
     )
     p_validate.add_argument(
-        "--input", required=True, help="Path to input feature-list.json"
+        "--input", required=True, help="Path to input .prizmkit/plans/feature-list.json"
     )
     p_validate.add_argument(
         "--output", help="Path to write validated output (optional)"
@@ -883,7 +882,7 @@ def main():
     # -- template --
     p_template = subparsers.add_parser(
         "template",
-        help="Generate a blank template feature-list.json",
+        help="Generate a blank template .prizmkit/plans/feature-list.json",
     )
     p_template.add_argument(
         "--output", required=True, help="Path to write template file"
@@ -892,10 +891,10 @@ def main():
     # -- summary --
     p_summary = subparsers.add_parser(
         "summary",
-        help="Print a summary table of features from a feature-list.json",
+        help="Print a summary table of features from a .prizmkit/plans/feature-list.json",
     )
     p_summary.add_argument(
-        "--input", required=True, help="Path to input feature-list.json"
+        "--input", required=True, help="Path to input .prizmkit/plans/feature-list.json"
     )
     p_summary.add_argument(
         "--format",

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

@@ -1,7 +1,6 @@
 ---
 name: "feature-workflow"
-tier: companion
-description: "One-stop entry point for feature development. Brainstorms requirements with the user until fully clarified, then orchestrates feature-planner → feature-pipeline-launcher → execution. Handles multi-feature batch development from a single request. Use this skill whenever the user wants to build an app, develop multiple features at once, or go from idea to running code in one step. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete', 'batch implement'. (project)"
+description: "One-stop entry point for feature development. Brainstorms requirements with the user until fully clarified, then orchestrates feature-planner → feature-pipeline-launcher → execution. Handles multi-feature batch development from a single request. Use this skill whenever the user wants to build an app, develop multiple features at once, or go from idea to running code in one step. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete', 'batch implement'."
 ---
 
 # Feature Workflow
@@ -19,7 +18,7 @@ User says:
 
 **Do NOT use this skill when:**
 - User only wants to plan features (use `feature-planner` directly)
-- User only wants to launch pipeline for existing feature-list.json (use `feature-pipeline-launcher`)
+- User only wants to launch pipeline for existing .prizmkit/plans/feature-list.json (use `feature-pipeline-launcher`)
 - User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
 - User wants to refactor code (use `refactor-workflow`)
 
@@ -32,7 +31,7 @@ feature-workflow <idea / requirements>
    │
    ├── Phase 1: Brainstorm → deep interactive Q&A until requirements are crystal clear
    │
-   ├── Phase 2: Plan → feature-planner → feature-list.json
+   ├── Phase 2: Plan → feature-planner → .prizmkit/plans/feature-list.json
    │
    ├── Phase 3: Launch → feature-pipeline-launcher → pipeline execution
    │
@@ -44,7 +43,7 @@ feature-workflow <idea / requirements>
 | Phase | Action | Result |
 |-------|--------|--------|
 | 1 | **Brainstorm** — interactive Q&A with user | Fully clarified requirements document |
-| 2 | Call `feature-planner` with clarified requirements | `feature-list.json` with N features |
+| 2 | Call `feature-planner` with clarified requirements | `.prizmkit/plans/feature-list.json` with N features |
 | 3 | Call `feature-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
 | 4 | Monitor progress | Status updates, completion report |
 
@@ -52,7 +51,7 @@ feature-workflow <idea / requirements>
 
 Without this skill, users must:
 1. Figure out all requirements themselves
-2. Invoke `feature-planner` → wait for feature-list.json
+2. Invoke `feature-planner` → wait for .prizmkit/plans/feature-list.json
 3. Invoke `feature-pipeline-launcher` → wait for pipeline start
 4. Manually check progress
 
@@ -81,9 +80,9 @@ Natural language description of the project or features. Can be:
 
 Flow: brainstorm → feature-planner → feature-pipeline-launcher → monitor
 
-**Mode B: From existing feature-list.json**
+**Mode B: From existing .prizmkit/plans/feature-list.json**
 
-When user says "run pipeline from existing file" or feature-list.json already exists:
+When user says "run pipeline from existing file" or .prizmkit/plans/feature-list.json already exists:
 - Skip brainstorm and `feature-planner` (file already exists)
 - Invoke `feature-pipeline-launcher` directly
 - Monitor and report progress
@@ -92,7 +91,7 @@ When user says "run pipeline from existing file" or feature-list.json already ex
 
 When user says "add features to existing project" or the project already has features:
 - Brainstorm new feature requirements with the user
-- Invoke `feature-planner` in incremental mode (reads existing feature-list.json)
+- Invoke `feature-planner` in incremental mode (reads existing .prizmkit/plans/feature-list.json)
 - Append new features to existing list
 - Invoke `feature-pipeline-launcher`
 - Monitor and report progress
@@ -232,7 +231,7 @@ Present this summary to the user and get explicit confirmation before proceeding
 
 ## Phase 2: Plan
 
-**Goal**: Generate structured feature-list.json from the clarified requirements.
+**Goal**: Generate structured .prizmkit/plans/feature-list.json from the clarified requirements.
 
 **STEPS**:
 
@@ -240,18 +239,18 @@ Present this summary to the user and get explicit confirmation before proceeding
    - Pass the structured requirements summary as input — NOT the raw user conversation
    - For new projects: standard planning mode
    - For existing projects with `--incremental`: incremental planning mode
-   - **Input**: Markdown requirements summary (feature descriptions, user stories, constraints)
-   - **Output**: `feature-list.json` (schema: `dev-pipeline-feature-list-v1`) containing `project_name`, `features[]` with id (F-NNN), title, description, priority, dependencies, acceptance_criteria, status
+   - **Input**: Markdown requirements summary (feature descriptions, goals, constraints)
+   - **Output**: `.prizmkit/plans/feature-list.json` (schema: `dev-pipeline-feature-list-v1`) containing `project_name`, `features[]` with id (F-NNN), title, description, priority, dependencies, acceptance_criteria, status
 
 2. **Interactive planning** (if feature-planner requires clarification):
    - Because Phase 1 was thorough, feature-planner should need minimal clarification
    - If questions arise, answer from the Phase 1 context or pass through to user
 
 3. **Validate output**:
-   - Confirm `feature-list.json` exists
+   - Confirm `.prizmkit/plans/feature-list.json` exists
    - Show summary: total features, complexity distribution, dependencies
 
-**CHECKPOINT CP-FW-1**: `feature-list.json` generated and validated.
+**CHECKPOINT CP-FW-1**: `.prizmkit/plans/feature-list.json` generated and validated.
 
 **If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
 
@@ -274,7 +273,7 @@ Present this summary to the user and get explicit confirmation before proceeding
    ```
 
 2. **Invoke `feature-pipeline-launcher` skill**:
-   - **Input**: Path to validated `feature-list.json`
+   - **Input**: Path to validated `.prizmkit/plans/feature-list.json`
    - The launcher handles all prerequisites checks
    - The launcher presents execution mode choices to the user (foreground/background/manual)
    - The launcher asks whether to enable Critic Agent (adversarial review) — passes `--critic` flag if chosen
@@ -308,8 +307,8 @@ Present this summary to the user and get explicit confirmation before proceeding
 3. **Periodic progress reports** (when user asks):
    ```bash
    python3 dev-pipeline/scripts/update-feature-status.py \
-     --feature-list feature-list.json \
-     --state-dir dev-pipeline/state \
+     --feature-list .prizmkit/plans/feature-list.json \
+     --state-dir .prizmkit/state/features \
      --action status
    ```
 
@@ -338,12 +337,12 @@ The workflow supports resuming by detecting existing state:
 
 | State Found | Resume From |
 |-------------|------------|
-| No `feature-list.json` | Phase 1: Brainstorm |
-| `feature-list.json` exists, no pipeline state | Phase 3: Launch |
-| `feature-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
+| No `.prizmkit/plans/feature-list.json` | Phase 1: Brainstorm |
+| `.prizmkit/plans/feature-list.json` exists, no pipeline state | Phase 3: Launch |
+| `.prizmkit/plans/feature-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
 | All features completed | Report completion, suggest next steps |
 
-**Resume**: If `feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
+**Resume**: If `.prizmkit/plans/feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
 
 ---
 
@@ -367,7 +366,7 @@ While the pipeline runs, the user can continue the conversation:
 | User's idea is too vague to brainstorm | Ask for more context: "Can you describe the main problem this solves?" |
 | Brainstorming stalls | Offer concrete options: "Would you prefer A or B?" |
 | `feature-planner` cannot parse requirements | Refine the requirements summary and retry |
-| `feature-list.json` generation failed | Show error, retry with refined input |
+| `.prizmkit/plans/feature-list.json` generation failed | Show error, retry with refined input |
 | Pipeline launch failed | Show daemon log, suggest manual start |
 | All features blocked/failed | Show status, suggest retrying specific features |
 | User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
@@ -378,7 +377,7 @@ While the pipeline runs, the user can continue the conversation:
 
 | Skill | Relationship |
 |-------|-------------|
-| `feature-planner` | **Called by Phase 2** — generates feature-list.json from clarified requirements |
+| `feature-planner` | **Called by Phase 2** — generates .prizmkit/plans/feature-list.json from clarified requirements |
 | `feature-pipeline-launcher` | **Called by Phase 3** — starts pipeline (handles execution mode selection) |
 | `bug-planner` | **Alternative** — for bug fix workflows |
 | `bugfix-pipeline-launcher` | **Alternative** — for bug fix pipelines |
@@ -398,7 +397,7 @@ While the pipeline runs, the user can continue the conversation:
 | **Input** | Rough idea or requirements | Bug report / stack trace | Module / code target |
 | **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
 | **User verification** | Yes (Phase 1 brainstorm confirmation) | Yes (Phase 5) | Yes (Phase 5) |
-| **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | N/A |
+| **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | (this is the batch flow) |
 
 ---
 
@@ -409,7 +408,7 @@ All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibil
 ## Output
 
 - Structured requirements summary (Phase 1 artifact)
-- `feature-list.json` (Phase 2 artifact)
+- `.prizmkit/plans/feature-list.json` (Phase 2 artifact)
 - Pipeline execution (Phase 3)
 - Progress updates (Phase 4)
 - Multiple git commits with `feat(<scope>):` prefix

package/bundled/skills/prizm-kit/SKILL.md

@@ -1,61 +1,62 @@
 ---
 name: "prizm-kit"
-description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit skill for spec-driven development, Prizm docs, code quality, deployment, and knowledge management. Use when the user asks 'which command?', 'help', 'how do I start a feature', or '/prizmkit'. (project)"
+description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit skill for spec-driven development, Prizm docs, code quality, deployment, and knowledge management. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Use this as the entry point for the full PrizmKit development lifecycle."
 ---
 
 # PrizmKit — Full-Lifecycle Development Toolkit
 
+## Task Execution Model
 
-## When to Use the Full Workflow
+PrizmKit uses **headless mode** — each task runs as an independent AI CLI session with NO context carryover between tasks. Every session starts by reading docs and ends by maintaining docs.
 
-**Full workflow** — forms a continuous loop for feature development:
+**Per-task flow**:
 ```
-read .prizm-docs → plan (specify + design + tasks) → implement → code-review → retrospective → committer
-                      ↑                                                              ↓
-                      └────────────────────── next feature ←─────────────────────────┘
+read docs → plan → implement → code-review → retrospective → committer
 ```
-- New features or user-facing capabilities
-- Multi-file coordinated changes
-- Architectural decisions, data model or API changes
 
-Each cycle produces spec, plan, and task artifacts that create a traceable record of what was built and why — `.prizm-docs/` stays in sync through retrospective, so the next cycle starts with up-to-date context.
+Each task begins by reading context at two levels:
 
-**Fast path** — for small, well-scoped changes:
+**Application level** (read every session):
+- `.prizm-docs/root.prizm` — L0 project architecture index (modules, tech stack, conventions)
+- `.prizmkit/plans/project-brief.md` — user's product vision checklist (generated by app-planner)
+- `.prizmkit/config.json` — tech stack config, deploy strategy
+
+**Task level** (read for the specific task):
+- `spec.md` / `plan.md` — task specification and implementation plan
+- `.prizm-docs/<module>.prizm` (L1/L2) — architecture docs for affected modules (TRAPS, DECISIONS, INTERFACES)
+
+Each cycle produces spec, plan, and task artifacts that create a traceable record of what was built and why. `.prizm-docs/` stays in sync through retrospective, so the next session starts with up-to-date context.
+
+**Fast path** — for small, well-scoped changes, always ask user whether to use fast path:
 ```
 /prizmkit-plan → /prizmkit-implement → /prizmkit-committer
 ```
-- Bug fixes with clear root cause
-- Simple refactors (rename, extract)
-- Documentation-only changes, test additions for existing code
 
-Fast path skips specify/analyze/review but still generates a simplified plan.md so implement has a task list to follow.
+### Development Scenarios
 
-### Bug Fix Documentation Policy
+PrizmKit supports any development scenario through the same skill chain. `/prizmkit-plan` produces `spec.md` + `plan.md` regardless of the task type:
 
-**Bug fixes MUST NOT create new documentation entries.** Bug fixes are refinements of incomplete existing features — they complete what was already planned, not introduce new functionality. Specifically:
+| Scenario | Artifacts | When to Use |
+|----------|-----------|-------------|
+| **Feature** | `spec.md` → `plan.md` → code | New functionality, UI, API, data model changes |
+| **Bug Fix** | `spec.md` → `plan.md` → code | Complex defects, regressions, crash fixes. Simple bugs can use fast path directly. |
+| **Refactor** | `spec.md` → `plan.md` → code | Restructure, extract, rename, performance. No behavior change. |
 
-- Run `/prizmkit-retrospective` with structural sync only (Job 1) for bug fix commits — skip knowledge injection unless genuinely new TRAP discovered
-- Do NOT create new spec/plan/tasks under `.prizmkit/specs/` for bug fixes
-- Do NOT update `.prizm-docs/` module docs for pure bug fixes (no interface/dependency change)
-- Bug fix commits use `fix(<scope>):` prefix in Conventional Commits, not `feat:`
+All three follow the same per-task flow. Detailed documentation policies (when to update `.prizm-docs/`, when to skip steps) are defined within each skill — not here.
 
-All documentation records are for: features, projects, code logic, and module indexes. Bug fixes do not alter the system's functional scope — they bring existing features to their intended state.
+### Best Practices for AI-Driven Development
 
-## Architecture
+**Monorepo structure recommended**: Keep frontend, backend, and shared libraries in one repository. AI needs visibility into the full call chain — cross-repo references are invisible to it. If you have a multi-repo setup, add all related repos to the AI workspace so module boundaries and API contracts are discoverable.
 
-PrizmKit produces two complementary knowledge layers:
+**Module organization**: Ensure every meaningful module has a `.prizm-docs/` L1 doc. AI reads TRAPS and DECISIONS before modifying files — undocumented modules get no guardrails.
 
-```
-.prizm-docs/           → Architecture Index (structure, interfaces, dependencies, traps, rules, decisions)
-.prizmkit/specs/       → Feature artifacts (spec → plan → implement → review cycle)
-```
+**Small, focused tasks**: Break large features into tasks that can each be completed in one AI session. The pipeline handles this automatically via `/prizmkit-plan` task decomposition.
 
 ## Core Skill Reference
 
 | Skill | Purpose | Trigger Phrases |
 |-------|---------|-----------------|
 | `/prizmkit-plan` | Specify + plan: natural language → spec.md → plan.md + tasks | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
-| `/prizmkit-analyze` | Cross-doc consistency check (read-only) | "analyze", "check consistency", "validate spec" |
 | `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
 | `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
 | `/prizmkit-retrospective` | Sync .prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
@@ -67,25 +68,14 @@ PrizmKit produces two complementary knowledge layers:
 **Reading guide**:
 - Need code structure/modules/interfaces/traps/decisions? → `.prizm-docs/`
 
-### Tier Definitions
-
-- **Tier 1**: AI can perform well independently — these tasks align with AI's core strengths (documentation, code pattern analysis, test generation)
-- **Tier 2**: Useful as guidance/checklist — AI provides static analysis and recommendations, but lacks access to real external tools (scanners, profilers, package registries, runtime environments)
-- **Core skills** (no tier label): The foundational, documentation, spec-driven workflow, and commit skills that form PrizmKit's primary value
-
-## Installation
-
-**Option 1: npm CLI (recommended — works for both platforms)**
-```bash
-npx prizmkit init
-```
-Interactive installer auto-detects your platform and guides you through configuration.
-
-**Option 2: Claude Code Plugin**
-Install the `prizmkit` plugin via Claude Code's plugin system, then run `/prizmkit-init`.
+## Quick Start (First-Time Setup)
 
-## Hook / Rules Configuration
+1. `npx prizmkit install .` → installs skills, rules (`prizm-documentation.md`, `prizm-commit-workflow.md`), hooks, platform scaffolding
+2. `/prizmkit-init` → scans project code, generates `.prizm-docs/`, detects tech stack, populates `.prizmkit/config.json`
+3. `/prizmkit-plan` → specify your first feature → produces spec.md + plan.md
+4. `/prizmkit-implement` → TDD implementation following the plan
+5. `/prizmkit-code-review` → review before commit
+6. `/prizmkit-retrospective` → sync `.prizm-docs/` with changes
+7. `/prizmkit-committer` → safe Conventional Commit
 
-Hooks and rules are configured automatically by `prizmkit-init`:
-- `assets/project-memory-template.md` for the project memory template
-- The init skill creates `prizm-documentation.md` and `prizm-commit-workflow.md` rules
+> **Note**: Rules and hooks are installed by `npx prizmkit install`, not by `/prizmkit-init`.