@dedesfr/prompter 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # CHANGELOG
 
+## [0.8.7] - 2026-04-05
+
+### ✨ Added
+- **prompter-workflow Skill**: Guide spec-driven development through Prompter's three-stage workflow
+  - Orchestrates **Propose**, **Apply**, and **Archive** stages for safe, traceable changes
+  - Includes guardrails for minimal, scoped, and verifiable implementations
+  - Integrated with `prompter/changes/` and `prompter/specs/` for change management
+  - Supports drafting spec deltas with `ADDED|MODIFIED|REMOVED|RENAMED` requirements
+
+## [0.8.6] - 2026-04-04
+
+### ✨ Added
+- **Convex Self-Hosted Deployment**: Comprehensive setup guide for self-hosted Convex deployments
+  - New `convex-setup.md` documentation covering Docker Compose setup with backend and dashboard containers
+  - Step-by-step instructions for admin key generation, schema deployment, and frontend integration
+  - Environment variable configuration for both compose stack (`.env.dev`) and CLI/frontend (`.env.local`)
+  - Troubleshooting guide and common mistakes reference
+  - Verification checklist for successful setup
+
+### 🔄 Changed
+- **project-orchestrator Skill**: Added Convex self-hosted deployment options
+  - New Convex hosting sub-choice: Cloud (managed) vs Self-Hosted (Docker, full control)
+  - Comprehensive Convex Self-Hosted Guidelines including Docker Compose setup, environment variables, and admin key generation
+  - Updated plan summary template to include Convex hosting choice and web server configuration
+  - Added Convex self-hosted setup commands to project bootstrapping examples
+  - Best practices for reserved index names and frontend URL configuration in self-hosted deployments
+  - Web Server / Reverse Proxy Guidelines: Always use Caddy for automatic HTTPS in production with zero configuration
+
 ## [0.8.5] - 2026-03-30
 
 ### ✨ Added

package/convex-setup.md

