prizmkit 1.1.111 → 1.1.113

package/bundled/skills/prizmkit-deploy/references/database-setup.md

@@ -10,7 +10,14 @@ During Discovery Step 1 (Project Detection), database drivers were already scann
 > - **Yes** → proceed with database installation
 > - **No** → skip, record in deploy.md with note "database must be configured by user"
 
-## PostgreSQL setup
+## Secrets file safety
+
+Before writing `.prizmkit/deploy/secrets.local.json`:
+
+1. Verify `.gitignore` or an equivalent ignore rule covers `.prizmkit/deploy/secrets.local.json` and any `.prizmkit/deploy/*.local.json` pattern used by the project.
+2. If the ignore rule is missing, pause and add or request the ignore rule before writing secrets.
+3. Set the secrets file permissions to current-user read/write only, for example `chmod 600 .prizmkit/deploy/secrets.local.json` on POSIX systems.
+4. Record only presence metadata in deploy config, docs, reports, and history. Never copy raw passwords, connection strings, passphrases, decryption keys, unsalted hashes, or full env var values into committed files.
 
 ```
 apt-get install -y postgresql postgresql-contrib
@@ -21,7 +28,8 @@ sudo -u postgres psql -c "GRANT ALL ON DATABASE <project> TO <project>;"
 
 - Generate a secure random password (32 chars, alphanumeric + symbols).
 - Write the connection string to `.prizmkit/deploy/secrets.local.json`: `DATABASE_URL=postgresql://<project>:<password>@localhost:5432/<project>`.
-- In deploy.md, write: "PostgreSQL installed, connection info recorded in `.prizmkit/deploy/secrets.local.json` (not committed to git)".
+- Set `.prizmkit/deploy/secrets.local.json` permissions to current-user read/write only after writing.
+- In deploy.md, write: "PostgreSQL installed, connection info recorded in `.prizmkit/deploy/secrets.local.json` (gitignored; raw value not committed)".
 
 ## MySQL setup (future)
 
@@ -37,10 +45,11 @@ redis-cli CONFIG REWRITE
 
 - Bind to localhost only (modify `/etc/redis/redis.conf` if needed).
 - Write `REDIS_URL=redis://:<password>@localhost:6379` to `.prizmkit/deploy/secrets.local.json`.
+- Set `.prizmkit/deploy/secrets.local.json` permissions to current-user read/write only after writing.
 
 ## Security notes
 
 - Never write database passwords to deploy.md, because deploy.md may be committed to git and passwords would leak.
-- Passwords stored in `.prizmkit/deploy/secrets.local.json` (gitignored).
+- Passwords stored in `.prizmkit/deploy/secrets.local.json` only after verifying the file is ignored by git and locked down to current-user read/write permissions.
 - Default: database binds to localhost, no external access, because most indie projects only need local connections.
 - Record a `"database-setup"` event in deploy history (presence metadata only, no passwords).

package/bundled/skills/prizmkit-deploy/references/ssh-adapter-flow.md

