prizmkit 1.1.78 → 1.1.79

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

@@ -0,0 +1,46 @@
+# Database Setup
+
+Read this file when Discovery detected a database driver and the user wants AI-assisted database installation on the server.
+
+## Entry condition
+
+During Discovery Step 1 (Project Detection), database drivers were already scanned. If a driver was detected, ask after bootstrap tools are installed:
+
+> "检测到项目使用了 <PostgreSQL/MySQL/Redis>，需要帮你在服务器上安装配置吗？"
+> - **需要** → 继续数据库安装
+> - **不需要** → 跳过，记录到 deploy.md，标注"数据库需用户自行配置"
+
+## PostgreSQL setup
+
+```
+apt-get install -y postgresql postgresql-contrib
+sudo -u postgres psql -c "CREATE DATABASE <project>;"
+sudo -u postgres psql -c "CREATE USER <project> WITH PASSWORD '<random-password>';"
+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 已安装，连接信息已记录到 `.prizmkit/deploy/secrets.local.json`（不提交到 git）".
+
+## MySQL setup (future)
+
+Similar flow. Not implemented in first version — if project uses MySQL, direct user to documentation fallback.
+
+## Redis setup
+
+```
+apt-get install -y redis-server
+redis-cli CONFIG SET requirepass "<random-password>"
+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`.
+
+## 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).
+- 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-windows/prizmkit-deploy/references/deploy-config-schema.md

@@ -0,0 +1,148 @@
+# deploy.config.json Schema
+
+This file is the machine-readable deployment configuration. Always read it before executing any deploy operation.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "project": "project-name",
+  "deploymentMode": "ssh",
+  "deployStrategy": "direct-upload|ci-cd-push|ci-cd-pull",
+  "defaults": { ... },
+  "environments": { ... },
+  "servers": [ ... ],
+  "repository": { ... },
+  "apps": [ ... ],
+  "nginx": { ... },
+  "env": { ... }
+}
+```
+
+## defaults
+
+```json
+{
+  "releaseRetention": 5,
+  "credentialMode": "ai-assisted|user-managed",
+  "secretStorage": "ask-every-time|encrypted-local|plaintext-local|user-managed-on-server-only",
+  "rollbackOnFailure": true,
+  "headlessDefaultEnvironment": "test"
+}
+```
+
+## environments
+
+Keyed by environment name. Each entry:
+```json
+{
+  "dev": {
+    "server": "server-id",
+    "allowHeadless": true,
+    "confirmBeforeDeploy": false
+  }
+}
+```
+
+## servers
+
+Array of server objects:
+```json
+{
+  "id": "prod-1",
+  "host": "IP or hostname",
+  "port": 22,
+  "bootstrapUser": "root",
+  "runtimeUser": "deploy",
+  "roles": ["web"],
+  "validated": {
+    "ssh": true|false,
+    "bootstrap": true|false,
+    "runtimeUser": true|false,
+    "tools": {
+      "node": "version",
+      "npm": "version",
+      "pm2": "version",
+      "nginx": "version",
+      "git": "version"
+    },
+    "directories": true|false,
+    "deployKey": true|false
+  }
+}
+```
+
+## repository
+
+```json
+{
+  "url": "git@github.com:owner/repo.git",
+  "branch": "master",
+  "auth": "deploy-key|ssh-agent|token",
+  "validated": {
+    "clone": true|false
+  }
+}
+```
+
+## apps
+
+Array of app objects:
+```json
+{
+  "id": "web",
+  "path": ".",
+  "runtime": "pm2",
+  "packageManager": "npm",
+  "installCommand": "npm ci",
+  "buildCommand": "npm run build",
+  "startCommand": "npm run start",
+  "ports": {
+    "blue": 3101,
+    "green": 3102
+  },
+  "healthChecks": [
+    { "name": "home", "url": "/", "expectedStatus": [200] },
+    { "name": "login", "url": "/login", "expectedStatus": [200, 302] }
+  ],
+  "activeColor": "blue",
+  "pm2Process": "prizm-ideas-blue"
+}
+```
+
+## nginx
+
+```json
+{
+  "enabled": true,
+  "managed": true,
+  "firstChangeRequiresConfirmation": true,
+  "domain": null,
+  "ipFallback": true,
+  "currentUpstream": "127.0.0.1:3101"
+}
+```
+
+## env
+
+```json
+{
+  "strategy": "ai-assisted|user-managed",
+  "required": ["VAR_NAME"],
+  "secrets": ["SECRET_NAME"],
+  "validated": {
+    "allRequiredPresent": true|false
+  }
+}
+```
+
+## Validation Rules
+
+- `version` must be present (always 1 for first version)
+- `servers` must have at least one entry with host and bootstrapUser
+- `repository.url` must be present
+- `apps` must have at least one entry
+- `apps[*].ports.blue` and `apps[*].ports.green` must differ
+- `apps[*].healthChecks` should have at least one entry
+- Environment referenced in `environments` must have a matching server in `servers`

