prizmkit 1.1.7 → 1.1.9

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -1,102 +1,89 @@
 ---
 name: "prizmkit-code-review"
-description: "Code review with fix strategy formulation. Diagnoses issues across 6 dimensions, then produces structured Fix Instructions. Use after /prizmkit-implement as quality gate before committing. Trigger on: 'review', 'check code', 'code review', 'is it ready to commit'. (project)"
+description: "Code review against spec and plan. Diagnoses issues across multiple dimensions, produces findings with fix instructions. Use after /prizmkit-implement as quality gate. Trigger on: 'review', 'check code', 'code review', 'is it ready to commit'. (project)"
 ---
 
 # PrizmKit Code Review
 
-Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. This skill has two phases:
-
-1. **Diagnostic Review** — read-only analysis producing findings with severity ratings
-2. **Fix Strategy Formulation** — for each finding, produce actionable Fix Instructions
-
-The review itself is read-only. Fix Instructions are structured guidance for the developer — the reviewer does not modify code.
+Review code changes against the spec, plan, and project conventions. Produces a diagnostic report with findings and actionable fix instructions. The review itself is read-only — no source code is modified.
 
 ### When to Use
 - After `/prizmkit-implement` to verify code quality before commit
 - User says "review", "check code", "review my implementation"
 - As a quality gate before `/prizmkit-committer`
 
-**PRECONDITION:**
+### When NOT to Use
+- Trivial changes (typo, single-line config) → commit directly
+- No spec.md or plan.md exists → nothing to review against
 
-| Mode | Required Artifacts | Directory | Check | If Missing |
-|---|---|---|---|---|
-| **Feature** | `spec.md` + `plan.md` (with Tasks) | `.prizmkit/specs/###-feature-name/` | Files exist + tasks completed | Run `/prizmkit-implement` |
-| **Refactor** | `refactor-analysis.md` + `plan.md` (with Tasks) | `.prizmkit/refactor/<refactor-slug>/` | Files exist + tasks completed. Review against behavior preservation, not spec. | Run `/prizmkit-implement` in refactor mode |
-| **Bugfix** | `fix-plan.md` | `.prizmkit/bugfix/<BUG_ID>/` | File exists + tasks completed. Review against bug description + reproduction test. | Run `/prizmkit-implement` in bugfix mode |
+## Input
 
-**Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md` whose tasks are all completed. |
 
-## Phase 1: Diagnostic Review
+## Context Loading
 
-1. **Detect mode and load review baseline + dimension rules**:
-   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-feature.md` for review dimensions.
-   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-refactor.md` for refactor-specific dimensions, **and also** `${SKILL_DIR}/rules/dimensions-feature.md` §3–§6 for standard dimensions (code quality, security, consistency, test coverage) that still apply.
-   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-bugfix.md` for review dimensions.
-   - If none found → prompt user: "No review baseline found. Which workflow are you in? (feature/refactor/bugfix)"
-2. Read **architecture index**: `.prizm-docs/root.prizm` RULES and PATTERNS for project conventions
-3. Read **past decisions**: check DECISIONS sections in relevant `.prizm-docs/` L1/L2 files — helps verify implementation respects established conventions
-4. Read '## Implementation Log' section of context-snapshot.md in the feature directory (if exists) — understand Dev's implementation decisions, trade-offs, and notable discoveries. This context helps distinguish intentional design choices from accidental patterns during review.
-5. Scan all code files referenced in completed tasks
-6. Review across all dimensions defined in the loaded rules file
-7. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
+1. **Task context**: Read `spec.md`, `plan.md`, and any companion documents (e.g., `refactor-analysis.md`) from the artifact directory.
+2. **Architecture context**: Read `.prizm-docs/root.prizm` (L0) and relevant L1/L2 docs for affected modules — check RULES, PATTERNS, TRAPS, DECISIONS.
 
-## Phase 2: Fix Strategy Formulation
+## Phase 1: Diagnostic Review
 