@@ -0,0 +1,220 @@
+# SSH Adapter Flow
+
+Read this file when Discovery routes `/prizmkit-deploy` to SSH Linux full automation.
+
+The SSH adapter supports Node.js projects using PM2 + Nginx blue/green deployment.
+
+## 1. Deployment Mode Selection
+
+Before entering the configuration wizard, ask how the user wants to deploy:
+
+1. **Direct Upload** — build locally, transfer artifacts to the server, start with PM2. Best for first deployment and low-spec servers.
+2. **CI/CD Auto-Deploy** — configure GitHub Actions so pushes deploy automatically.
+
+If the user chooses CI/CD, ask which mode:
+
+- **Push mode** — GitHub Actions builds and SCPs artifacts to server. Low server load.
+- **Pull mode** — server pulls code and builds itself. Simpler workflow but requires a deploy key and build tools on the server.
+
+Read `references/deployment-modes.md` when the user needs the full comparison.
+
+Config field: `deployStrategy` in `deploy.config.json` is `direct-upload`, `ci-cd-push`, or `ci-cd-pull`. Existing configs without this field default to `ci-cd-pull` for backward compatibility.
+
+## 2. Server Model
+
+A valid SSH target:
+
+- Is reachable over SSH.
+- Provides a Linux shell.
+- Can install or already has Node.js, npm, PM2, Nginx, and Git.
+- Can access the configured repository when using CI/CD Pull mode.
+
+Roles:
+
+- `bootstrapUser`: usually root; installs packages and creates users/directories.
+- `runtimeUser`: default `deploy`; app processes run as this user and never as root.
+
+Server-side layout:
+
+```text
+/var/www/<project>/
+  releases/
+    <release-id>/
+  shared/
+    .env.production
+    deploy-metadata.json
+  current -> releases/<release-id>
+  deploy-logs/
+```
+
+`shared/.env.production` must be mode `600` and owned by the runtime user.
+
+## 3. First-Run Configuration Wizard
+
+Flow: deployment mode → collect → validate → confirm → persist.
+
+Collect:
+
+1. SSH server host/port, bootstrap user, runtime user, auth method.
+2. Repository access only for `ci-cd-pull`: Git URL, branch, deploy-key or other auth.
+3. App configuration: app id, path, package manager, install/build/start commands, blue/green port pair, health checks.
+4. Environment variables: scan source for env references, ask for values or storage strategy.
+5. Persist `deploy.config.json` and `deploy.md`.
+
+Validate SSH immediately with a harmless connectivity command before collecting deeper config. If SSH fails, stop and fix connectivity first.
+
+## 4. Bootstrap
+
+Before privileged bootstrap, present an action plan listing:
+
+- packages to install
+- users/groups to create
+- SSH keys to generate
+- Nginx config files to create/update
+- directories and permissions
+- services that may restart
+
+Rules:
+
+- User gives one explicit approval for the bootstrap plan.
+- If the plan changes during execution, pause and ask again.
+- Bootstrap operations must be idempotent.
+- Existing config files must be backed up before modification.
+- Failed bootstrap stops before deployment and provides recovery instructions.
+
+Read `references/ssh-bootstrap-flow.md` for the detailed bootstrap procedure. It routes to `references/firewall-setup.md` and `references/database-setup.md` when those branches are selected.
+
+## 5. Strategy-Specific Setup
+
+Direct upload:
+- Build locally and transfer artifacts.
+- No Git operation is required on the server.
+- Read `references/direct-upload.md`.
+
+CI/CD push or pull:
+- Generate `.github/workflows/deploy.yml` from `references/ci-cd-workflows.md`.
+- Verify the first push to the configured branch will trigger deployment.
+- Pull mode requires a deploy key on the server; show the public key and wait for the user to add it to GitHub Deploy Keys before verifying clone access.
+
+After a successful direct-upload deployment, offer CI/CD setup so future `git push` can deploy automatically.
+
+## 6. DNS and SSL
+
+Before SSL, ask whether the user has a domain for the project.
+
+- If no domain, skip DNS + SSL and note it in `deploy.md`.
+- If a domain exists, check DNS before SSL.
+- Read `references/dns-setup.md` for DNS instructions.
+- Read `references/ssl-setup.md` for Let's Encrypt / certificate guidance.
+
+Always verify certificate renewal when Let's Encrypt is configured.
+
+## 7. Deployment Execution
+
+Read `references/ssh-execution-flow.md` for the full pipeline.
+
+Core sequence:
+
+1. Pre-flight and prepare release.
+2. Fetch/build or receive artifact.
+3. Stage new process on inactive blue/green port.
+4. Health-check inactive port.
+5. Switch Nginx upstream only after staged health checks pass.
+6. Verify public endpoint.
+7. Stop old process, cleanup old releases, record history.
+
+Failure rules:
+
+- If any step before traffic switch fails, stop and leave the live version unchanged.
+- If a public health check fails after traffic switch, rollback immediately.
+- Do not delete failed release logs; preserve them for debugging.
+
+## 8. Blue/Green PM2 + Nginx Invariants
+
+- Default ports: blue `3101`, green `3102`.
+- Active color is persisted in `shared/deploy-metadata.json`.
+- PM2 process name: `<project>-<app>-<color>`.
+- Nginx managed blocks include `# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY`.
+- First creation or modification of non-PrizmKit Nginx config requires user confirmation.
+- Always run `nginx -t` before reload.
+
+Read `references/nginx-blue-green.md` for config templates and traffic switch details.
+
+## 9. Rollback
+
+Rollback can be automatic or manual.
+
+Manual command:
+
+```text
+/prizmkit-deploy rollback --app <id> [--to <releaseId>]
+```
+
+Steps:
+
+1. Identify target release.
+2. Verify build artifacts exist.
+3. Start PM2 on the target release/port.
+4. Update Nginx upstream.
+5. Run `nginx -t` and reload.
+6. Run health checks.
+7. Write rollback event.
+
+If no previous release exists, state clearly that rollback is not possible.
+
+## 10. Operations Commands
+
+- `status`: PM2 list, active release, active color/port, last deploy.
+- `logs --app <id>`: recent PM2 logs for active process.
+- `restart --app <id>`: restart active PM2 process and run health checks.
+- `health --app <id>`: run configured health checks.
+- `history`: list deploy history events chronologically.
+
+Run app commands as `runtimeUser`.
+
+## 11. Secrets Management
+
+Supported storage modes:
+
+- `ask-every-time`
+- `encrypted-local`
+- `plaintext-local`
+- `user-managed-on-server-only`
+
+Rules:
+
+- `plaintext-local` must be gitignored; stop if tracked by git.
+- Server runtime secrets live in `shared/.env.production` with mode `600`.
+- Deploy history records secret presence metadata only.
+- Never record raw secret values, passphrases, decryption keys, or unsalted hashes.
+
+## 12. Existing Deployment Takeover
+
+When the target server already has deployment assets, read `references/ssh-takeover.md`.
+
+Record takeover decisions and validation results in config and history.
+
+Before modifying non-PrizmKit-managed Nginx config, ask for confirmation.
+
+## 13. Multi-App Coordination
+
+An all-app deploy creates one release group.
+
+Rules:
+
+- Pre-traffic phases must complete for all selected apps before any app switches traffic.
+- If any app fails before traffic switch, no app switches traffic.
+- If any app fails after traffic switch, default to group rollback.
+- Single-app deploys do not affect unrelated apps.
+
+## 14. History and Validation
+
+Write a deploy-history record for every deploy, rollback, takeover, validation, user-abort, failed deploy, or adapter gap.
+
+Read:
+
+- `references/deploy-history-schema.md`
+- `references/deploy-config-schema.md`
+- `references/live-validation-notes.md` when troubleshooting bootstrap or deploy failures
+
+Validation is mandatory before production deploy.

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