package/bundled/skills-windows/prizmkit-deploy/references/deploy-history-schema.md

@@ -0,0 +1,62 @@
+# Deploy History Record Schema
+
+Each event in `.prizmkit/deploy/deploy-history/<id>.json` follows this schema:
+
+```json
+{
+  "eventId": "<releaseId or event id>",
+  "eventType": "deploy|rollback|status|validation|failed-deploy|user-aborted|takeover|adapter-gap",
+  "timestamp": "<ISO 8601>",
+  "serverId": "<server id from deploy.config.json>",
+  "appIds": ["<app ids involved>"],
+  "branch": "<git branch>",
+  "commitSha": "<full or short commit SHA>",
+  "releasePath": "<full server path, e.g. /var/www/prizm-ideas/releases/20260430-22783a3>",
+  "previousReleasePath": "<previous release path or null for first deploy>",
+  "targetPort": 3101,
+  "targetColor": "blue|green",
+  "previousPort": 3102,
+  "phases": {
+    "preflight": "success|failed|skipped",
+    "prepareRelease": "success|failed|skipped",
+    "fetchCode": "success|failed|skipped",
+    "installDependencies": "success|failed|skipped",
+    "build": "success|failed|skipped",
+    "stageRuntime": "success|failed|skipped",
+    "healthCheck": "success|failed|skipped",
+    "switchTraffic": "success|failed|skipped",
+    "verifyLive": "success|failed|skipped",
+    "cleanupOldReleases": "success|failed|skipped",
+    "recordHistory": "success|failed|skipped"
+  },
+  "healthCheckResults": [
+    {
+      "name": "home",
+      "url": "/",
+      "expected": [200],
+      "actual": 200,
+      "pass": true
+    }
+  ],
+  "rollbackResult": null,
+  "logPath": "<server log path>",
+  "operatorMode": "ai-assisted|user-managed",
+  "notes": "<human-readable summary of what happened>"
+}
+```
+
+## Field Notes
+
+- `eventId`: Use `<releaseId>` for deploy events, `<releaseId>-rollback` for rollbacks.
+- `eventType`: Use `failed-deploy` when deploy fails before traffic switch, `deploy` when it succeeds. Use `adapter-gap` when no adapter exists for the detected project type or target — include `detectedProjectType`, `missingAdapter`, and `fallbackOutput` in the record.
+- `phases`: Only include phases that were attempted. Skip phases that were never reached.
+- `healthCheckResults`: Include all configured health checks. `pass` = actual status matches one of the expected status codes.
+- `rollbackResult`: `null` for non-rollback events, `"success"` or `"failed"` for rollbacks.
+- `notes`: Keep concise but include any anomalies or manual interventions.
+
+## What NOT to record
+
+- Raw secret values or API keys — never.
+- Unsalted hashes of secret values — inferable with rainbow tables.
+- Passphrases or decryption keys — even if hashed.
+- Full environment variable values — presence metadata only (e.g., `{"SUPABASE_KEY": {"present": true}}`).