-Load `${SKILL_DIR}/rules/fix-strategy.md` for the complete fix formulation process, finding format, grouping rules, and priority ordering.
+1. **Identify changed files**: Extract file paths from completed tasks in plan.md, or use `git diff` against the branch base.
+2. **Read changed files**: Scan all code files identified above.
+3. **Review across dimensions**: Load `${SKILL_DIR}/rules/dimensions.md` and evaluate each applicable dimension. Dimensions are conditionally triggered based on what sections exist in spec.md — see the dimensions file for trigger conditions.
+4. **Generate findings**: For each issue found, describe the problem, its location, which dimension it falls under, and why it matters.
+5. If unsure whether something is a bug or intentional design, flag it with a note asking the developer to confirm.
 
-For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable), follow the fix strategy rules to produce structured Fix Instructions.
+## Phase 2: Fix Strategy
 
-## Severity & Verdict
+For each finding, load `${SKILL_DIR}/rules/fix-strategy.md` and produce structured Fix Instructions: Root Cause, Impact, Fix Strategy, Code Guidance, Verification Criteria.
 
-Spec compliance failures are always HIGH or CRITICAL — if the code doesn't match what was agreed in the spec, that's a functional gap, not a style issue. Security findings follow the same rule.
+## Reviewer Agent Mode
 
-**Verdict criteria:**
-- `PASS`: No CRITICAL or HIGH findings
-- `PASS WITH WARNINGS`: No CRITICAL findings, some HIGH findings
-- `NEEDS FIXES`: Any CRITICAL findings present
+When interactive session is available, offer the option to spawn an independent reviewer subagent:
 
-Cap findings at 30 to keep the review actionable. If there are more, summarize the overflow with counts by dimension.
+1. Spawn a reviewer subagent with **read-only** permissions (Read, Glob, Grep, Bash for test commands only)
+2. The subagent independently reviews changed files against spec/plan/dimensions and produces findings
+3. The main agent receives findings and applies fixes
+4. Re-spawn the subagent to verify fixes
+5. Repeat until the subagent reports no more findings or the caller's maximum iteration limit is reached
 
-If you're unsure whether something is a bug or intentional design, flag it as MEDIUM with a note asking the developer to confirm. Don't silently skip uncertain findings.
+In non-interactive mode, perform the review directly (no subagent).
 
-## Review Notes Format
+## Output
 
-When writing to context-snapshot.md, use this structured format:
+Write `review-report.md` to the artifact directory:
 
 ```markdown
-## Review Notes
-
-### Verdict: PASS | PASS_WITH_WARNINGS | NEEDS_FIXES
-### Review Iteration: 1/5
-### Summary: X findings (N critical, N high, N medium, N low)
+# Review Report
 
-### Fix Instructions (ordered by priority)
+## Verdict: PASS | NEEDS_FIXES
 
-#### FIX-1: [SEVERITY] Title
-(finding format per ${SKILL_DIR}/rules/fix-strategy.md)
+## Summary: X findings
 
-#### FIX-2: [SEVERITY] Title
-...
+## Findings
 
-### Re-Review Expectations
-After fixes are applied, the reviewer expects:
-1. (specific grep/test commands that should pass)
-2. (behavioral checks)
-3. All existing tests pass
+### Finding 1: Title
+- Location: file:line
+- Dimension: category
+- Problem: what is wrong and why it matters
+- Root Cause: explanation
+- Impact: affected callers/dependents
+- Fix Strategy: step-by-step
+- Code Guidance: before/after snippet
+- Verification: commands/checks to confirm
+- Related: Finding N (if grouped)
 ```
 
-**HANDOFF:** `/prizmkit-retrospective` (if PASS) or Dev fixes following Fix Instructions (if NEEDS FIXES)
+- `PASS`: 0 findings
+- `NEEDS_FIXES`: 1+ findings with fix instructions
 
-## Loop Protection
+Also output findings summary to conversation.
 
-In unattended pipeline mode, the review→fix→review cycle can loop indefinitely if fixes introduce new issues. To prevent this:
+**HANDOFF:** `/prizmkit-retrospective` (if no findings) or apply fixes and re-review (if findings exist)
 
-- Track a `review_iteration` counter starting at 1. Each review-fix-review cycle increments the counter.
-- **max_iterations = 5**: If `review_iteration >= 5`, you MUST proceed to `/prizmkit-retrospective` regardless of remaining findings. Log remaining issues as known technical debt: "Loop protection triggered — proceeding to retrospective with N unresolved findings (iterations: 5/5)."
-- Unresolved findings should be recorded in the review report so they can be tracked as follow-up work.
-- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full dimension review unless new code was added beyond the fix scope.
-
-## Output
+## References
 
