@dedesfr/prompter 0.8.5 → 0.8.8

package/skills/feature-planner/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: feature-planner
+description: Plan feature development on existing projects. Interview users about what they want to build, analyze the codebase to understand tech stack, patterns, and affected areas, then produce a structured implementation plan with phased tasks. Optionally scaffolds a Prompter change proposal. Use when a user wants to add a feature, make a change, or plan development work on a project that already exists.
+---
+
+# Feature Developer
+
+Interview the user about what they want to build, analyze the existing codebase, then produce a phased implementation plan with concrete tasks and file references.
+
+## Quick Start
+
+1. **DESCRIBE** -- Ask what the user wants to build and why
+2. **ANALYZE** -- Scan the codebase: structure, tech stack, patterns, existing specs
+3. **SCOPE** -- Present what's in/out of scope, identify affected files
+4. **PLAN** -- Break down into phased implementation tasks
+5. **REVIEW** -- Present the plan and iterate until approved
+6. **PROPOSAL** -- Optionally create a Prompter change proposal
+
+---
+
+## Before You Begin (REQUIRED)
+
+Before starting the interview:
+
+1. **Read `AGENTS.md`** at the project root (if it exists) to understand the tech stack, conventions, and architecture.
+2. **Read `prompter/project.md`** (if it exists) to understand project conventions.
+3. **Scan the project structure** using Glob to understand the directory layout and key files.
+
+Store what you learn -- you'll reference it when identifying affected files and patterns.
+
+---
+
+## Interactive Terminal Tool (REQUIRED)
+
+Use the `AskUserQuestion` tool for **every question** in the interview. This renders an interactive UI in the terminal.
+
+### How to Use AskUserQuestion
+
+- **Single-choice questions**: Set `multiSelect: false`. Use for yes/no, pick-one decisions.
+- **Multi-choice questions**: Set `multiSelect: true`. Use for checklists.
+- **Free-text input**: When you need the user to describe something open-ended (like the feature itself), ask as a plain message and wait for their response. Only use `AskUserQuestion` for structured choices.
+- **Keep options concise**: Labels should be 1-5 words. Add detail in the `description` field.
+
+---
+
+## Core Rules
+
+- Use `AskUserQuestion` for every structured question -- never ask choice questions as plain text.
+- Ask one question or one small grouped set at a time. Never overwhelm.
+- After every answer, acknowledge what you understood before moving on.
+- Ground every suggestion in what you observed in the codebase -- don't guess patterns.
+- If unsure about something, look at the code before asking the user.
+- Keep the interview short -- 3 to 5 questions max before producing the plan.
+
+---
+
+## Step 1: Feature Description (REQUIRED)
+
+Open with:
+
+```
+What feature or change do you want to build? Tell me:
+
+1. What it does (the user-visible behavior or system change)
+2. Why you need it (the problem it solves or value it adds)
+3. Any constraints or preferences (e.g., "must use existing auth system", "keep it simple")
+```
+
+Wait for the user's response. Summarize what you understood in 2-3 sentences.
+
+---
+
+## Step 2: Codebase Analysis (REQUIRED)
+
+After understanding the feature, **silently analyze the codebase**. Do NOT ask the user about the tech stack -- discover it yourself.
+
+### What to Analyze
+
+1. **Project structure** -- Use Glob to map the directory layout (e.g., `src/**`, `app/**`, `resources/**`)
+2. **Tech stack** -- Identify framework, language, database, styling from config files:
+   - `package.json`, `composer.json`, `Cargo.toml`, `go.mod`, `requirements.txt`
+   - Framework configs: `next.config.*`, `vite.config.*`, `artisan`, `convex/`
+   - Database: migrations folder, schema files, ORM config
+3. **Existing patterns** -- Read 2-3 files similar to what you'll need to create/modify:
+   - If adding an API endpoint, read an existing endpoint
+   - If adding a UI component, read an existing component
+   - If adding a model, read an existing model
+4. **Related code** -- Use Grep to find code related to the feature (e.g., if adding notifications, search for existing notification code)
+5. **Existing specs** -- Check `prompter/specs/` for relevant capability specs
+
+### Present Findings
+
+After analysis, present a brief summary:
+
+```
+Here's what I found in your codebase:
+
+**Stack**: [e.g., Laravel 12 + Filament + PostgreSQL + Docker]
+**Structure**: [e.g., Standard Laravel with domain-driven modules under app/Domains/]
+**Relevant patterns**:
+- [e.g., Controllers follow single-action pattern (app/Http/Controllers/)]
+- [e.g., All models use UUIDs as primary keys]
+- [e.g., Tests use Pest with factories]
+
+**Related existing code**:
+- [e.g., Similar notification system exists at app/Notifications/]
+- [e.g., No existing code for webhooks -- this is net new]
+```
+
+Then ask using `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Does this look right? Anything I missed about how your project works?",
+      "header": "Codebase Analysis",
+      "multiSelect": false,
+      "options": [
+        { "label": "Looks correct", "description": "Move on to scoping" },
+        { "label": "Need to correct something", "description": "I'll clarify what's different" }
+      ]
+    }
+  ]
+}
+```
+
+If the user corrects something, update your understanding and move on.
+
+---
+
+## Step 3: Scope & Affected Areas
+
+Based on the feature description and codebase analysis, present the scope:
+
+```
+Here's what I'd include for this feature:
+
+**In scope:**
+- [change 1]
+- [change 2]
+- [change 3]
+
+**Out of scope (can do later):**
+- [deferred item 1] -- [reason]
+
+**Files that will be affected:**
+- `path/to/file.ext` -- [what changes: new / modify / delete]
+- `path/to/file.ext` -- [what changes]
+```
+
+Then ask:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Does this scope match what you had in mind?",
+      "header": "Feature Scope",
+      "multiSelect": false,
+      "options": [
+        { "label": "Looks good", "description": "Proceed to implementation plan" },
+        { "label": "Too much", "description": "I want to trim the scope" },
+        { "label": "Missing something", "description": "I'll tell you what to add" }
+      ]
+    }
+  ]
+}
+```
+
+Iterate until the user confirms the scope.
+
+---
+
+## Step 4: Implementation Plan (REQUIRED)
+
+Produce the implementation plan using the template in `assets/implementation-plan-template.md`.
+
+### Planning Rules
+
+- **Phase tasks logically**: database/schema first, then backend logic, then frontend, then tests.
+- **Reference specific files**: Every task should mention the file path where the work happens. Use existing file paths for modifications; propose paths that follow existing conventions for new files.
+- **Follow existing patterns**: If the project uses a specific pattern (e.g., repository pattern, single-action controllers), your plan must follow it.
+- **Be concrete**: "Create UserNotification model with `user_id`, `type`, `message`, `read_at` columns" is better than "Create notification model".
+- **Include test tasks**: Always include at least one testing phase.
+- **Keep it achievable**: Aim for a plan that can be completed in a single session. If the feature is large, suggest splitting it and plan only the first part.
+
+### Present the Plan
+
+Output the filled-in implementation plan template, then ask:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Does this implementation plan look correct?",
+      "header": "Plan Review",
+      "multiSelect": false,
+      "options": [
+        { "label": "Approved", "description": "Save the plan and optionally create a proposal" },
+        { "label": "Needs changes", "description": "I'll tell you what to adjust" }
+      ]
+    }
+  ]
+}
+```
+
+Iterate if the user requests changes.
+
+---
+
+## Step 5: Save & Next Steps (REQUIRED)
+
+Once approved, save the plan based on what's available in the project.
+
+### If Prompter is installed
+
+Check whether `prompter/core/proposal.md` exists using Glob.
+
+If it exists, ask:
+
+```json
+{
+  "questions": [
+    {
+      "question": "How would you like to proceed?",
+      "header": "Next Steps",
+      "multiSelect": false,
+      "options": [
+        { "label": "Create proposal", "description": "Scaffold a Prompter change proposal from this plan" },
+        { "label": "Start building", "description": "Jump straight into implementation using this plan" },
+        { "label": "Save plan only", "description": "Save the plan to a file for later" }
+      ]
+    }
+  ]
+}
+```
+
+**If "Create proposal"**: Read `prompter/core/proposal.md` and `prompter/AGENTS.md`, then follow their instructions to scaffold a full change proposal. Use the implementation plan as context to derive:
+- `change-id` (verb-led, kebab-case)
+- `proposal.md` (why, what changes, impact)
+- `tasks.md` (from the implementation phases)
+- `design.md` (only if needed per Prompter criteria)
+- Spec deltas under `specs/[capability]/spec.md`
+
+After scaffolding, run `prompter validate <change-id> --strict --no-interactive` and fix any issues.
+
+**If "Start building"**: Begin implementing the tasks from the plan sequentially. Read the plan as your checklist and complete each task in order.
+
+**If "Save plan only"**: Write the plan to `implementation-plan.md` in the project root.
+
+### If Prompter is NOT installed
+
+Ask:
+
+```json
+{
+  "questions": [
+    {
+      "question": "What would you like to do next?",
+      "header": "Next Steps",
+      "multiSelect": false,
+      "options": [
+        { "label": "Start building", "description": "Begin implementing the tasks now" },
+        { "label": "Save plan only", "description": "Save the plan to a file for later" }
+      ]
+    }
+  ]
+}
+```
+
+**If "Start building"**: Begin implementing tasks sequentially.
+
+**If "Save plan only"**: Write the plan to `implementation-plan.md` in the project root.
+
+---
+
+## Conversation Tips
+
+### Handling Large Features
+- Suggest splitting into multiple increments.
+- Plan only the first increment in detail.
+- Note follow-up work in the "Out of scope" section.
+- Use: "This is a big feature. I'd suggest we tackle [core part] first and add [extras] after."
+
+### Handling Vague Requests
+- Look at the codebase first to infer what the user might mean.
+- If still unclear after codebase analysis, ask ONE focused clarifying question.
+- Never ask more than 2 clarifying questions before producing a draft plan -- it's easier to iterate on a concrete plan than to keep asking questions.
+
+### Handling Technical Users
+- Skip obvious explanations.
+- Focus on file paths, patterns, and concrete decisions.
+- Be direct about tradeoffs.
+
+### Handling Unfamiliar Codebases
+- Spend more time in Step 2 (analysis).
+- Read more example files to understand patterns.
+- Be explicit about assumptions: "I'm assuming X based on what I see in Y -- correct me if wrong."
+
+---
+
+## Resources
+
+- **Implementation plan template**: [implementation-plan-template.md](assets/implementation-plan-template.md) -- Structured output format for the plan