@@ -1,71 +1,82 @@
 ---
 name: "prizmkit-implement"
-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)"
+description: "Execute plan.md tasks with a TDD-oriented approach. Respects task ordering, checkpoints, and dependencies for Fast path or Full path change artifacts. Reads Prizm docs before editing; when relevant L2 docs are missing, falls back to target source files and lets /prizmkit-retrospective create L2 later if needed. 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` 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)
+- Fast path or Full path has a `plan.md` with unchecked tasks
+- User says "implement", "build", "code it", "start coding", "develop", or "execute"
 
 ### When NOT to Use
-- No plan.md exists — run /prizmkit-plan first
-- All tasks in plan.md are already checked off — nothing to implement
-- Trivial one-line changes (typo, config tweak) — edit directly without the full workflow
-- Design/planning phase — use /prizmkit-plan to produce spec and plan first
+- No `plan.md` exists and the task is not a Direct edit — run `/prizmkit-plan` first
+- All tasks in `plan.md` are checked off
+- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
+- User is still asking for design/planning rather than implementation
 
-**PRECONDITION:**
+## Preconditions
 
 | 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` |
+| `plan.md` with Tasks section | File exists and has unchecked tasks | Run `/prizmkit-plan` |
+| `spec.md` | File exists in same artifact directory | 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. When invoked as a handoff step in a skill chain, reuse the `artifact_dir` from the previous skill rather than re-detecting — re-detection can resolve to a different feature's directory in a multi-task workspace.
-
-## Input
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, auto-detect per precondition above. |
+Artifact directory: accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks. When invoked as a handoff step, reuse the previous skill's `artifact_dir`; re-detection can select the wrong change artifact in a multi-task workspace.
 
 ## 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 `.prizmkit/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).