-Review report with Fix Instructions is output to conversation and written to the '## Review Notes' section of context-snapshot.md. No source code files are created or modified.
+- Review dimensions: `${SKILL_DIR}/rules/dimensions.md`
+- Fix strategy formulation: `${SKILL_DIR}/rules/fix-strategy.md`

package/bundled/skills/prizmkit-code-review/rules/dimensions.md

@@ -0,0 +1,85 @@
+# Review Dimensions
+
+Evaluate code changes across the following dimensions. Each dimension is either **always active** or **conditionally triggered** based on spec.md content.
+
+---
+
+## §1 Goal Compliance (always active)
+
+Does code implement all goals and acceptance criteria from spec.md?
+
+- Check every goal (G-N) in spec.md has a corresponding implementation
+- Verify acceptance criteria are met
+- Verify edge cases mentioned in spec are handled
+- Confirm scope boundaries are respected (no over-implementation, no under-implementation)
+
+## §2 Plan Adherence (always active)
+
+Does implementation follow architectural decisions in plan.md?
+
+- Check component structure matches plan's change approach
+- Verify data model matches plan's schema design (if applicable)
+- Confirm API contracts (endpoints, request/response) match plan (if applicable)
+- Deviations may be improvements — flag for confirmation, not automatic rejection
+
+## §3 Behavior Preservation (conditional: spec.md has `## Behavior Preservation`)
+
+Observable behavior for existing functionality must remain unchanged.
+
+- All existing tests still pass without modification
+- Public API signatures are unchanged (parameter types, return types, error types)
+- Side effects (logging, metrics, events) are preserved unless explicitly scoped for removal
+- Edge case handling is preserved — changes often silently drop edge case branches
+
+## §4 Code Quality (always active)
+
+Naming, structure, complexity, DRY. Focus on maintainability.
+
+- Function/variable names are descriptive and consistent with project conventions
+- No unnecessary complexity (deep nesting, oversized functions)
+- No copy-paste duplication that should be abstracted
+- Error messages are informative for debugging
+
+## §5 Security (always active)
+
+Injection, auth/authz gaps, sensitive data exposure, insecure defaults.
+
+- User input is validated and sanitized before use in queries, HTML, or commands
+- Authentication and authorization checks are present on protected routes
+- Sensitive data (passwords, tokens, PII) is not logged or exposed in responses
+- Cryptographic operations use established libraries, not custom implementations
+
+## §6 Consistency (always active)
+
+Follows project patterns from `.prizm-docs/` PATTERNS and RULES sections.
+
+- Code style matches existing codebase conventions
+- Error handling follows established patterns
+- File organization follows project structure conventions
+- Naming conventions align with `.prizm-docs/` RULES
+
+## §7 Test Coverage (always active)
+
+Are critical paths tested?
+
+- Happy path tests exist for each goal
+- Error/edge case tests for critical paths
+- Tests are deterministic (no flaky timing dependencies)
+- Test names clearly describe what they verify
+
+## §8 Fix Correctness (conditional: spec.md has `## Root Cause`)
+
+The fix addresses the actual root cause, not just symptoms.
+
+- The root cause identified in spec.md is addressed
+- A regression test exists that would catch this issue if reintroduced
+- The fix does not change behavior for non-affected inputs
+- Related code paths are not inadvertently affected
+
+## §9 Change Scope (conditional: spec.md `## Scope` emphasizes minimal change)
+
+Only files directly related to the task are modified.
+
+- No "while I'm here" changes mixed with the primary task
+- If scope creep is detected, flag it — those changes belong in a separate commit
+- Structural improvement (refactoring) is measured against stated goals, not unbounded

package/bundled/skills/prizmkit-code-review/rules/fix-strategy.md

@@ -1,6 +1,6 @@
 # Fix Strategy Formulation
 
-For each finding from the Diagnostic Review (CRITICAL and HIGH mandatory; MEDIUM/LOW when actionable):
+For each finding from the Diagnostic Review, produce actionable Fix Instructions.
 
 ## Per-Finding Analysis
 
