@dedesfr/prompter 0.8.5 → 0.8.8

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # CHANGELOG
 
+## [0.8.8] - 2026-04-10
+
+### 🗑️ Removed
+- **skill-creator Agents**: Removed complex agent infrastructure for skill evaluation
+  - Deleted analyzer, comparator, and grader agent definitions
+  - Simplified skill-creator workflow by removing advanced evaluation agents
+- **Evaluation Infrastructure**: Removed benchmark and evaluation tooling
+  - Deleted eval-viewer HTML application and visualization components
+  - Removed benchmark aggregation and report generation scripts
+  - Removed skill evaluation loop and description optimization scripts
+  - Removed JSON schema references for evaluation data structures
+- **Utility Scripts**: Removed support tools and helper modules
+  - Deleted packaging, validation, improvement, and utility scripts
+  - Cleaned up skill-creator Python script dependencies
+
+### 🔄 Changed
+- **skill-creator Skill**: Streamlined to focus on core skill creation workflow
+  - Removed evaluation and benchmarking components
+  - Simplified to essential skill creation and documentation guidance
+
+## [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.8');
 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.8",
     "description": "Enhance prompts directly in your AI coding workflow",
     "type": "module",
     "main": "dist/index.js",

package/skills/design-md/README.md

@@ -0,0 +1,34 @@
+# Stitch Design System Documentation Skill
+
+## Install
+
+```bash
+npx skills add google-labs-code/stitch-skills --skill design-md --global
+```
+
+## Example Prompt
+
+```text
+Analyze my Furniture Collection project's Home screen and generate a comprehensive DESIGN.md file documenting the design system.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, workflow, and reference materials.
+
+```text
+design-md/
+├── SKILL.md           — Core instructions & workflow
+├── examples/          — Sample DESIGN.md outputs
+└── README.md          — This file
+```
+
+## How it Works
+
+When activated, the agent follows a structured design analysis pipeline:
+
+1. **Retrieval**: Uses the Stitch MCP Server to fetch project screens, HTML code, and design metadata.
+2. **Extraction**: Identifies design tokens including colors, typography, spacing, and component patterns.
+3. **Translation**: Converts technical CSS/Tailwind values into descriptive, natural design language.
+4. **Synthesis**: Generates a comprehensive DESIGN.md following the semantic design system format.
+5. **Alignment**: Ensures output follows Stitch Effective Prompting Guide principles for optimal screen generation.

package/skills/design-md/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: design-md
+description: Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
+allowed-tools:
+  - "stitch*:*"
+  - "Read"
+  - "Write"
+  - "web_fetch"
+---
+
+# Stitch DESIGN.md Skill
+
+You are an expert Design Systems Lead. Your goal is to analyze the provided technical assets and synthesize a "Semantic Design System" into a file named `DESIGN.md`.
+
+## Overview
+
+This skill helps you create `DESIGN.md` files that serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Prerequisites
+
+- Access to the Stitch MCP Server
+- A Stitch project with at least one designed screen
+- Access to the Stitch Effective Prompting Guide: https://stitch.withgoogle.com/docs/learn/prompting/
+
+## The Goal
+
+The `DESIGN.md` file will serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with the existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Retrieval and Networking
+
+To analyze a Stitch project, you must retrieve screen metadata and design assets using the Stitch MCP Server tools:
+
+1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `mcp_stitch:`) for all subsequent calls.
+
+2. **Project lookup** (if Project ID is not provided):
+   - Call `[prefix]:list_projects` with `filter: "view=owned"` to retrieve all user projects
+   - Identify the target project by title or URL pattern
+   - Extract the Project ID from the `name` field (e.g., `projects/13534454087919359824`)
+
+3. **Screen lookup** (if Screen ID is not provided):
+   - Call `[prefix]:list_screens` with the `projectId` (just the numeric ID, not the full path)
+   - Review screen titles to identify the target screen (e.g., "Home", "Landing Page")
+   - Extract the Screen ID from the screen's `name` field
+
+4. **Metadata fetch**: 
+   - Call `[prefix]:get_screen` with both `projectId` and `screenId` (both as numeric IDs only)
+   - This returns the complete screen object including:
+     - `screenshot.downloadUrl` - Visual reference of the design
+     - `htmlCode.downloadUrl` - Full HTML/CSS source code
+     - `width`, `height`, `deviceType` - Screen dimensions and target platform
+     - Project metadata including `designTheme` with color and style information
+
+5. **Asset download**:
+   - Use `web_fetch` or `read_url_content` to download the HTML code from `htmlCode.downloadUrl`
+   - Optionally download the screenshot from `screenshot.downloadUrl` for visual reference
+   - Parse the HTML to extract Tailwind classes, custom CSS, and component patterns
+
+6. **Project metadata extraction**:
+   - Call `[prefix]:get_project` with the project `name` (full path: `projects/{id}`) to get:
+     - `designTheme` object with color mode, fonts, roundness, custom colors
+     - Project-level design guidelines and descriptions
+     - Device type preferences and layout principles
+
+## Analysis & Synthesis Instructions
+
+### 1. Extract Project Identity (JSON)
+- Locate the Project Title
+- Locate the specific Project ID (e.g., from the `name` field in the JSON)
+
+### 2. Define the Atmosphere (Image/HTML)
+Evaluate the screenshot and HTML structure to capture the overall "vibe." Use evocative adjectives to describe the mood (e.g., "Airy," "Dense," "Minimalist," "Utilitarian").
+
+### 3. Map the Color Palette (Tailwind Config/JSON)
+Identify the key colors in the system. For each color, provide:
+- A descriptive, natural language name that conveys its character (e.g., "Deep Muted Teal-Navy")
+- The specific hex code in parentheses for precision (e.g., "#294056")
+- Its specific functional role (e.g., "Used for primary actions")
+
+### 4. Translate Geometry & Shape (CSS/Tailwind)
+Convert technical `border-radius` and layout values into physical descriptions:
+- Describe `rounded-full` as "Pill-shaped"
+- Describe `rounded-lg` as "Subtly rounded corners"
+- Describe `rounded-none` as "Sharp, squared-off edges"
+
+### 5. Describe Depth & Elevation
+Explain how the UI handles layers. Describe the presence and quality of shadows (e.g., "Flat," "Whisper-soft diffused shadows," or "Heavy, high-contrast drop shadows").
+
+## Output Guidelines
+
+- **Language:** Use descriptive design terminology and natural language exclusively
+- **Format:** Generate a clean Markdown file following the structure below
+- **Precision:** Include exact hex codes for colors while using descriptive names
+- **Context:** Explain the "why" behind design decisions, not just the "what"
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [Insert Project ID Here]
+
+## 1. Visual Theme & Atmosphere
+(Description of the mood, density, and aesthetic philosophy.)
+
+## 2. Color Palette & Roles
+(List colors by Descriptive Name + Hex Code + Functional Role.)
+
+## 3. Typography Rules
+(Description of font family, weight usage for headers vs. body, and letter-spacing character.)
+
+## 4. Component Stylings
+* **Buttons:** (Shape description, color assignment, behavior).
+* **Cards/Containers:** (Corner roundness description, background color, shadow depth).
+* **Inputs/Forms:** (Stroke style, background).
+
+## 5. Layout Principles
+(Description of whitespace strategy, margins, and grid alignment.)
+```
+
+## Usage Example
+
+To use this skill for the Furniture Collection project:
+
+1. **Retrieve project information:**
+   ```
+   Use the Stitch MCP Server to get the Furniture Collection project
+   ```
+
+2. **Get the Home page screen details:**
+   ```
+   Retrieve the Home page screen's code, image, and screen object information
+   ```
+
+3. **Reference best practices:**
+   ```
+   Review the Stitch Effective Prompting Guide at:
+   https://stitch.withgoogle.com/docs/learn/prompting/
+   ```
+
+4. **Analyze and synthesize:**
+   - Extract all relevant design tokens from the screen
+   - Translate technical values into descriptive language
+   - Organize information according to the DESIGN.md structure
+
+5. **Generate the file:**
+   - Create `DESIGN.md` in the project directory
+   - Follow the prescribed format exactly
+   - Ensure all color codes are accurate
+   - Use evocative, designer-friendly language
+
+## Best Practices
+
+- **Be Descriptive:** Avoid generic terms like "blue" or "rounded." Use "Ocean-deep Cerulean (#0077B6)" or "Gently curved edges"
+- **Be Functional:** Always explain what each design element is used for
+- **Be Consistent:** Use the same terminology throughout the document
+- **Be Visual:** Help readers visualize the design through your descriptions
+- **Be Precise:** Include exact values (hex codes, pixel values) in parentheses after natural language descriptions
+
+## Tips for Success
+
+1. **Start with the big picture:** Understand the overall aesthetic before diving into details
+2. **Look for patterns:** Identify consistent spacing, sizing, and styling patterns
+3. **Think semantically:** Name colors by their purpose, not just their appearance
+4. **Consider hierarchy:** Document how visual weight and importance are communicated
+5. **Reference the guide:** Use language and patterns from the Stitch Effective Prompting Guide
+
+## Common Pitfalls to Avoid
+
+- ❌ Using technical jargon without translation (e.g., "rounded-xl" instead of "generously rounded corners")
+- ❌ Omitting color codes or using only descriptive names
+- ❌ Forgetting to explain functional roles of design elements
+- ❌ Being too vague in atmosphere descriptions
+- ❌ Ignoring subtle design details like shadows or spacing patterns