-3. **Dev rules** (if configured): Check `.prizmkit/prizm-docs/root.prizm` for a `RULES:` line — if present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If a referenced file does not exist, skip it silently and continue. These define per-layer conventions (frameworks, naming, patterns, state management, etc.) that AI must follow when generating code for that layer. Apply these rules during implementation — if a rule conflicts with what plan.md describes, call it out and ask the user.
+1. **Task context**: read `plan.md` and `spec.md`. If companion documents exist in the artifact directory, read only those relevant to the change.
+2. **Architecture context**:
+   - Read `.prizmkit/prizm-docs/root.prizm`.
+   - Read relevant L1 docs for affected modules.
+   - Read relevant L2 docs when they exist, especially INTERFACES, TRAPS, and DECISIONS.
+   - If a relevant L2 doc does not exist, read the target source files as fallback and note that no L2 was available. Do not stop implementation only because L2 is missing; `/prizmkit-retrospective` can create L2 after the change if durable detail exists.
+3. **Dev rules**: if root Prizm docs reference `.prizmkit/rules/<layer>-rules.md`, read the relevant rule files. If a referenced rule file is missing, skip it and continue.
 
-> `.prizmkit/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.
+If a dev rule conflicts with `plan.md`, call out the conflict and ask the user unless the plan clearly supersedes the rule.
 
 ## 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.
-   - **Internal ID hygiene**: Do not place PrizmKit feature/bug/refactor IDs (`F-001`, `B-001`, `R-001`), task IDs, session IDs, run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy. Translate internal references into durable product/domain language before writing memory docs, tests, or UI copy.
-   - **Cover three paths for each function**: happy path (valid inputs producing expected behavior), edge cases (boundary values specific to the parameter type and domain — e.g., zero/min/max for numeric, empty collection, boundary index), and error conditions (inputs that should trigger error handling). Determine edge cases from the function's parameter types and domain logic, not from a fixed checklist. If a function has no edge or error paths, don't force them.
-   - **No redundant tests**: Check if a test for this behavior already exists before writing. Each test must verify a uniquely different code path — don't write multiple tests that exercise the same logic.
-   - **Test your own code only**: Don't test framework behavior, third-party library internals, or language built-ins. For library calls, test the integration point (correct parameters passed, return value correctly handled), not the library itself.
-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.
+For each unchecked task in `plan.md`, in order:
+
+1. Confirm relevant context for the target files is loaded: L1, L2 when present, or source fallback when L2 is absent.
+2. Apply TDD where applicable:
+   - Write or update a failing test first for behavior changes.
+   - For UI-only, docs, configuration, or mechanical refactors where test-first does not apply, use the smallest meaningful verification instead.
+3. Follow internal ID hygiene: do not place PrizmKit feature/bug/refactor IDs, task IDs, session/run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy.
+4. Cover relevant paths for changed logic:
+   - happy path
+   - domain-specific edge cases
+   - error conditions
+   Do not force meaningless edge/error tests when the function has none.
+5. Avoid redundant tests. Check existing coverage before adding a new test; each new test should exercise a distinct behavior or boundary.
+6. Test your own code and integration points, not framework internals, third-party library internals, or language built-ins.
+7. Mark the task as `[x]` immediately after completion. Immediate marking makes interrupted sessions resumable.
+8. Respect task semantics:
+   - Sequential tasks stop on failure when later tasks depend on them.
+   - `[P]` tasks may run in parallel within the same safe group.
+   - `CP:` checkpoint tasks require build/tests/verification specified by the plan before continuing.
+9. After all tasks complete, run the verification appropriate to the chosen path and risk. Full test orchestration via `/prizmkit-test` is risk-triggered, not mandatory for every change.
 
 ## 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
+If a session is interrupted:
 
-**HANDOFF:** `/prizmkit-code-review`
+- Completed tasks should already be marked `[x]`.
+- Re-run `/prizmkit-implement`; it resumes from the first unchecked task.
+- If partially edited files exist without a completed task marker, inspect the diff and either finish the task or revert incomplete work before continuing.
 
 ## Output
 
-- Code files created/modified as specified in plan.md Tasks section
-- `plan.md` Tasks section updated with completion markers `[x]`
-- Implementation summary output to conversation
+- Code files created/modified as specified in `plan.md`
+- `plan.md` Tasks section updated with `[x]` markers
+- Implementation summary
+- Suggested next step:
+  - Full path or review-triggered risk: `/prizmkit-code-review`
+  - Risk-triggered testing: `/prizmkit-test`
+  - Docs/durable knowledge changed: `/prizmkit-retrospective`
+  - Otherwise: `/prizmkit-committer`

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

@@ -14,8 +14,9 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 - After `npx prizmkit install` when project has no `.prizmkit/prizm-docs/`
 
 ### When NOT to Use
-- All artifacts exist and are up to date → use `/prizmkit-prizm-docs` (Update) instead if you only want to resync docs
-- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild) instead (faster, targeted)
+- All artifacts exist and are up to date → skip init; use `/prizmkit-prizm-docs` Status/Validate for health checks
+- Docs drifted outside the normal development loop (manual edits, merge, branch switch) → use `/prizmkit-prizm-docs` Update/Rebuild for repair
+- Normal development just finished and docs need syncing → use `/prizmkit-retrospective`, not init
 - User wants to start a feature on an already-initialized project → skip init, go to `/prizmkit-plan`
 
 ### Error Handling
@@ -182,7 +183,7 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
   - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
   - Generate L1 docs for top-level modules at `.prizmkit/prizm-docs/<M>.prizm` and for sub-modules at `.prizmkit/prizm-docs/<M>/<S>.prizm`
-  - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
+  - Skip L2 (lazy generation) — L2 is created later by `/prizmkit-retrospective` when a changed module has meaningful behavior or durable knowledge. During implementation, if an affected L2 is missing, `/prizmkit-implement` reads the target source files as fallback instead of blocking.
   - Do not create auxiliary `changelog.prizm`, CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths; git history is the source of change history
 
 **Phase 6: Workspace Initialization**

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

@@ -1,102 +1,117 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan tasks: natural language → spec.md & plan.md with architecture and executable tasks. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+description: "Specify and plan development tasks: natural language → change artifact with spec.md and plan.md. Works for features, bug fixes, refactors, migrations, and other non-trivial changes. Use before /prizmkit-implement when the task needs written scope, design, or executable tasks; use simplified planning for Fast path changes and full planning for high-risk or multi-module work. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
 ---
 
 # PrizmKit Plan
 
-A universal spec + plan generator. Takes a natural-language description of ANY development task (new feature, refactoring, bug fix, migration, etc.) and produces `spec.md` (WHAT/WHY) and `plan.md` (HOW) with executable tasks.
+A universal spec + plan generator. It turns a natural-language development task into a **change artifact**: `spec.md` (WHAT/WHY) and `plan.md` (HOW + Tasks).
+
+A change artifact is not feature-only. It can describe a feature, bug fix, refactor, migration, test improvement, or other scoped change.
 
 ### When to Use
-- Any non-trivial development task that benefits from written specification and planning
-- Before `/prizmkit-implement` — to create the spec + task breakdown
-- User says "specify", "plan", "new task", "I want to add...", "architect", "design", "break it down"
+- Any non-trivial development task that benefits from written scope and task breakdown
+- Before `/prizmkit-implement` when no suitable `plan.md` exists
+- Fast path changes that still need a simplified plan and resumable Tasks section
+- Full path changes involving multiple files/modules, public interfaces, data models, architecture, security, or unclear requirements
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", or "break it down"
 
 ### When NOT to Use
-- Config tweaks, typo fixes, trivial one-line changes → edit directly
-- Simple changes where the developer already knows exactly what to do and the scope is ≤10 lines in a single file
+- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
+- User explicitly asks for a one-off direct edit and the risk is low
+- A current artifact directory already has an adequate `spec.md` + `plan.md` for the requested work
+
+## Path Selection
+
+Choose the lightest planning depth that protects correctness:
+
+| Path | Planning behavior |
+|---|---|
+| Direct edit | Skip `/prizmkit-plan`; edit directly and verify the specific change. |
+| Fast path | Create a concise `spec.md` and simplified `plan.md` with a Tasks section. |
+| Full path | Create full `spec.md` and `plan.md` with architecture, risks, tests, and executable tasks. |
+
+Use Full path for high-risk, multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous work. Use Fast path for small scoped behavior changes. Explain the chosen path briefly.
 
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `description` | Yes | Natural-language description of the task |
-| `artifact_dir` | No | Directory to write spec.md + plan.md into. If omitted, auto-generates under `.prizmkit/specs/` (see Phase 0 Step 2). |
+| `artifact_dir` | No | Directory to write the change artifact into. If omitted, auto-generates under `.prizmkit/specs/` using a numbered slug. |
 
 ## Execution
 
-### Phase 0: Specify (→ spec.md)
+### Phase 0: Specify (`spec.md`)
 
-**Skip condition**: If `spec.md` already exists in the artifact directory, skip to Phase 1.
+Skip this phase if `spec.md` already exists in the artifact directory and still matches the requested change.
 
-**Steps:**
+Steps:
 
-1. Gather input: read the task description. If no description is provided and interactive session is available, ask the user; otherwise abort with an error.
+1. Gather the task description. If missing and interactive, ask the user; otherwise abort with a clear error.
 2. Determine artifact directory:
-   - If `artifact_dir` is provided → use it directly
-   - If not provided → scan `.prizmkit/specs/` for existing `###-*` directories, find highest numeric prefix, next = highest + 1 (zero-padded to 3 digits; start at `001` if empty). Create `.prizmkit/specs/###-task-slug/`
-   - Auto-generate 2-10 word task slug from description
-3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
-4. Generate `spec.md` from template (`${SKILL_DIR}/assets/spec-template.md`):
-   - Fill sections based on the task description — all sections are optional, include only what is relevant
-   - `[NEEDS CLARIFICATION]` markers for all ambiguous items
-5. **Database design detection**: If changes involve data persistence (new entities, fields, schema changes), add `## Data Model` section — scan existing schema files to extract naming conventions, ID strategy, constraint patterns. Mark uncertain decisions with `[NEEDS CLARIFICATION]`.
-6. Run quality validation : all goals have criteria? scope defined? DB conventions documented (if applicable)?
-7. **Auto-clarification**: If any `[NEEDS CLARIFICATION]` markers remain and interactive session is available, enter interactive clarification.
-   → Read `${SKILL_DIR}/references/clarify-guide.md` for question strategy and update rules.
-   If non-interactive, resolve ambiguities by choosing the most conservative option and annotating the decision.
-   Resolve all markers before proceeding to Phase 1.
-
-**Writing principles**: Focus on WHAT and WHY, never HOW. Every goal needs acceptance criteria. Scope boundaries must be explicit. Mark all genuine ambiguities — the clarification phase resolves them.
-
-**Internal ID hygiene**: PrizmKit IDs (`F-001`, `B-001`, `R-001`), task IDs (`T-100`), session IDs, run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal tracking metadata. They may appear in specs, plans, commit messages, and non-memory pipeline artifacts, but must never be written to `.prizmkit/prizm-docs/`, user-visible product copy, UI text, API responses, or expected UI strings in tests. If a behavior is scoped to the current feature, describe the product behavior without the ID.
-
-### Phase 1: Design (spec.md → plan.md)
-
-**Precondition**: `spec.md` exists in the artifact directory.
-
-**Steps:**
-
-1. Read `spec.md` from the artifact directory
-2. Load project context if not already loaded in Phase 0: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
-3. Resolve any remaining `[NEEDS CLARIFICATION]` by proposing solutions
-4. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
-   - Change approach (how the changes integrate with existing system)
-   - Component / file changes
-   - Data model changes (with **database design gate** — read ALL existing schema files, ensure new schema follows existing patterns, resolve all DB ambiguities inline before proceeding)
-   - Interface design (API endpoints, request/response formats)
-   - Testing strategy
+   - If `artifact_dir` is provided, use it directly.
+   - If omitted, scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
+   - The `.prizmkit/specs/` path is a generic change-artifact location; it is not limited to features.
+3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs. If L2 is missing for an affected module, use relevant source files as fallback context.
+4. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
+   - Focus on WHAT and WHY, not HOW.
+   - Include only relevant sections.
+   - Every goal needs acceptance criteria.
+   - Mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
+5. If changes involve persistence, add a Data Model section. Read existing schema files to learn naming conventions, ID strategy, constraints, and migration patterns.
+6. Resolve `[NEEDS CLARIFICATION]` markers:
+   - Interactive: ask targeted questions using `${SKILL_DIR}/references/clarify-guide.md`.
+   - Non-interactive: choose conservative defaults and annotate the decision.
+
+Internal ID hygiene: PrizmKit IDs, task IDs, session/run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal metadata. They may appear in change artifacts, but do not write them into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
+
+### Phase 1: Design (`plan.md`)
+
+Precondition: `spec.md` exists.
+
+Steps:
+
+1. Read `spec.md`.
+2. Load project context if not already loaded: root Prizm doc, relevant L1/L2 docs, and source fallback for missing L2 docs.
+3. Resolve any remaining clarification markers.
+4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md`:
+   - Change approach
+   - Component/file changes
+   - Data model changes and migration approach when relevant
+   - Interface/API contract design when relevant
+   - Testing strategy, using risk-triggered `/prizmkit-test` criteria
    - Risk assessment
-   - Behavior preservation strategy (if the task modifies existing behavior — include what must remain unchanged and how to verify)
-5. Cross-check: every goal in spec.md maps to plan components — unmapped goals = coverage gaps
-6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES section
+   - Behavior preservation strategy for refactors or behavior-adjacent changes
+5. Cross-check every spec goal maps to a plan component.
+6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES.
+
+### Phase 2: Task Generation
+
+1. Choose task strategy: MVP-first, incremental, or parallel. Ask in interactive mode when the choice affects execution; otherwise infer from risk and dependencies.
+2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`:
+   - Setup tasks
+   - Foundation tasks
+   - Core tasks mapped to goals or logical units
+   - Polish tasks when needed
+   - Checkpoint tasks between phases when integration risk exists
+3. Mark parallel tasks with `[P]` only when they can safely run independently.
+4. Run the verification checklist from `${SKILL_DIR}/references/verification-checklist.md` and fix issues before output.
 