@@ -14,7 +14,7 @@ Search the codebase for all callers/dependents of the affected code. List concre
 Concrete step-by-step modification plan:
 - What to change, where, and in what order
 - Which project conventions to follow (reference `.prizm-docs/` RULES)
-- Dependencies between fixes (FIX-1 must be done before FIX-3)
+- Dependencies between fixes (Finding 1 must be done before Finding 3)
 
 ### 4. Code Guidance
 Show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation.
@@ -27,21 +27,21 @@ How to confirm the fix works:
 
 ## Finding Grouping
 
-Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+Group related findings that should be fixed together. If Finding 1 and Finding 3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents fixing symptoms individually only to have the underlying cause persist.
 
-## Fix Priority Ordering
+## Fix Ordering
 
 Order Fix Instructions by:
-1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
-2. **CRITICAL before HIGH** — severity determines priority within independent fixes
-3. **Grouped fixes together** — related findings are adjacent
+1. **Dependencies first** — if Finding 2 depends on Finding 1, Finding 1 comes first
+2. **Grouped fixes together** — related findings are adjacent
 
 ## Finding Format
 
 ```
-#### FIX-N: [SEVERITY] Title
+### Finding N: Title
 - Location: file:line
 - Dimension: category
+- Problem: what is wrong and why it matters
 - Root Cause: explanation
 - Impact: affected callers/dependents with file:line locations
 - Fix Strategy:
@@ -55,7 +55,7 @@ Order Fix Instructions by:
 - Verification:
   - command to run
   - expected output
-- Related: FIX-X (if grouped)
-- Depends On: FIX-Y (if dependency)
-- Blocks: FIX-Z (if blocking)
+- Related: Finding X (if grouped)
+- Depends On: Finding Y (if dependency)
+- Blocks: Finding Z (if blocking)
 ```

package/bundled/skills/prizmkit-committer/SKILL.md

@@ -16,8 +16,8 @@ description: "Pure git commit workflow with safety checks. Stages files, generat
 |---|---|---|
 | Uncommitted changes exist | `git status` shows modified/added/untracked files | Inform user "nothing to commit" and stop |
 | `.prizm-docs/` synced (feature/refactor) | `/prizmkit-retrospective` has run | Run `/prizmkit-retrospective` first |
-| Code review passed (pipeline mode) | `context-snapshot.md` has Review Notes with PASS/PASS_WITH_WARNINGS | Run `/prizmkit-code-review` first |
-| `DEPLOY.md` updated (if applicable) | If `/prizmkit-deploy` ran, `DEPLOY.md` is staged | Run `/prizmkit-deploy` or skip if no infrastructure changes |
+| Code review passed (pipeline mode) | `review-report.md` in artifact directory has `## Verdict: PASS` | Run `/prizmkit-code-review` first |
+| `.prizmkit/deploy.md` updated (if applicable) | If `/prizmkit-deploy` ran, `.prizmkit/deploy.md` is staged | Run `/prizmkit-deploy` or skip if no infrastructure changes |
 
 ### Workflow
 
@@ -31,7 +31,7 @@ git status
 - If there are changes: proceed
 
 #### Step 2: Generate Commit Message
-Analyze the staged diff and context (spec title, plan summary, review verdict) to generate a concise Conventional Commits message. The message should capture the *what* and *why* of the change.
+Analyze the staged diff and context (spec title, plan summary) to generate a concise Conventional Commits message. The message should capture the *what* and *why* of the change.
 
 #### Step 3: Update CHANGELOG.md
 If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