package/bundled/skills-windows/prizmkit-deploy/references/deployment-modes.md

@@ -0,0 +1,50 @@
+# Deployment Mode Details
+
+Read this file when the user needs a detailed comparison of deployment modes during mode selection. SKILL.md contains the routing logic; this file has the full descriptions.
+
+## Mode A — Direct Upload
+
+1. Local build on the user's machine.
+2. SCP built output + `node_modules` + `.env.production` to server.
+3. PM2 start → health check → Nginx switch.
+4. After success: offer to upgrade to CI/CD.
+5. Bypasses: deploy key, git clone on server, server-side build.
+
+Best for: first-time deployment, getting something live fast, low-spec servers.
+
+## Mode B1 — CI/CD Push
+
+1. Generate `.github/workflows/deploy.yml`: checkout → install → build → SCP tarball → SSH restart.
+2. Add GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, `SSH_PORT`.
+3. First deploy triggered by push to configured branch.
+4. Server only needs Node.js runtime + PM2 — no git, no build tools needed.
+5. GitHub Actions runner handles the heavy lifting.
+
+Best for: low-spec servers, heavy build processes, projects with large dependencies.
+
+## Mode B2 — CI/CD Pull
+
+1. Configure deploy key on server → add to GitHub.
+2. Generate `.github/workflows/deploy.yml`: triggers SSH command on server.
+3. Server-side deploy script: `git pull` → install → build → PM2 restart → health check.
+4. Server needs full build toolchain (Node.js, npm, git).
+5. Simpler workflow file, heavier server load.
+
+Best for: simple setup, servers with sufficient CPU/RAM, projects where build is fast.
+
+## Comparison
+
+| 对比 | Push 模式 | Pull 模式 |
+|------|----------|----------|
+| 构建位置 | GitHub Actions runner | 服务器本地 |
+| 服务器压力 | 低（只运行应用） | 高（编译+运行） |
+| 配置复杂度 | 中（需 SCP 传产物） | 低（只需 SSH 触发脚本） |
+| 适合场景 | 服务器配置低、编译重 | 部署简单优先、服务器性能充裕 |
+| Deploy Key 需要 | 不需要 | 需要 |
+| 产物传输 | SCP tarball | git pull（仅增量） |
+
+## Common ground between all modes
+
+- Same PM2 + Nginx blue/green strategy.
+- Same health check and traffic switch procedure.
+- Same ops commands (status/logs/restart/rollback).

package/bundled/skills-windows/prizmkit-deploy/references/direct-upload.md

@@ -0,0 +1,26 @@
+# Direct Upload Deployment
+
+Read this file when `deployStrategy` is `"direct-upload"`. The AI handles the build locally and transfers built artifacts to the server. No Git operations on the server.
+
+## Build phase (local)
+
+1. Run `<buildCommand>` locally (e.g., `npm run build`) in the project root.
+2. Identify the build output directory: `.next/` for Next.js, `dist/` for Vite, `build/` for CRA.
+3. Prepare a deployment tarball containing: build output + `node_modules/` + `package.json` + `package-lock.json` + any runtime config files.
+
+## Transfer phase (SCP)
+
+```powershell
+scp.exe -P <port> deploy-<releaseId>.tar.gz <runtimeUser>@<host>:/var/www/<project>/releases/
+ssh.exe <runtimeUser>@<host> "cd /var/www/<project>/releases && mkdir <releaseId> && tar xzf deploy-<releaseId>.tar.gz -C <releaseId>"
+```
+
+## Server-side setup
+
+1. Copy `.env.production` from `shared/` into the release directory (or SCP it alongside the tarball if first deploy).
+2. No `npm install` needed — `node_modules` was transferred directly.
+3. Start PM2 on the inactive port. Health checks and traffic switch follow the standard flow (Groups 3-5 in SKILL.md).
+
+## Why transfer node_modules
+
+Direct upload is optimized for "fast first deploy." Re-running `npm ci` on a low-spec server can be slow. Transferring pre-built artifacts means the server only needs to run the app.