@@ -0,0 +1,403 @@
+# Convex Self-Hosted Setup Guide
+
+This document explains how to set up a self-hosted Convex deployment for this project using the official Convex self-hosted flow.
+
+It covers:
+
+- the Convex backend container
+- the Convex dashboard container
+- the frontend app connected through `VITE_CONVEX_URL`
+- the Convex CLI workflow for deploying schema and functions to a self-hosted instance
+
+## Official self-hosted flow
+
+The official Convex self-hosted documentation uses this sequence:
+
+1. start the backend and dashboard
+2. generate the admin key from the running backend container
+3. save `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY` in `.env.local`
+4. use the Convex CLI to deploy schema and functions
+5. run queries, mutations, imports, or seeds against the self-hosted backend
+
+Important:
+
+- The CLI admin key is generated from the running backend.
+- Do not assume the Docker env value `CONVEX_ADMIN_KEY` is the same value the CLI expects.
+- Do not use a random `openssl rand -hex 32` string as `CONVEX_SELF_HOSTED_ADMIN_KEY` unless Convex explicitly tells you to do so for your setup.
+
+## How this project is wired
+
+### Frontend
+
+The frontend creates the Convex React client from `VITE_CONVEX_URL`:
+
+```ts
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
+```
+
+That means:
+
+- `VITE_CONVEX_URL` must be reachable by the browser
+- the frontend needs this value during local development
+- when building the Docker image, the same value must be passed as a build argument
+
+### Deploy script
+
+This project exposes a self-hosted deploy script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "deploy:selfhosted": "convex deploy --url $CONVEX_SELF_HOSTED_URL --admin-key $CONVEX_SELF_HOSTED_ADMIN_KEY"
+  }
+}
+```
+
+## Prerequisites
+
+Install these first:
+
+- Node.js 22+
+- npm
+- Docker Desktop or Docker Engine with Compose
+- project dependencies installed with `npm install`
+
+If `node` or `npm` are missing from your `PATH`, use the Node 22 install configured for this project:
+
+```bash
+export PATH="$HOME/.nvm/versions/node/v22.17.1/bin:$PATH"
+```
+
+## Environment variables used by this project
+
+This project uses two different configuration contexts.
+
+### 1. Docker Compose environment
+
+The compose stack reads values such as:
+
+```env
+APP_ENV=dev
+WEB_PORT=8080
+CONVEX_PORT=3220
+CONVEX_DASHBOARD_PORT=3221
+CONVEX_DASHBOARD_UI_PORT=6792
+VITE_CONVEX_URL=http://localhost:3220
+CONVEX_ADMIN_KEY=replace-with-placeholder-if-needed
+CONVEX_CLOUD_ORIGIN=http://localhost:3220
+CONVEX_SITE_ORIGIN=http://localhost:6792
+```
+
+Notes:
+
+- `CONVEX_ADMIN_KEY` is passed into the backend container.
+- In practice, the Convex CLI should use the admin key generated from the running backend container.
+- `CONVEX_CLOUD_ORIGIN` should point to the backend API origin.
+- `CONVEX_SITE_ORIGIN` should point to the dashboard UI origin.
+
+### 2. Local CLI and frontend environment
+
+For local development, `.env.local` should contain:
+
+```env
+VITE_CONVEX_URL=http://localhost:3220
+CONVEX_SELF_HOSTED_URL=http://localhost:3220
+CONVEX_SELF_HOSTED_ADMIN_KEY=convex-self-hosted|generated-from-container
+```
+
+Notes:
+
+- `VITE_CONVEX_URL` is used by the frontend.
+- `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY` are used by the Convex CLI.
+- `.env.local` should not be committed.
+
+## Reference Docker Compose pattern
+
+This project uses the same high-level pattern as the official self-hosted documentation: one backend service and one dashboard service.
+
+```yaml
+services:
+  convex:
+    image: ghcr.io/get-convex/convex-backend:latest
+    ports:
+      - "${CONVEX_PORT:-3210}:3210"
+      - "${CONVEX_DASHBOARD_PORT:-3211}:3211"
+    volumes:
+      - convex-data:/convex/data
+    environment:
+      CONVEX_ADMIN_KEY: ${CONVEX_ADMIN_KEY}
+      CONVEX_CLOUD_ORIGIN: ${CONVEX_CLOUD_ORIGIN}
+      CONVEX_SITE_ORIGIN: ${CONVEX_SITE_ORIGIN}
+
+  convex-dashboard:
+    image: ghcr.io/get-convex/convex-dashboard:latest
+    depends_on:
+      convex:
+        condition: service_started
+    ports:
+      - "${CONVEX_DASHBOARD_UI_PORT:-6791}:6791"
+    environment:
+      NEXT_PUBLIC_DEPLOYMENT_URL: ${CONVEX_CLOUD_ORIGIN}
+      NEXT_PUBLIC_LOAD_MONACO_INTERNALLY: "true"
+
+volumes:
+  convex-data:
+```
+
+In this repository, the actual compose file also includes a `web` service for the frontend.
+
+## Step-by-step setup for this project
+
+### 1. Install dependencies
+
+From the repository root:
+
+```bash
+npm install
+```
+
+### 2. Create `.env.dev`
+
+Copy the development template:
+
+```bash
+cp env.dev.example .env.dev
+```
+
+Recommended local values:
+
+```env
+APP_ENV=dev
+WEB_PORT=8080
+CONVEX_PORT=3220
+CONVEX_DASHBOARD_PORT=3221
+CONVEX_DASHBOARD_UI_PORT=6792
+VITE_CONVEX_URL=http://localhost:3220
+CONVEX_ADMIN_KEY=replace-with-placeholder-if-needed
+CONVEX_CLOUD_ORIGIN=http://localhost:3220
+CONVEX_SITE_ORIGIN=http://localhost:6792
+```
+
+Important:
+
+- Treat `CONVEX_ADMIN_KEY` here as backend container configuration.
+- Do not copy this value into `CONVEX_SELF_HOSTED_ADMIN_KEY` for CLI usage unless you have confirmed it is the generated self-hosted admin key for your instance.
+
+### 3. Create `.env.local`
+
+Create the local file with the frontend URL first:
+
+```bash
+cat > .env.local <<'EOF'
+VITE_CONVEX_URL=http://localhost:3220
+EOF
+```
+
+You will append the self-hosted CLI settings after the backend starts and after you generate the real admin key.
+
+### 4. Start the Convex backend and dashboard
+
+Run:
+
+```bash
+docker compose --env-file .env.dev up -d convex convex-dashboard
+```
+
+Check status:
+
+```bash
+docker compose --env-file .env.dev ps
+```
+
+Expected result:
+
+- `convex` is running
+- `convex-dashboard` is running
+
+By default for local development in this project:
+
+- backend API is available at `http://localhost:3220`
+- backend dashboard/API port is mapped at `http://localhost:3221`
+- dashboard UI is available at `http://localhost:6792`
+
+## 5. Generate the real self-hosted admin key
+
+After the backend is running, generate the admin key from the live Convex container.
+
+Run:
+
+```bash
+docker compose --env-file .env.dev exec convex ./generate_admin_key.sh
+```
+
+Expected output format:
+
+```text
+convex-self-hosted|...
+```
+
+Copy that exact value.
+
+Now append the self-hosted CLI settings to `.env.local`:
+
+```bash
+cat >> .env.local <<'EOF'
+CONVEX_SELF_HOSTED_URL=http://localhost:3220
+CONVEX_SELF_HOSTED_ADMIN_KEY=paste-the-generated-key-here
+EOF
+```
+
+Important:
+
+- Use the generated key exactly as printed.
+- If you later recreate the backend state, generate the key again.
+- If the backend uses a persistent Docker volume, the instance credentials can persist across restarts.
+
+## 6. Deploy schema and functions
+
+With `.env.local` configured, deploy the Convex schema and functions:
+
+```bash
+npm run deploy:selfhosted
+```
+
+Equivalent raw command:
+
+```bash
+convex deploy --url "$CONVEX_SELF_HOSTED_URL" --admin-key "$CONVEX_SELF_HOSTED_ADMIN_KEY"
+```
+
+If deployment succeeds, the self-hosted backend now has the current Convex schema and functions.
+
+### Project-specific warning
+
+This repository currently has a known self-hosted compatibility issue in `convex/schema.ts`: reserved index names such as `by_id` can cause deploy to fail on self-hosted Convex.
+
+If you see an error like:
+
+```text
+IndexNameReserved: In table "agents" cannot name an index "by_id"
+```
+
+rename the reserved index names to something non-reserved such as `by_external_id`, then deploy again.
+
+## 7. Seed or run commands against the backend
+
+Once deploy succeeds, you can run Convex commands against the self-hosted instance.
+
+For this project's seed function:
+
+```bash
+npx convex run seed:run '{}' \
+  --url http://localhost:3220 \
+  --admin-key "$CONVEX_SELF_HOSTED_ADMIN_KEY"
+```
+
+You can also use other CLI commands after configuration, for example:
+
+```bash
+npx convex --help
+```
+
+## 8. Run the frontend locally
+
+Start the frontend development server:
+
+```bash
+npm run dev
+```
+
+Open the local Vite URL shown in the terminal, typically:
+
+```text
+http://localhost:5173
+```
+
+## 9. Optional Dockerized frontend
+
+If you want to run the frontend through Docker Compose too:
+
+```bash
+docker compose --env-file .env.dev up -d --build
+```
+
+This project passes `VITE_CONVEX_URL` as a Docker build argument so the Vite app can be built with the correct public backend URL.
+
+## Verification checklist
+
+- `npm install` completes successfully
+- `docker compose --env-file .env.dev up -d convex convex-dashboard` succeeds
+- `docker compose --env-file .env.dev exec convex ./generate_admin_key.sh` returns a `convex-self-hosted|...` key
+- `.env.local` contains `VITE_CONVEX_URL`, `CONVEX_SELF_HOSTED_URL`, and the generated `CONVEX_SELF_HOSTED_ADMIN_KEY`
+- `npm run deploy:selfhosted` succeeds
+- any seed or query command against the backend succeeds
+- `npm run dev` starts the frontend successfully
+- the frontend can load data from Convex
+
+## Common mistakes
+
+- using `.env.dev`'s `CONVEX_ADMIN_KEY` as the CLI admin key without generating the real self-hosted key from the container
+- using a random string as `CONVEX_SELF_HOSTED_ADMIN_KEY`
+- forgetting to deploy schema and functions before running seed commands
+- using a `VITE_CONVEX_URL` that the browser cannot reach
+- assuming changing `.env.dev` automatically updates credentials already persisted in a Docker volume
+- overlooking self-hosted restrictions such as reserved index names during deploy
+
+## Troubleshooting
+
+### `401 Unauthorized: BadAdminKey`
+
+Cause:
+
+- the CLI is using the wrong admin key
+
+Fix:
+
+1. make sure the backend is running
+2. run `docker compose --env-file .env.dev exec convex ./generate_admin_key.sh`
+3. copy the printed `convex-self-hosted|...` value into `.env.local` as `CONVEX_SELF_HOSTED_ADMIN_KEY`
+4. retry deploy or seed
+
+### `Could not find function for 'seed:run'`
+
+Cause:
+
+- deploy has not succeeded yet, so the function is not available on the backend
+
+Fix:
+
+1. resolve the deploy error first
+2. rerun `npm run deploy:selfhosted`
+3. rerun the seed command
+
+### `IndexNameReserved`
+
+Cause:
+
+- the schema defines a reserved index name such as `by_id`
+
+Fix:
+
+- rename the reserved index to a non-reserved name such as `by_external_id`
+- redeploy
+
+### Frontend fails because `VITE_CONVEX_URL` is missing
+
+Cause:
+
+- `.env.local` is missing or incomplete
+
+Fix:
+
+- recreate `.env.local`
+- restart the frontend dev server
+
+## Files in this project you can reuse as references
+
+- `package.json`
+- `docker-compose.yml`
+- `Dockerfile`
+- `env.dev.example`
+- `env.prod.example`
+- `src/providers/ConvexClientProvider.tsx`
+- `prompter/changes/add-convex-backend/guide.md`