@@ -62,34 +62,6 @@ git status
 ```
 - If "nothing to commit, working tree clean": commit verified successfully, proceed
 
-#### Step 5.5: Generate Session Summary (for cross-session recovery)
-
-After a successful commit, generate a lightweight handoff file for future sessions. Locate the artifact directory (`.prizmkit/specs/<feature-dir>/` for features, `.prizmkit/refactor/<slug>/` for refactors, `.prizmkit/bugfix/<id>/` for bugfixes) by checking which `plan.md` was used in this workflow.
-
-If an artifact directory with `plan.md` is found, write `session-summary.md` in that directory:
-
-```markdown
-# Session Summary
-## Completed Tasks
-<list task IDs and one-line descriptions from plan.md [x] items>
-
-## Files Changed
-<list from `git diff HEAD~1 --name-only` of the commit just made>
-
-## Key Decisions
-<1-3 bullet points of non-obvious design choices made this session, referencing DECISIONS in .prizm-docs/ if applicable>
-
-## Active TRAPS
-<any CRITICAL or HIGH TRAPS relevant to the changed files, copied from .prizm-docs/ L2>
-
-## Remaining Work
-<list unchecked [ ] task IDs from plan.md, or "None — feature complete" if all done>
-```
-
-Keep this file under 1.5KB. If no artifact directory with `plan.md` can be identified (e.g., ad-hoc commit), skip this step.
-
-**Lifecycle**: `session-summary.md` is a local cross-session artifact — do NOT commit it to git. It exists only on disk for the next session to read. Overwrite any existing `session-summary.md` from a previous session — this file reflects only the most recent commit's state. In pipeline mode, this file will remain as an untracked file after commit; the pipeline runner should ignore it (it is not a sign of incomplete work).
-
 #### Step 6: Optional Push
 Ask user: "Push to remote?"
 - Yes: `git push`

package/bundled/skills/prizmkit-deploy/SKILL.md

@@ -1,73 +1,76 @@
 ---
 name: "prizmkit-deploy"
-description: "Generate or update DEPLOY.md with local dev setup, testing, production deployment, and rollback procedures. Fully autonomous. Use after /prizmkit-retrospective, before /prizmkit-committer. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'DEPLOY.md'. (project)"
+description: "Generate or update .prizmkit/deploy.md with local dev setup, testing, production deployment, and rollback procedures. On-demand skill — trigger when deployment docs are needed. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'deploy.md'. (project)"
 ---
 
 # PrizmKit Deploy
 
 ### When to Use
-- After `/prizmkit-retrospective` and before `/prizmkit-committer` to complete documentation before commit
-- After a batch of features has been implemented and reviewed
 - When the project has no deployment documentation yet
 - When new infrastructure components have been added (new database, cache, message queue, etc.)
+- When deployment-related configuration has changed significantly
+- When explicitly requested by user or caller
 
 ### When NOT to Use
-- Mid-feature development (deployment docs should reflect reviewed, stable code)
-- For actual deployment execution (this skill only produces docs)
-- Fast-path bug fixes (no deployment doc update needed)
+- For actual deployment execution (this skill only produces documentation)
+- When only application logic changed with no infra/config impact
 
-### Pipeline Safety
-- **Fully autonomous** — no user interaction required at any step
+> **On-demand skill** — not part of the default `plan → implement → code-review → retrospective → committer` chain. Invoke independently when deployment documentation needs creation or update.
+
+### PRECONDITION
+- Project contains deployable artifacts (at least one of: `package.json`, `Dockerfile`, `Makefile`, `go.mod`, `Cargo.toml`, `pyproject.toml`, or equivalent)
+
+## Context Loading
+
+1. **Architecture context**: Read `.prizm-docs/root.prizm` → identify modules with deployment-relevant components (APIs, services, workers)
+2. **Project config**: Read `.prizmkit/config.json` for `deploy_strategy` and `tech_stack`
+   - If `.prizmkit/config.json` does not exist → proceed without it, infer from project file scanning. Log warning: "No .prizmkit/config.json found — inferring deployment strategy from project files."
+3. **Module detail**: Read relevant `.prizm-docs/<module>.prizm` L1/L2 for INTERFACES and DEPENDENCIES sections that inform deployment topology
 
 ## Execution Steps
 
-**Phase 1 — Context Gathering:**
-1. Read `.prizmkit/config.json`:
-   - `deploy_strategy` — user's confirmed deployment approach (may be absent)
-   - `tech_stack` — detected or user-provided technology stack
-   - **If `.prizmkit/config.json` does not exist**: proceed without it — infer deployment approach entirely from project file scanning in steps 2-3. Log a warning: "No .prizmkit/config.json found — inferring deployment strategy from project files. Run `/prizmkit-init` to generate config."
-2. Scan project for deployment-related files:
+**Phase 1 — Project Scanning:**
+1. Scan project for deployment-related files:
    - Container: `Dockerfile`, `docker-compose.yml`, `.dockerignore`
    - Cloud platforms: `vercel.json`, `netlify.toml`, `fly.toml`, `app.yaml` (GCP), `appspec.yml` (AWS)
    - CI/CD: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`
    - Package managers: `package.json` scripts (start, build, preview), `Makefile`, `Procfile`
    - Infrastructure as Code: `terraform/`, `pulumi/`, `cdk/`, `serverless.yml`