-### Phase 2: Task Generation (plan.md → Tasks section)
+## Output
 
-1. If interactive session is available, ask user for strategy; otherwise infer automatically: MVP-first / Incremental / Parallel
-2. Append `## Tasks` section to `plan.md` using template in `${SKILL_DIR}/assets/plan-template.md`:
-   - Phases: Setup (T-001~T-009) → Foundation (T-010~T-099) → Core (T-100+) → Polish (T-900+)
-   - Each task: `- [ ] [T-NNN] [P?] [G-N?] Description — file: path/to/file`
-   - Checkpoint tasks between phases for validation
-   - Organize Core tasks by goals (G-1, G-2, ...) or by logical grouping appropriate to the task
-3. Verify consistency and coverage → read `${SKILL_DIR}/references/verification-checklist.md` and run all checks. Fix any issues inline before output.
-4. Output: `plan.md` path, summary of design decisions, task count.
+| Directory | Files |
+|---|---|
+| `artifact_dir` or auto-generated `.prizmkit/specs/###-slug/` | `spec.md` + `plan.md` |
+
+Report:
+- artifact directory
+- chosen path: Fast path or Full path
+- key decisions
+- task count and checkpoint summary
 
 **HANDOFF:** `/prizmkit-implement`
 
 ## Examples
 
 Read `${SKILL_DIR}/references/examples.md` for worked examples of feature, refactoring, and bug fix planning.
-
-## References
-
-- Spec template: `${SKILL_DIR}/assets/spec-template.md`
-- Plan template: `${SKILL_DIR}/assets/plan-template.md`
-- Clarification guide: `${SKILL_DIR}/references/clarify-guide.md`
-- Verification checklist: `${SKILL_DIR}/references/verification-checklist.md`
-
-## Output
-
-| Directory | Files |
-|---|---|
-| `artifact_dir` (provided or auto-generated `.prizmkit/specs/###-slug/`) | `spec.md` + `plan.md` |