package/skills/feature-planner/assets/implementation-plan-template.md

@@ -0,0 +1,85 @@
+# Implementation Plan: [Feature Name]
+
+## Feature Overview
+[1-2 sentence summary of what is being built and why]
+
+---
+
+## Scope
+
+### In Scope
+- [ ] [Change 1]
+- [ ] [Change 2]
+- [ ] [Change 3]
+
+### Out of Scope
+- [Deferred item 1] -- [reason]
+- [Deferred item 2] -- [reason]
+
+---
+
+## Codebase Analysis
+
+### Tech Stack Detected
+| Layer | Technology |
+|-------|-----------|
+| Frontend | [e.g., Next.js, React] |
+| Backend | [e.g., Laravel, Express] |
+| Database | [e.g., PostgreSQL, MySQL] |
+| Other | [e.g., Redis, Docker] |
+
+### Affected Files & Modules
+| File / Module | Change Type | Description |
+|---------------|-------------|-------------|
+| [path/to/file] | New / Modify / Delete | [What changes] |
+
+### Existing Patterns to Follow
+- [Pattern 1 observed in codebase -- e.g., "Controllers use single-action pattern"]
+- [Pattern 2 -- e.g., "All API responses use ApiResource wrapper"]
+- [Pattern 3 -- e.g., "Tests use factories with specific naming convention"]
+
+---
+
+## Data Model Changes
+> Skip this section if no database changes are needed.
+
+### New Tables / Collections
+- **[table_name]**: [key columns/fields]
+
+### Modified Tables / Collections
+- **[table_name]**: Add [column] ([type]) -- [reason]
+
+### New Relationships
+- [Entity A] has many [Entity B]
+
+---
+
+## Implementation Tasks
+
+### Phase 1: [Foundation / Database / Setup]
+- [ ] 1.1 [Task description] -- `path/to/file`
+- [ ] 1.2 [Task description] -- `path/to/file`
+
+### Phase 2: [Core Logic / Backend]
+- [ ] 2.1 [Task description] -- `path/to/file`
+- [ ] 2.2 [Task description] -- `path/to/file`
+
+### Phase 3: [Frontend / UI]
+- [ ] 3.1 [Task description] -- `path/to/file`
+- [ ] 3.2 [Task description] -- `path/to/file`
+
+### Phase 4: [Tests / Validation]
+- [ ] 4.1 [Task description] -- `path/to/file`
+- [ ] 4.2 [Task description] -- `path/to/file`
+
+---
+
+## Dependencies & Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk 1] | [High/Med/Low] | [How to handle] |
+
+---
+
+## Notes
+- [Any additional context, edge cases, or decisions made during planning]

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` |