@dedesfr/prompter 0.9.0 → 1.0.0

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

@@ -1,159 +0,0 @@
-# Project Plan: [Project Name]
-
-## Project Overview
-[1-2 sentence summary of the project, its purpose, and target audience]
-
----
-
-## MVP Scope
-
-### In Scope
-- [ ] [Feature 1]
-- [ ] [Feature 2]
-- [ ] [Feature 3]
-
-### Out of Scope (Deferred)
-- [Deferred item 1] -- [reason]
-- [Deferred item 2] -- [reason]
-
----
-
-## User Roles
-| Role | Description | MVP? |
-|------|-------------|------|
-| [Role] | [What they do] | Yes/No |
-
----
-
-## Core Features (Prioritized)
-| # | Feature | Priority | Complexity | Notes |
-|---|---------|----------|------------|-------|
-| 1 | [Feature] | Must-have | [Low/Med/High] | [Notes] |
-| 2 | [Feature] | Must-have | [Low/Med/High] | [Notes] |
-| 3 | [Feature] | Nice-to-have | [Low/Med/High] | [Notes] |
-
----
-
-## Data Model Sketch
-
-### Core Entities
-- **[Entity 1]**: [key fields]
-- **[Entity 2]**: [key fields]
-- **[Entity 3]**: [key fields]
-
-### Key Relationships
-- [Entity A] has many [Entity B]
-- [Entity B] belongs to [Entity A]
-
----
-
-## Integrations & Services
-
-| Capability | Needed? | Service/Tool | Notes |
-|------------|---------|--------------|-------|
-| Caching | Yes/No | [e.g., Redis] | [Notes] |
-| Queues / Background Jobs | Yes/No | [e.g., Redis Queue] | [Notes] |
-| Real-Time | Yes/No | [e.g., Pusher, WebSockets] | [Notes] |
-| Full-Text Search | Yes/No | [e.g., Meilisearch] | [Notes] |
-| File Storage | Yes/No | [e.g., S3] | [Notes] |
-| Email / SMS | Yes/No | [e.g., Resend, Twilio] | [Notes] |
-| Analytics | Yes/No | [e.g., PostHog, Plausible] | [Notes] |
-| Payments | Yes/No | [e.g., Stripe] | [Notes] |
-| Third-Party | Yes/No | [e.g., social login, maps] | [Notes] |
-
----
-
-## Tech Stack
-
-| Layer | Choice | Rationale |
-|-------|--------|-----------|
-| Frontend | [e.g., Next.js] | [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] |
-| Convex Storage Backend | [SQLite / PostgreSQL -- only include if self-hosted Convex] | [Why -- SQLite for dev/hobby; Postgres for production] |
-| Styling | [e.g., Tailwind CSS] | [Why] |
-| Web Server | [e.g., Caddy] | [Why -- include when Docker is used] |
-| Docker | Yes/No | [Why] |
-
----
-
-## Deployment & Environments
-
-| Environment | Platform | URL (if known) | Notes |
-|-------------|----------|----------------|-------|
-| Development | [e.g., Local + Docker] | localhost | |
-| Staging | [e.g., Railway] | [TBD] | |
-| Production | [e.g., VPS / DigitalOcean] | [TBD] | |
-
----
-
-## Non-Functional Requirements
-
-| Requirement | Detail |
-|-------------|--------|
-| Security | [e.g., standard auth, 2FA, GDPR] |
-| Performance | [e.g., <1k users expected] |
-| SEO | [e.g., required / not required] |
-
----
-
-## Open Questions / Risks
-- [Open question or risk 1]
-- [Open question or risk 2]
-
----
-
-## Recommended Next Steps
-
-### 1. Scaffold the project
-```bash
-# [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}
-# Filament:       composer require filament/filament && php artisan filament:install --panels
-```
-> Replace the above with only the command(s) matching the selected stack.
-
-### 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]
-- [e.g., Set up CI/CD pipeline]
-- [e.g., Deploy staging environment]

package/skills/prompter-specs/SKILL.md