package/dist/cli/index.js

@@ -16,7 +16,7 @@ const program = new Command();
 program
     .name('prompter')
     .description('Enhance prompts directly in your AI coding workflow')
-    .version('0.8.5');
+    .version('0.8.7');
 program
     .command('init')
     .description('Initialize Prompter in your project')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dedesfr/prompter",
-    "version": "0.8.5",
+    "version": "0.8.7",
     "description": "Enhance prompts directly in your AI coding workflow",
     "type": "module",
     "main": "dist/index.js",

package/skills/project-orchestrator/SKILL.md

@@ -263,6 +263,7 @@ After the user picks a bundle, ask ONLY the necessary sub-choices:
 **Bundle 2 sub-choices:**
 - Next.js vs React (Vite)? (Recommend Next.js if SEO matters; Vite if it's a dashboard or real-time app where SSR isn't needed)
 - No database sub-choice needed -- Convex includes a built-in document database with real-time sync.
+- **Convex hosting**: Convex Cloud (managed, easiest) vs Self-Hosted (Docker, full control)? (Recommend Convex Cloud for most projects -- zero infrastructure overhead. Recommend Self-Hosted if the user needs data sovereignty, air-gapped environments, or wants to avoid vendor lock-in.)
 
 **Bundle 3 sub-choices:**
 - MySQL vs PostgreSQL? (Same guidance as above)