package/bundled/skills-windows/prizmkit-deploy/references/dns-setup.md

@@ -0,0 +1,42 @@
+# DNS Setup Guidance
+
+Read this file when the user has a domain for their project but DNS is not yet pointing to the server.
+
+## Step 1 — Check DNS resolution
+
+```powershell
+Resolve-DnsName <domain> -Type A | Where-Object { $_.QueryType -eq 'A' } | Select-Object -ExpandProperty IPAddress
+```
+
+If it resolves to the server IP: DNS is already configured, proceed to SSL (`references/ssl-setup.md`).
+If not: continue below.
+
+## Step 2 — DNS setup guidance
+
+```
+域名 <example.com> 还未指向服务器 <服务器IP>。
+
+请在 DNS 服务商（如阿里云、Cloudflare、Namecheap）添加以下记录：
+
+  Type:  A
+  Name:  @
+  Value: <服务器IP>
+  TTL:   600
+
+如果要同时支持 www 子域名：
+  Type:  A
+  Name:  www
+  Value: <服务器IP>
+
+配置完成后回复"好了"，我继续检查并配 SSL 证书。
+```
+
+## Step 3 — Verify after user confirmation
+
+- Re-run `Resolve-DnsName <domain> -Type A` to confirm resolution.
+- If still not resolved: warn about DNS propagation delay (can take up to 48 hours, usually 5-30 minutes). Offer to wait or continue without SSL for now.
+- Once confirmed: proceed to SSL (`references/ssl-setup.md`).
+
+## Edge case — IP-only deployment
+
+If user has no domain: skip DNS + SSL sections. Generate a note in deploy.md: "项目通过 IP 访问，未配置域名和 HTTPS。建议购买域名后运行 `/prizmkit-deploy setup-ssl`。"

package/bundled/skills-windows/prizmkit-deploy/references/docker-deploy.md

@@ -0,0 +1,31 @@
+# Docker Deployment Path
+
+Guided deployment when a `Dockerfile` or `docker-compose.yml` is detected, or the user requests Docker deployment.
+
+## Detect and Configure
+
+1. Read `Dockerfile` — extract base image, exposed ports, build steps.
+2. Read `docker-compose.yml` if present — extract services, volumes, environment, ports.
+3. Identify image name: from compose project name or repo directory name.
+4. Identify port mappings: from `EXPOSE`, `ports:` in compose, or ask the user.
+
+## Build and Deploy
+
+1. Build: `docker build -t <project>:<releaseId> .` or `docker compose build`.
+2. Check for running containers with the same name: `docker ps -a --filter name=<project>`.
+3. If a previous container exists:
+   - For blue/green on a server with Nginx: start new container on different port, health check, switch upstream.
+   - For single-container setup: stop old, start new — warn about brief downtime.
+4. Start: `docker run -d --name <project>-<releaseId> -p <port>:<port> <project>:<releaseId>` or `docker compose up -d`.
+5. Health check the new container.
+6. Write deploy-history event.
+
+## Operations
+
+| Command | Docker CLI |
+|---------|-----------|
+| status | `docker ps --filter name=<project>` |
+| logs | `docker logs <container-name> --tail 100` |
+| restart | `docker restart <container-name>` |
+| rollback | `docker stop <new-container> && docker start <old-container>` |
+| cleanup | `docker image prune -a --filter "label=project=<project>"` |

package/bundled/skills-windows/prizmkit-deploy/references/firewall-setup.md