-3. Scan source code for environment variable references:
+2. Scan source code for environment variable references:
    - Grep for `process.env.`, `os.environ`, `os.Getenv`, `env::var`, `System.getenv`
    - Cross-reference with `.env.example`, `.env.template`, or `.env.sample` if they exist
    - Catalog all env vars with their usage context
-4. Check for existing `DEPLOY.md` (or `docs/deployment.md`, `docs/DEPLOY.md`)
-5. Read recent git log to identify newly added infrastructure components since last deploy doc update:
-   - If `DEPLOY.md` exists → use `git log -1 --format=%H -- DEPLOY.md` to find the last commit that touched it, then `git diff <that-commit>..HEAD` to identify new infra files
-   - If `DEPLOY.md` does not exist → treat all infrastructure as "new"
+3. Check for existing `.prizmkit/deploy.md`
+4. If `.prizmkit/deploy.md` exists → use `git log` to identify infra changes since last update; otherwise treat all infrastructure as "new"
 
 **Phase 2 — Document Generation:**
-6. If NO existing deploy doc:
-   - Generate full `DEPLOY.md` from template (`${SKILL_DIR}/assets/deploy-template.md`)
+5. If NO existing deploy doc:
+   - Generate `.prizmkit/deploy.md` from template (`${SKILL_DIR}/assets/deploy-template.md`)
    - Fill all sections based on scanned project state
    - If `deploy_strategy` exists in config → use it as the authoritative deployment approach
-   - If `deploy_strategy` is absent → infer from detected files (Dockerfile → Docker-based, vercel.json → Vercel, etc.) and note "Inferred from project files — confirm with `/prizmkit-plan` on next feature"
-7. If existing deploy doc found:
+   - If `deploy_strategy` is absent → infer from detected files (Dockerfile → Docker-based, vercel.json → Vercel, etc.) and note "Inferred from project files"
+6. If existing deploy doc found:
    - Compare current project state against documented state
    - Identify gaps: new env vars not documented, new services not covered, outdated commands
    - Apply incremental updates — preserve user-written sections, only add/update auto-detectable content
    - Mark updated sections with `<!-- Updated by prizmkit-deploy -->` comment
 
 **Phase 3 — Validation:**
-8. Verify completeness checklist:
+7. Verify completeness checklist:
    - [ ] All detected env vars are documented with descriptions
    - [ ] Local development setup commands are runnable (check referenced scripts/commands exist)
    - [ ] Build command documented and exists in package.json/Makefile
-   - [ ] Production deployment steps match `deploy_strategy` in config
+   - [ ] Production deployment steps match `deploy_strategy` in config (if configured)
    - [ ] Health check or verification step is included
-9. If any checklist item fails, add a `## TODO` section at the bottom listing what needs manual completion
-10. Output: `DEPLOY.md` path, summary of sections generated/updated, list of TODOs if any
+8. If any checklist item fails, add a `## TODO` section at the bottom listing what needs manual completion
+9. If interactive session is available → show summary and ask if user wants to review before finishing
+10. Output: `.prizmkit/deploy.md` path, summary of sections generated/updated, list of TODOs if any
 
-**HANDOFF:** `/prizmkit-committer` — commit all changes including the updated `DEPLOY.md`.
+**HANDOFF:** `/prizmkit-committer` — commit changes including `.prizmkit/deploy.md`.
 
 ## Document Sections
 