@@ -290,6 +291,16 @@ Quick context: Docker makes it easy to set up identical dev environments across
 
 If unsure: Recommend based on team size and deployment target (e.g., "For a solo project deploying to a single VPS, Docker is optional. For a team or cloud deployment, I'd recommend it.").
 
+### Web Server / Reverse Proxy Guidelines
+
+When Docker is used and a web server or reverse proxy is needed (e.g., for Laravel, Express, NestJS, or a Dockerized frontend):
+
+- **Always use Caddy** as the web server and reverse proxy -- do NOT use or recommend Nginx or Apache.
+- Caddy automatically handles HTTPS (via Let's Encrypt or ZeroSSL) in production with zero extra configuration.
+- For local development, Caddy serves HTTP by default -- no certificate setup needed.
+- Add a `Caddyfile` at the project root and a `caddy` service in `docker-compose.yml`.
+- Mention Caddy in the final plan summary under the Docker/web server row and in the recommended next steps.
+
 ### Laravel + Docker Guidelines
 
 When the user chooses a Laravel stack (Bundle 3, 4, or 5) with Docker:
@@ -300,6 +311,29 @@ When the user chooses a Laravel stack (Bundle 3, 4, or 5) with Docker:
   - Any other long-running processes the project needs (e.g., scheduler via `php artisan schedule:work`)
 - Mention this in the final plan summary under the Docker row and in the recommended next steps.
 
+### Convex Self-Hosted Guidelines
+
+When the user chooses React + Convex (Bundle 2) with **self-hosted** deployment:
+
+- **Use Docker Compose** with two Convex services:
+  - `convex` — backend image `ghcr.io/get-convex/convex-backend:latest`
+  - `convex-dashboard` — dashboard image `ghcr.io/get-convex/convex-dashboard:latest`
+- **Two environment files** are required:
+  - `.env.dev` (Docker Compose config) — contains `CONVEX_PORT`, `CONVEX_DASHBOARD_PORT`, `CONVEX_DASHBOARD_UI_PORT`, `VITE_CONVEX_URL`, `CONVEX_ADMIN_KEY`, `CONVEX_CLOUD_ORIGIN`, `CONVEX_SITE_ORIGIN`
+  - `.env.local` (CLI and frontend, never committed) — contains `VITE_CONVEX_URL`, `CONVEX_SELF_HOSTED_URL`, `CONVEX_SELF_HOSTED_ADMIN_KEY`
+- **Admin key generation**: After starting the backend, generate the CLI admin key from the running container:
+  ```bash
+  docker compose --env-file .env.dev exec convex ./generate_admin_key.sh
+  ```
+  Copy the printed `convex-self-hosted|...` value into `.env.local` as `CONVEX_SELF_HOSTED_ADMIN_KEY`. Never use a random string or the Docker `CONVEX_ADMIN_KEY` value directly for CLI use.
+- **Add a deploy script** to `package.json`:
+  ```json
+  "deploy:selfhosted": "convex deploy --url $CONVEX_SELF_HOSTED_URL --admin-key $CONVEX_SELF_HOSTED_ADMIN_KEY"
+  ```
+- **Reserved index names**: Self-hosted Convex does not allow reserved index names such as `by_id`. Rename them to non-reserved names (e.g., `by_external_id`) before deploying.
+- **Frontend wiring**: The frontend reads `VITE_CONVEX_URL` at build time. Ensure this value is reachable by the browser and is passed as a Docker build argument when building the frontend image.
+- Mention this setup in the final plan summary under the Docker/Convex row and in the recommended next steps.
+
 ---
 
 ## Step 9: Deployment & Hosting

package/skills/project-orchestrator/assets/plan-summary-template.md

@@ -68,10 +68,12 @@
 | Layer | Choice | Rationale |
 |-------|--------|-----------|
 | Frontend | [e.g., Next.js] | [Why] |
-| Backend | [e.g., NestJS] | [Why] |
-| ORM / DB Layer | [e.g., Drizzle] | [Why] |
-| Database | [e.g., PostgreSQL] | [Why] |
+| Backend | [e.g., NestJS / Convex] | [Why] |
+| ORM / DB Layer | [e.g., Drizzle / Convex built-in] | [Why] |
+| Database | [e.g., PostgreSQL / Convex document DB] | [Why] |
+| Convex Hosting | [Cloud / Self-Hosted] | [Why -- only include if using Convex] |
 | Styling | [e.g., Tailwind CSS] | [Why] |
+| Web Server | [e.g., Caddy] | [Why -- include when Docker is used] |
 | Docker | Yes/No | [Why] |
 
 ---
@@ -109,6 +111,7 @@
 # [Insert the exact setup command(s) for the chosen stack]
 # React (Vite):   npm create vite@latest
 # Next.js:        npx create-next-app@latest {project_name} --yes
+# React + Convex: npm create convex@latest
 # Express:        npm install express --save
 # NestJS:         npm i -g @nestjs/cli && nest new {project_name}
 # Laravel 12:     composer create-project laravel/laravel:^12.0 {project_name}
@@ -116,7 +119,38 @@
 ```
 > Replace the above with only the command(s) matching the selected stack.
 
-### 2. Further steps
+### 2. Convex Self-Hosted Setup (only if self-hosted Convex was chosen)
+```bash
+# 1. Copy environment files
+cp env.dev.example .env.dev
+# Edit .env.dev with your port and origin values
+
+# 2. Create initial .env.local
+echo 'VITE_CONVEX_URL=http://localhost:3220' > .env.local
+
+# 3. Start Convex backend and dashboard
+docker compose --env-file .env.dev up -d convex convex-dashboard
+
+# 4. Generate the self-hosted admin key from the running container
+docker compose --env-file .env.dev exec convex ./generate_admin_key.sh
+# Copy the printed convex-self-hosted|... value
+
+# 5. Append CLI credentials to .env.local
+# CONVEX_SELF_HOSTED_URL=http://localhost:3220
+# CONVEX_SELF_HOSTED_ADMIN_KEY=convex-self-hosted|...
+
+# 6. Deploy schema and functions
+npm run deploy:selfhosted
+
+# 7. (Optional) Seed data
+npx convex run seed:run '{}' --url http://localhost:3220 --admin-key "$CONVEX_SELF_HOSTED_ADMIN_KEY"
+```
+> Notes:
+> - Do NOT use a random string as `CONVEX_SELF_HOSTED_ADMIN_KEY` -- always generate it from the container.
+> - Avoid reserved index names like `by_id` in your Convex schema -- rename them (e.g., `by_external_id`) before deploying.
+> - `VITE_CONVEX_URL` must be reachable by the browser; pass it as a Docker build argument when building the frontend image.
+
+### 3. Further steps
 - [e.g., Define database schema based on data model above]
 - [e.g., Implement authentication and user management]
 - [e.g., Build core feature X]

package/skills/prompter-workflow/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: prompter-workflow
+description: Guide spec-driven development through Prompter's three-stage workflow — creating change proposals with spec deltas, implementing approved changes, and archiving completed work. Use this skill whenever the user mentions proposals, specs, changes, plans, or asks to create/apply/archive a Prompter change. Also trigger when the user wants to add features, make breaking changes, update architecture, or plan implementation work that should go through a formal proposal process.
+---
+
+# Prompter Workflow
+
+Drive spec-driven development through three stages: **Propose**, **Apply**, and **Archive**. Each stage has guardrails to keep changes minimal, scoped, and traceable.
+
+## Before You Begin
+
+1. Search existing specs under `prompter/specs/` and active changes under `prompter/changes/` to understand current state and avoid conflicts.
+2. Search existing requirements with `rg -n "Requirement:|Scenario:" prompter/specs` before writing new ones.
+
+## Detecting Which Stage
+
+Determine which stage the user needs based on their request:
+
+| Signal | Stage |
+|--------|-------|
+| "create a proposal", "plan a change", "add a feature", "I want to spec..." | **Propose** |
+| "implement", "apply", "build this", references an existing change ID + wants code | **Apply** |
+| "archive", "mark as done", "move to archive", references a completed change | **Archive** |
+
+If unclear, default to **Propose** — it's always safer to plan first.
+
+---
+
+## Stage 1: Propose
+
+Create a change proposal with spec deltas. No code gets written here — only design documents.
+
+### Guardrails
+
+- Favor straightforward, minimal implementations first.
+- Keep changes tightly scoped to the requested outcome.
+- Identify vague or ambiguous details and ask follow-up questions before editing files.
+- Do not write any code during this stage.
+
+### Steps
+
+1. **Ground the proposal in current state.**
+   - List `prompter/changes/` to see active changes (check for conflicts).
+   - List `prompter/specs/` to see existing capabilities.
+   - Inspect related code or docs to understand current behavior.
+   - Note any gaps that require clarification from the user.
+
+2. **Choose a change ID and scaffold.**
+   - Pick a unique, verb-led, kebab-case ID (e.g., `add-two-factor-auth`, `update-payment-flow`, `remove-legacy-api`).
+   - Create the directory structure:
+     ```
+     prompter/changes/<change-id>/
+     ├── proposal.md
+     ├── tasks.md
+     ├── design.md  (only if needed — see criteria below)
+     └── specs/
+         └── <capability>/
+             └── spec.md
+     ```
+
+3. **Map the change into capabilities.**
+   - Break multi-scope efforts into distinct spec deltas with clear relationships.
+   - Prefer modifying existing specs over creating duplicates.
+   - One folder per affected capability under `specs/`.
+
+4. **Write design.md (only when needed).**
+   Create `design.md` if the solution spans multiple systems, introduces new patterns, or demands trade-off discussion. Include: Context, Goals/Non-Goals, Decisions, Risks/Trade-offs, Migration Plan, Open Questions.
+
+5. **Draft spec deltas.**
+   - Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers.
+   - Include at least one `#### Scenario:` per requirement.
+   - Use SHALL/MUST for normative requirements.
+   - Cross-reference related capabilities when relevant.
+   - For MODIFIED requirements: copy the full existing requirement, then edit. Partial deltas lose detail at archive time.
+
+6. **Draft tasks.md.**
+   - Ordered list of small, verifiable work items.
+   - Each task should deliver user-visible progress.
+   - Include validation steps (tests, tooling).
+   - Highlight dependencies or parallelizable work.
+
+### Spec Format Reference
+
+```markdown
+## ADDED Requirements
+### Requirement: Feature Name
+The system SHALL provide [capability].
+
+#### Scenario: Success case
+- **WHEN** user performs action
+- **THEN** expected result occurs
+
+## MODIFIED Requirements
+### Requirement: Existing Feature (full copy, then edit)
+...
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason**: [Why removing]
+**Migration**: [How to handle]
+```
+
+---
+
+## Stage 2: Apply
+
+Implement an approved change proposal. Work through tasks sequentially, keeping edits minimal.
+
+### Guardrails
+
+- Do not start implementation until the proposal is reviewed and approved.
+- Keep changes tightly scoped to what the proposal specifies.
+- Favor straightforward, minimal implementations.
+
+### Steps
+
+1. **Read the proposal.**
+   - Read `changes/<id>/proposal.md` to understand scope and motivation.
+   - Read `changes/<id>/design.md` (if present) for technical decisions.
+   - Read `changes/<id>/tasks.md` for the implementation checklist.
+
+2. **Implement tasks sequentially.**
+   - Work through each task in order.
+   - Keep edits minimal and focused on the requested change.
+
+3. **Confirm completion.**
+   - Verify every item in `tasks.md` is actually finished before updating statuses.
+   - Run tests and validation as specified in the tasks.
+
+4. **Update the checklist.**
+   - Mark each task `- [x]` only after all work is done.
+   - Ensure the checklist reflects reality.
+
+---
+
+## Stage 3: Archive
+
+Move a completed change to the archive and update specs.
+
+### Steps
+
+1. **Determine the change ID.**
+   - If the user specified a change ID, use it (trim whitespace).
+   - If referenced loosely (by title or summary), list `prompter/changes/` to find candidates and confirm with the user.
+
+2. **Verify the change exists and is ready.**
+   - Check `prompter/changes/<id>/` exists and is not already under `prompter/changes/archive/`.
+
+3. **Move the change to archive.**
+   - Move `prompter/changes/<id>/` to `prompter/changes/archive/YYYY-MM-DD-<id>/` (use today's date).
+   - Apply the spec deltas: for each `changes/<id>/specs/<capability>/spec.md`, merge the ADDED/MODIFIED/REMOVED requirements into the corresponding `prompter/specs/<capability>/spec.md`.
+   - Skip spec merging only for tooling-only changes that don't affect specifications.
+
+4. **Confirm archive landed.**
+   - Verify the directory moved to `prompter/changes/archive/`.
+   - Verify target specs were updated correctly.
+
+---
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| "Change must have at least one delta" | Check `changes/<id>/specs/` has `.md` files with `## ADDED\|MODIFIED\|REMOVED Requirements` headers |
+| "Requirement must have at least one scenario" | Use `#### Scenario:` format (4 hashtags, not bullets or bold) |
+| Silent scenario parsing failures | Exact format required: `#### Scenario: Name` |

package/skills/prompter-workflow/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "prompter-workflow",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to add a webhook notification system so that when a user completes an order, we fire a POST to their configured endpoint. Can you create a proposal for this?",
+      "expected_output": "Creates a change proposal under prompter/changes/add-webhook-notifications/ with proposal.md, tasks.md, and at least one spec delta under specs/ with ADDED Requirements and Scenario blocks. Runs prompter validate with --strict.",
+      "files": [],
+      "assertions": [
+        {
+          "name": "Creates proposal.md with Why section",
+          "description": "Output or created files include a proposal.md that contains a ## Why section explaining the motivation"
+        },
+        {
+          "name": "Creates tasks.md",
+          "description": "Output or created files include a tasks.md with a checklist of implementation tasks using - [ ] format"
+        },
+        {
+          "name": "Creates spec delta with ADDED Requirements",
+          "description": "A spec delta file under specs/ contains '## ADDED Requirements' header"
+        },
+        {
+          "name": "Spec delta has Scenario block",
+          "description": "The spec delta contains at least one '#### Scenario:' block (4 hashtags, not bold or bullet)"
+        },
+        {
+          "name": "Does not write implementation code",
+          "description": "The output does not contain actual code implementation (no function definitions, no API endpoint implementations) — only design documents"
+        },
+        {
+          "name": "Mentions running prompter validate",
+          "description": "The output mentions running prompter validate with --strict flag to verify the proposal"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The add-webhook-notifications proposal has been approved. Please implement it now.",
+      "expected_output": "Reads the proposal.md, design.md (if any), and tasks.md from the change directory. Works through tasks sequentially. Updates tasks.md with checkmarks when done.",
+      "files": [],
+      "assertions": [
+        {
+          "name": "Reads proposal.md before implementing",
+          "description": "Output explicitly mentions reading or referencing proposal.md before starting implementation"
+        },
+        {
+          "name": "Reads tasks.md",
+          "description": "Output explicitly mentions reading or referencing tasks.md"
+        },
+        {
+          "name": "Works through tasks sequentially",
+          "description": "Output describes completing tasks in order, not all at once or in arbitrary order"
+        },
+        {
+          "name": "Updates task checklist",
+          "description": "Output mentions updating tasks.md checkboxes (- [x]) after completion"
+        },
+        {
+          "name": "Does not skip approval gate",
+          "description": "Output does not implement before acknowledging the proposal was approved — respects the approval gate"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We shipped the webhook feature last week. Can you archive that change?",
+      "expected_output": "Runs prompter list to identify the change, confirms the ID with the user or uses it directly, runs prompter archive <id> --yes, then validates with prompter validate --strict.",
+      "files": [],
+      "assertions": [
+        {
+          "name": "Mentions running prompter list to identify change",
+          "description": "Output mentions running `prompter list` or `prompter show` to verify the change ID before archiving"
+        },
+        {
+          "name": "Uses correct archive command with --yes",
+          "description": "Output includes `prompter archive add-webhook-notifications --yes` (or similar with the correct change ID and --yes flag)"
+        },
+        {
+          "name": "Runs post-archive validation",
+          "description": "Output mentions running `prompter validate --strict` after archiving to confirm specs are consistent"
+        },
+        {
+          "name": "Does not archive blindly without ID check",
+          "description": "Output shows the agent verifying or confirming the change ID rather than immediately running the archive command"
+        }
+      ]
+    }
+  ]
+}

package/src/cli/index.ts

@@ -18,7 +18,7 @@ const program = new Command();
 program
     .name('prompter')
     .description('Enhance prompts directly in your AI coding workflow')
-    .version('0.8.5');
+    .version('0.8.7');
 
 program
     .command('init')