@@ -0,0 +1,37 @@
+# Firewall Setup (UFW)
+
+Read this file when the user wants AI-assisted firewall configuration during bootstrap.
+
+## Flow
+
+1. After core tools are installed, ask the user:
+   > "是否需要帮你配置防火墙（ufw）？只开放必要的端口，提高服务器安全性。"
+
+2. If user declines: skip, record to deploy config.
+
+3. If user agrees, ask which additional ports to open (beyond SSH/HTTP/HTTPS):
+   > "默认只开放 SSH(22)、HTTP(80)、HTTPS(443)。蓝绿部署预览端口（3101/3102）要不要也开放？如果需要其他端口（如数据库远程管理），可以一起列出来。"
+
+4. Collect ports, then ask:
+   > "防火墙规则已整理好。是我直接上去改，还是你自己来？"
+   > - **A. 你帮我改** — AI 执行 ufw 命令
+   > - **B. 我自己改** — 输出规则清单，用户手工执行
+
+## Planned rules (output before executing)
+
+```
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp       # SSH
+ufw allow 80/tcp       # HTTP
+ufw allow 443/tcp      # HTTPS
+ufw allow 3101/tcp     # blue preview (user-approved)
+ufw allow 3102/tcp     # green preview (user-approved)
+ufw --force enable
+```
+
+## Rules for automatic execution
+
+- Check `ufw status` first — if rules already exist, append only missing rules, don't overwrite.
+- Never `ufw reset` unless explicitly asked, because it wipes custom rules the user may have configured manually.
+- Record a `"security-baseline"` event in deploy history with the rule list, so future sessions can detect existing configuration.

package/bundled/skills-windows/prizmkit-deploy/references/live-validation-notes.md

@@ -0,0 +1,21 @@
+# Implementation Notes from Live Validation
+
+These findings from the first PrizmKit deployment (PrizmIdeas) guide edge-case handling. Read when troubleshooting bootstrap or deploy issues.
+
+1. **Detect port conflicts before installing Nginx.** Check what's on port 80/443 and ask before stopping anything, because overwriting an existing web server without confirmation can break unrelated services.
+
+2. **Verify npm separately from node.** Minimal Node installs may not bundle npm. Run `which npm` after installing Node, because `node --version` succeeding doesn't guarantee npm is available.
+
+3. **Fix locale on bare Ubuntu.** Run `locale-gen en_US.UTF-8` early to avoid perl warnings in apt. This is safe to run unconditionally even if locale is already configured.
+
+4. **Deploy key workflow is inherently interactive.** Generate key → wait for user to add to GitHub → verify. Headless mode cannot complete this because it requires the user to paste the key into GitHub's UI.
+
+5. **`pm2 startup` needs explicit PATH.** Always use `env PATH=$PATH:/usr/bin pm2 startup ...`, because the pm2 binary may not be on root's default PATH.
+
+6. **Persist deploy metadata on server.** Write `activeColor`, `activePort`, `lastReleaseId`, `lastDeployTimestamp` to `shared/deploy-metadata.json`, because subsequent deploys and rollbacks depend on knowing the current active slot.
+
+7. **Detect first deployment.** If no `current` symlink and no PM2 process for the app, skip rollback safety checks and use blue (3101) as initial color.
+
+8. **Build-time env vars.** Copy `.env.production` before `npm run build`, not after. `NEXT_PUBLIC_*` vars are baked at build time and won't be picked up if the .env is added later.
+
+9. **Node.js version flexibility.** Default to v22 LTS if v25 is unavailable. Most frameworks tolerate a minor version diff, and v22 has broader package compatibility.

package/bundled/skills-windows/prizmkit-deploy/references/nginx-blue-green.md