@@ -1,115 +0,0 @@
----
-name: prompter-specs
-description: Generate structured implementation specs from casual change requests. Analyzes the codebase first, then produces a clear specification with problem statement, current state analysis, proposed solution, files to modify, implementation details, and visual representation. Use when the user describes a desired change, improvement, or reorganization — especially in casual or vague terms — and needs a structured plan before implementation. Triggers on requests like "can you organize...", "I want to change...", "restructure this...", "clean up the...", "make it better", "plan out how to...", or any request implying a codebase change where analysis should precede coding. Also use when the user explicitly asks for a "spec", "specs mode", "implementation plan", or "analysis before coding". Even when the user's request sounds simple, if it involves modifying multiple files or making structural decisions, produce a spec first.
----
-
-# Prompter Specs
-
-Generate structured implementation specifications from casual user requests. Analyze first, spec second, implement only after approval.
-
-## Core Principle
-
-Do not jump to coding. When this skill activates, the job is to **understand the problem, analyze the current state, and produce a clear spec**. The user wants to see what will change and why before any code is written.
-
-## Workflow
-
-### 1. Understand the Request
-
-Parse what the user is asking for, even if vague or casual. Phrases like "it's too long", "make it better", "organize this", "clean it up" all carry intent — identify the core problem behind them.
-
-If the request is truly ambiguous (multiple valid interpretations), ask one focused clarifying question. Otherwise, proceed with analysis.
-
-### 2. Explore the Codebase
-
-Read the relevant files to understand the current state. Use Glob, Grep, and Read to build a complete picture. The spec must be grounded in what actually exists — never guess at file contents, counts, or structures.
-
-Look for:
-- The files and code directly related to the request
-- Existing patterns and conventions the project uses
-- Related systems that might be affected
-
-### 3. Analyze and Decide
-
-Formulate a solution based on what you found. When the user gives open-ended direction ("you decide", "figure it out", "whatever makes sense"), commit to a specific, well-reasoned approach. Present one clear recommendation — not a menu of options.
-
-If there's a genuine trade-off worth flagging, mention it briefly in Implementation Details, but still recommend one path.
-
-### 4. Write the Spec
-
-Output a structured specification using the format below. Adapt section titles and depth to fit the change — a small reorganization needs less detail than an architecture shift.
-
-### 5. Wait for Approval
-
-After presenting the spec, ask if the user wants to:
-- Proceed with implementation
-- Adjust the proposal
-- Discard and try a different approach
-
-Do not start coding until the user confirms.
-
-## Spec Format
-
-```markdown
-## Problem
-[1-3 sentences describing what's wrong or what could be better.
-Be specific — reference actual counts, names, or metrics from the codebase.]
-
-## Current [Descriptive Title]
-[Describe what exists right now. List items, show structure, reference actual
-file contents. This section proves you've actually read the code.
-Use a descriptive title that fits the context, e.g.:
-- "Current Menu Items (flat list under Master Data)"
-- "Current API Endpoints"
-- "Current File Structure"]
-
-## Proposed Solution: [Solution Title]
-[Brief description of the approach — the "what" and "why" at a high level.]
-
-### [Detail Section — titled to fit the change]
-[The detailed proposal. Use nested lists, tables, diagrams, or whatever
-format best communicates the new structure. Be specific — show exactly
-what the result looks like, not vague descriptions.]
-
-### Files to Modify
-[For each file that needs changes:]
-1. **`path/to/file`** — [What changes and why. Be specific about the
-   nature of the change, not just "update this file".]
-
-### Implementation Details
-[Technical specifics:]
-- What new fields, properties, or patterns to introduce
-- How existing code adapts to the change
-- What stays unchanged (helps the user assess risk and scope)
-- Migration or backwards-compatibility notes if applicable
-- Performance or security considerations if relevant
-
-### Visual Result
-[Where it helps, show a text-based visualization of the end result.
-Skip this section if the change doesn't benefit from visual representation.
-Good candidates: UI layouts, directory trees, data flows, table structures,
-menu hierarchies, architecture diagrams.]
-```
-
-## Guidelines
-
-### Match the Project's World
-
-Read the project before writing the spec. Use its naming conventions, file organization patterns, and existing abstractions. Reference what the codebase already supports ("The sidebar already supports nested items — we extend this pattern") rather than proposing alien patterns.
-
-### Ground Every Claim in Code
-
-The "Current State" section must contain real information from the codebase. If the user says "the menu is too long" — count the items. If they say "the API is messy" — list the actual endpoints. If they say "the tests are slow" — check what test framework and patterns exist.
-
-### Scale the Spec to the Change
-
-- **Small changes** (rename, fix layout, reorder items): Shorter spec, skip Visual Result if not needed
-- **Medium changes** (reorganize UI, refactor a module, add a feature): Full spec with all sections
-- **Large changes** (new architecture, multi-service change): Consider splitting into phases, flag dependencies between them
-
-### Call Out What Does NOT Change
-
-Explicitly state what's unaffected. "No route or controller changes needed — purely presentation layer" or "Database schema unchanged" helps the user assess blast radius and risk.
-
-### Stay Tech-Stack Agnostic
-
-This workflow applies to any project. Whether it's Laravel, React, Django, Rails, Go, Swift, or a CLI tool — adapt the spec's language and file references to match. There's no assumption about framework or language.

package/skills/prompter-workflow/SKILL.md

@@ -1,166 +0,0 @@
----
-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

@@ -1,89 +0,0 @@
-{
-  "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/skills/proposal/SKILL.md

@@ -1,28 +0,0 @@
----
-name: proposal
-description: Create a new change proposal with spec deltas
----
-
-<!-- PROMPTER:START -->
-**Guardrails**
-- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
-- Keep changes tightly scoped to the requested outcome.
-- Refer to `prompter/AGENTS.md` (located inside the `prompter/` directory—run `ls prompter` if you don't see it) if you need additional Prompter conventions or clarifications.
-- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
-- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
-
-**Steps**
-1. Review `prompter/project.md`, run `prompter list` and `prompter list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
-2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `prompter/changes/<id>/`.
-3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
-4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
-5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
-6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
-7. Validate with `prompter validate <id> --strict` and resolve every issue before sharing the proposal.
-
-**Reference**
-- Use `prompter show <id> --json --deltas-only` or `prompter show <spec> --type spec` to inspect details when validation fails.
-- Search existing requirements with `rg -n "Requirement:|Scenario:" prompter/specs` before writing new ones.
-- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
-<!-- PROMPTER:END -->
-