-The generated `DEPLOY.md` includes these sections (skip any that don't apply to the project):
+The generated deploy doc includes these sections (skip any that don't apply to the project):
 
 | Section | Content | Source |
 |---------|---------|--------|
@@ -84,7 +87,7 @@ The generated `DEPLOY.md` includes these sections (skip any that don't apply to
 
 ## Incremental Update Rules
 
-When updating an existing `DEPLOY.md`:
+When updating an existing `.prizmkit/deploy.md`:
 - **NEVER delete** user-written content (sections without `<!-- Updated by prizmkit-deploy -->` markers)
 - **ADD** newly detected env vars to the Environment Variables table
 - **ADD** new services/components to Production Deployment
@@ -99,7 +102,7 @@ When updating an existing `DEPLOY.md`:
 - Project has `Dockerfile`, `docker-compose.yml`, `package.json` with build script
 - 12 env vars detected in source code, `.env.example` has 8
 
-**Output:** `DEPLOY.md` with all sections filled, plus TODO:
+**Output:** `.prizmkit/deploy.md` with all sections filled, plus TODO:
 ```
 ## TODO
 - [ ] 4 environment variables found in code but missing from `.env.example`: `REDIS_URL`, `SMTP_HOST`, `SMTP_PORT`, `SENTRY_DSN`

package/bundled/skills/prizmkit-deploy/assets/deploy-template.md

@@ -1,5 +1,5 @@
 # Deployment Guide: [PROJECT_NAME]
-<!-- Replace [PROJECT_NAME] with: project_name from feature-list.json, or name from package.json, or the project root directory name (in that priority order) -->
+<!-- Replace [PROJECT_NAME] with: name from package.json, or the project root directory name -->
 
 > Generated by PrizmKit Deploy
 

package/bundled/skills/prizmkit-implement/SKILL.md

@@ -1,87 +1,55 @@
 ---
 name: "prizmkit-implement"
-description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan (or /prizmkit-analyze). Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
 ---
 
 # PrizmKit Implement
 
 ### When to Use
-- After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
+- After `/prizmkit-plan` when ready to write code
 - User says "implement", "build", "code it", "start coding", "develop"
 - For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
 **PRECONDITION:**
 
-| Mode | Required Artifact | Directory | Check | If Missing |
-|---|---|---|---|---|
-| **Feature** (default) | `plan.md` with Tasks section | `.prizmkit/specs/###-feature-name/` | File exists + unchecked tasks | Run `/prizmkit-plan` |
-| **Refactor** | `plan.md` with Tasks section | `.prizmkit/refactor/<refactor-slug>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in refactor mode |
-| **Bugfix** | `plan.md` with Tasks section | `.prizmkit/bugfix/<BUG_ID>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in bugfix mode |
-
-**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
-
-## Execution Steps
-
-1. **Detect mode and read context**:
-   - Locate `plan.md` (check the artifact directory passed by the calling workflow, or auto-detect per PRECONDITION above)
-   - Read `plan.md` (including Tasks section)
-   - Read the companion input document for full context:
-     - **Feature mode**: read `spec.md` in the same directory
-     - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
-     - **Bugfix mode**: read `fix-plan.md` in the same directory
-2. Load project context — use the most efficient source available (check in this order):
-   - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS. Section 4 has File Manifest (Tier-2/3) or full source (Tier-1). Read source files on-demand as directed by the manifest.
-   - Else if `session-summary.md` exists in the feature directory → read it for quick context recovery (completed tasks, key decisions, active TRAPS). Then load only the L1/L2 docs for modules listed in "Files Changed" — skip unrelated modules.
-   - Otherwise → **self-service context fallback**:
-     1. Read **architecture index**: `.prizm-docs/root.prizm` and relevant L1/L2 for affected modules. Pay special attention to TRAPS and DECISIONS.
-     2. Scan needed source files
-3. Check if checkpoint tasks are complete before proceeding to next phase
-4. For each unchecked task in order:
-   a. If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group
-   b. Read L2 doc for target file's module. TRAPS save you from repeating known mistakes.
-      - If L2 exists: check TRAPS and DECISIONS before modifying files.
-      - If L2 does not exist and this task creates a new module directory or adds significant source files: create L2 using the L2 GENERATION TEMPLATE (see PRIZM-SPEC). Seed KEY_FILES and DEPENDENCIES from the files being created. TRAPS and DECISIONS can be minimal initially — `/prizmkit-retrospective` will enrich them.
-      - Judgment call: not every directory needs L2. Create L2 when the module has meaningful logic, non-obvious coupling, or design decisions worth preserving. Skip for trivial wrapper directories or single-config modules.
-   c. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
-   d. Mark task as `[x]` in `plan.md` Tasks section immediately — not batched at the end. Immediate marking means the plan always reflects true progress, even if the session is interrupted.
-   e. After all tasks, append '## Implementation Log' to `context-snapshot.md` (if running in pipeline context): files changed/created, key decisions, notable discoveries.
-   f. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
-5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
-6. After all tasks: run full test suite
-7. **Deploy guide update** — only when dependency manifests (package.json, requirements.txt, etc.) changed during this task.
-      → Read `${SKILL_DIR}/references/deploy-guide-protocol.md` and follow its protocol.
-8. Output implementation summary with pass/fail status
-
-## Task Format in plan.md
-
-Tasks in plan.md look like this:
-```markdown
-## Tasks
-
-### Phase 1: Data Layer
-- [ ] Create User model with avatar field in src/models/user.ts
-- [ ] Add S3 upload utility in src/lib/s3.ts
-- [x] ~~Set up database migration~~ (already done)
-
-### Phase 2: API [P]
-- [ ] [P] POST /api/avatar endpoint in src/routes/avatar.ts
-- [ ] [P] DELETE /api/avatar endpoint in src/routes/avatar.ts
-
-### Phase 3: UI
-- [ ] Avatar upload component in src/components/AvatarUpload.tsx
-- [ ] CP: Integration checkpoint — full test suite must pass
-```
-
-- `[ ]` / `[x]` — unchecked / completed
-- `[P]` — can run in parallel with other `[P]` tasks in the same phase
-- `CP:` — checkpoint where build + tests must pass before continuing
+| Required Artifact | Check | If Missing |
+|---|---|---|
+| `plan.md` with Tasks section | File exists + unchecked tasks | Run `/prizmkit-plan` |
+| `spec.md` | File exists in same directory as plan.md | Run `/prizmkit-plan` |
+
+**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, auto-detect per precondition above. |
+
+## Context Loading
+
+Before implementation, load context once:
+
+1. **Task context**: Read `plan.md` (including Tasks section) and `spec.md` from the artifact directory. If other companion documents exist in the directory (e.g., `refactor-analysis.md`), read them for additional context.
+2. **Architecture context**: Read `.prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1/L2 docs for affected modules. Pay special attention to TRAPS (known pitfalls) and DECISIONS (architectural choices).
+
+> `.prizm-docs/` uses a 3-level hierarchy: L0 (`root.prizm`) is the project-wide index. L1 (e.g., `auth.prizm`) covers a module — its key files, interfaces, dependencies, traps, and decisions. L2 is for sub-modules with their own complexity. Implement reads these docs to avoid repeating known mistakes; `/prizmkit-retrospective` is responsible for updating them after implementation.
+
+## Execution
+
+For each unchecked task in plan.md, in order:
+
+1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
+2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+3. Mark task as `[x]` in `plan.md` immediately after completion — not batched at the end. Immediate marking means plan.md always reflects true progress, even if the session is interrupted.
+4. **Parallel tasks**: If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group. Sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
+5. **Checkpoint tasks** (`CP:` prefix in plan.md): When a checkpoint task is reached, verify build passes and tests pass before continuing. Checkpoints catch integration errors early — skipping them means cascading failures in later phases.
+6. After all tasks complete: run full test suite.
 
 ## Recovery
 
 If a session is interrupted mid-implementation:
 - Completed tasks are already marked `[x]` in plan.md (because we mark immediately)
-- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked task
-- context-snapshot.md persists across sessions for consistent context
+- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked `[ ]` task
 
 **HANDOFF:** `/prizmkit-code-review`
 
@@ -89,5 +57,4 @@ If a session is interrupted mid-implementation:
 
 - Code files created/modified as specified in plan.md Tasks section
 - `plan.md` Tasks section updated with completion markers `[x]`
-- `DEPLOY.md` created/updated (only when new frameworks/tools were added)
 - Implementation summary output to conversation