@@ -0,0 +1,59 @@
+# Nginx Blue/Green Configuration Template
+
+## Server Block Template
+
+```nginx
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+upstream <project>_backend {
+    server 127.0.0.1:<activePort>;
+}
+
+server {
+    listen 80 default_server;
+    server_name _;
+
+    # PrizmKit managed marker: <project>
+    location / {
+        proxy_pass http://<project>_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Traffic Switch Procedure
+
+When switching from one color to another:
+
+1. Update the `upstream` block: change `server 127.0.0.1:<oldPort>` to `server 127.0.0.1:<newPort>`
+2. Run `nginx -t` to validate syntax
+3. If syntax check passes: `systemctl reload nginx`
+4. If syntax check fails: DO NOT reload. Abort the switch. Report the error.
+
+## Managed Marker
+
+All PrizmKit-generated Nginx config must contain:
+```
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+```
+
+Before modifying any server block that lacks this marker, ask for user confirmation.
+
+## First-Time Setup
+
+- Disable default nginx site: `rm -f /etc/nginx/sites-enabled/default`
+- Create new config: `/etc/nginx/sites-available/<project>`
+- Symlink: `ln -sf /etc/nginx/sites-available/<project> /etc/nginx/sites-enabled/<project>`
+- Test: `nginx -t`
+- Reload: `systemctl reload nginx`
+
+## Rediscovery of Active Port
+
+If `deploy-metadata.json` is missing, rediscover the active upstream port from Nginx config:
+```
+grep "server 127.0.0.1:" /etc/nginx/sites-available/<project>
+```
+Then match the port against configured blue/green ports to determine active color.

package/bundled/skills-windows/prizmkit-deploy/references/ssl-setup.md

@@ -0,0 +1,56 @@
+# SSL/HTTPS Configuration (Let's Encrypt + Certbot)
+
+Read this file when DNS is confirmed pointing to the server and SSL needs to be configured.
+
+## Step 1 — Detect cloud vendor
+
+```
+# Try metadata endpoints to detect cloud vendor (run on server via SSH)
+curl -s --connect-timeout 2 http://100.100.100.200/latest/meta-data/ && echo "ALIBABA"
+curl -s --connect-timeout 2 http://metadata.tencentyun.com/latest/meta-data/ && echo "TENCENT"
+curl -s --connect-timeout 2 http://169.254.169.254/latest/meta-data/ && echo "AWS/GCP/AZURE"
+```
+Also check `/etc/hostname` for vendor patterns.
+
+## Step 2 — Choose SSL strategy
+
+- **Cloud vendor detected** → ask user:
+  > "检测到服务器运行在 <云厂商>。用哪种 SSL 方案？"
+  > - **A. Let's Encrypt 免费证书（推荐）** — 一行命令永久自动续期，最省心
+  > - **B. <云厂商> 自有证书** — 需手动下载配置，1年有效期需手动续期
+  >
+  > 选 A 我直接帮你搞定；选 B 你需要在云控制台下载证书后告诉我路径。
+- **No cloud vendor / unknown** → use certbot directly, no choice needed.
+
+## Step 3 — Certbot install & certificate request
+
+```
+# Install certbot (idempotent, on server)
+which certbot || apt-get install -y certbot python3-certbot-nginx
+
+# Request certificate
+certbot --nginx -d <domain> -d www.<domain> --non-interactive --agree-tos --email <user-email>
+```
+
+**Collect from user before running:**
+- Email address (Let's Encrypt expiry notifications)
+- Confirm domain list (e.g., `example.com, www.example.com`)
+
+## Step 4 — Verify auto-renewal
+
+```
+systemctl status certbot.timer
+certbot renew --dry-run
+```
+If timer is inactive, enable it: `systemctl enable --now certbot.timer`.
+
+## Step 5 — Record
+
+- Write SSL configuration summary to deploy.md: certificate paths, auto-renewal status, expiry date.
+- Record a `"ssl-setup"` event in deploy history.
+
+## Edge cases
+
+- **DNS not yet propagated** → certbot challenge fails. Tell user to wait and retry: `/prizmkit-deploy setup-ssl`.
+- **Existing certificate found** → check expiry date (`certbot certificates`). If expiring within 30 days, warn. Otherwise skip.
+- **Port 80/443 occupied by non-Nginx process** → report and ask how to resolve before proceeding.

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

@@ -0,0 +1,65 @@
+---
+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)"
+---
+
+# 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)
+
+**PRECONDITION:**
+
+| 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 `.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.
+
+> `.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.
+
+## 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.
+
+## 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
+
+**HANDOFF:** `/prizmkit-code-review`
+
+## 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