@dedesfr/prompter 0.8.0 → 0.8.2

package/skills/project-orchestrator/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: project-orchestrator
+description: Interview users to define and verify a software project plan through a structured conversation. Collects project description, MVP scope, user roles, features, tech stack, integrations, and deployment preferences. Asks minimal clarifying questions grouped logically, provides tailored recommendations after each answer, and produces a verified project plan summary. Use when a user wants to plan a new software project, define MVP scope, choose a tech stack, or create a project brief.
+---
+
+# Project Orchestrator
+
+Interview the user to define a verified software project plan. Guide them through scope, features, tech stack, and deployment with minimal, focused questions. Provide a recommendation after every answer.
+
+## Quick Start
+
+1. **COLLECT** -- Ask for project description + top 3 MVP features
+2. **VERIFY** -- Walk through scope, roles, data, integrations, non-functional needs
+3. **SELECT STACK** -- Present bundled stack options, resolve sub-choices
+4. **CONFIGURE** -- Docker preference, deployment, environments
+5. **SUMMARIZE** -- Output the verified plan using the final summary template
+6. **CONFIRM** -- Ask the user to approve or correct the plan
+
+---
+
+## Before You Begin (REQUIRED)
+
+Before starting the interview, **always read `prompter/AGENTS.md`** and follow its instructions. This ensures the final output is structured as a proper spec that integrates with the Prompter workflow.
+
+---
+
+## Interactive Terminal Tool (REQUIRED)
+
+Use the `AskUserQuestion` tool for **every question** in the interview. This renders an interactive UI in the terminal instead of plain text, making it easier for the user to respond.
+
+### How to Use AskUserQuestion
+
+- **Single-choice questions**: Set `multiSelect: false`. Use for mutually exclusive picks (e.g., stack selection, database choice, Docker yes/no).
+- **Multi-choice questions**: Set `multiSelect: true`. Use for checklists (e.g., integrations, roles, features).
+- **Keep options concise**: Labels should be 1–5 words. Add detail in the `description` field.
+- **Always include an "Unsure" option** when the user may not know. Handle it by recommending a default.
+- **Group related sub-choices** into one `AskUserQuestion` call with multiple `questions` when they are always asked together and order doesn't matter.
+
+### Example: Stack Selection
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which tech stack bundle fits your project best?",
+      "header": "Stack",
+      "multiSelect": false,
+      "options": [
+        { "label": "JS/TS Full-Stack", "description": "React or Next.js + Drizzle + Express or NestJS + PostgreSQL/MySQL" },
+        { "label": "React + Convex", "description": "React (Vite or Next.js) + Convex (real-time backend + built-in DB)" },
+        { "label": "Laravel Classic", "description": "Laravel + Blade + Tailwind + PostgreSQL/MySQL" },
+        { "label": "Laravel + React", "description": "Laravel + Inertia.js (React) + PostgreSQL/MySQL" },
+        { "label": "Laravel + Filament", "description": "Laravel + Filament (admin panel & CRUD) + Tailwind + PostgreSQL/MySQL" },
+        { "label": "Unsure", "description": "I'll recommend based on your project needs" }
+      ]
+    }
+  ]
+}
+```
+
+### Example: Integrations Checklist
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which integrations or capabilities does your MVP need?",
+      "header": "Integrations",
+      "multiSelect": true,
+      "options": [
+        { "label": "Caching", "description": "e.g., Redis for fast data access" },
+        { "label": "Queues / Jobs", "description": "e.g., sending emails, processing uploads" },
+        { "label": "Real-Time", "description": "e.g., live chat, notifications, WebSockets" },
+        { "label": "File Storage", "description": "e.g., S3, local uploads" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Core Rules
+
+- Use `AskUserQuestion` for every question -- never ask interview questions as plain text.
+- Ask one question or one small grouped set at a time. Never overwhelm.
+- After every answer (or group), provide a short recommendation tailored to what the user said.
+- Use plain language. Only introduce jargon if the user shows technical comfort.
+- If the user says "unsure", recommend a pragmatic default and explain briefly.
+- Keep optional topics gated -- only go deeper if the user says yes or unsure.
+
+---
+
+## Project Setup Commands (PRIORITY)
+
+Always use these exact commands when scaffolding projects. Include the correct command in the final summary's "Recommended Next Steps" based on the chosen stack.
+
+| Technology | Command |
+|------------|---------|
+| React (Vite) | `npm create vite@latest` |
+| Next.js | `npx create-next-app@latest {project_name} --yes` |
+| 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` |
+| React + Convex | `npm create convex@latest` |
+
+**Rules:**
+- Always include the matching setup command(s) as the first recommended next step in the final plan.
+- For Bundle 1 (JS/TS Full-Stack): include the frontend command (React via Vite or Next.js) AND the backend command (Express or NestJS).
+- For Bundle 2 (React + Convex): include only `npm create convex@latest` -- it scaffolds both the React frontend and Convex backend in one step.
+- For Bundles 3 and 4 (Laravel): include only the Laravel command -- Blade, Inertia, and Tailwind are configured within the Laravel project.
+- For Bundle 5 (Laravel + Filament): include the Laravel command first, then the Filament install command (`composer require filament/filament && php artisan filament:install --panels`).
+- Never invent or substitute alternative installation commands. Use these exactly as shown.
+
+---
+
+## Step 1: Project Description (REQUIRED)
+
+Open with:
+
+```
+Let's define your project. To start, tell me:
+
+1. What problem does your project solve, and who is it for?
+2. What is the desired outcome (e.g., a web app, mobile app, SaaS platform)?
+3. What are your top 3 MVP features -- the minimum needed to launch?
+```
+
+Wait for the user's response. Summarize what you understood and give a brief recommendation (e.g., "This sounds like a good fit for a standard web app with auth and a dashboard. Let's verify the details.").
+
+---
+
+## Step 2: MVP Scope Confirmation
+
+Based on the user's description, present a draft scope:
+
+```
+Here's what I'd put in scope for the MVP:
+
+**In scope:**
+- [feature 1]
+- [feature 2]
+- [feature 3]
+
+**Out of scope (for later):**
+- [deferred item 1]
+- [deferred item 2]
+
+Does this match your expectations? Anything to add or move?
+```
+
+Recommendation: Briefly explain why you deferred certain items (e.g., "Reporting dashboards add complexity -- better to ship core functionality first and add analytics in v2.").
+
+---
+
+## Step 3: Users & Roles
+
+Ask:
+
+```
+Who will use this application? For example:
+- Public visitors (unauthenticated)
+- Registered users
+- Admins
+- Other roles (e.g., moderators, vendors, managers)
+
+Which roles does the MVP need?
+```
+
+Recommendation: Suggest a minimal role set (e.g., "For MVP, I'd recommend just User + Admin. You can add granular roles later without rearchitecting.").
+
+---
+
+## Step 4: Data & Content Types
+
+Ask:
+
+```
+What are the main things your app manages? For example:
+- Users / profiles
+- Products / listings
+- Orders / bookings
+- Posts / articles
+- Messages / notifications
+
+List the key entities your MVP needs to store and manage.
+```
+
+Recommendation: Sketch a quick high-level data model (e.g., "So we'd have Users, Products, and Orders as core entities, with Orders linking Users to Products.").
+
+---
+
+## Step 5: Integrations & Optional Capabilities
+
+Present optional topics as a checklist. Do NOT deep-dive unless the user says yes or unsure.
+
+```
+Do you need any of the following? (Yes / No / Unsure for each)
+
+1. Caching (e.g., Redis for fast data access)
+2. Queues / background jobs (e.g., sending emails, processing uploads)
+3. Real-time features (e.g., live chat, notifications, WebSockets)
+4. Full-text search (e.g., Elasticsearch, Algolia, Meilisearch)
+5. File storage / uploads (e.g., S3, local storage)
+6. Email or SMS notifications
+7. Analytics / event tracking
+8. Payments (e.g., Stripe, PayPal)
+9. Third-party integrations (e.g., social login, maps, calendar)
+```
+
+For each "yes" or "unsure":
+- Ask which service they prefer (or recommend one).
+- Give a 1-2 sentence recommendation (e.g., "For queues, Redis with a simple job runner is the easiest starting point. You can scale to dedicated queue services later.").
+
+For each "no": Move on. Don't push.
+
+---
+
+## Step 6: Non-Functional Requirements
+
+Ask as a grouped set:
+
+```
+A few quick questions about non-functional needs:
+
+1. **Security**: Any specific requirements beyond standard auth? (e.g., 2FA, encryption at rest, compliance like GDPR/HIPAA)
+2. **Performance**: Expected traffic volume? (e.g., <1k users, 1k-10k, 10k+)
+3. **SEO**: Does this app need to rank in search engines? (important for stack choice)
+```
+
+Recommendation: Tailor to their answers (e.g., "With SEO needs, server-side rendering will matter -- that'll influence our stack choice next." or "At <1k users, you won't need to worry about caching or CDN right away.").
+
+---
+
+## Step 7: Tech Stack Selection (REQUIRED)
+
+Present exactly these bundled options:
+
+```
+Let's pick your tech stack. Here are four proven bundles:
+
+1. **JS/TS Full-Stack**: React or Next.js + Drizzle ORM + Express or NestJS + MySQL or PostgreSQL
+2. **React + Convex**: React (Vite or Next.js) + Convex (real-time backend + built-in document DB, no SQL setup needed)
+3. **Laravel Classic**: Laravel + Blade + Tailwind CSS + MySQL or PostgreSQL
+4. **Laravel + React**: Laravel + Inertia.js (React) + MySQL or PostgreSQL
+5. **Laravel + Filament**: Laravel + Filament (admin panel & CRUD generator) + Tailwind CSS + MySQL or PostgreSQL
+
+Which bundle fits your project best? (Pick 1-5, or say "unsure")
+```
+
+If unsure: Recommend based on what you've learned (e.g., "Since you need SEO and prefer a simpler setup, I'd go with Laravel Classic -- it's fast to build, great for server-rendered pages, and has excellent built-in tooling." Or "If you want real-time features out of the box with minimal backend setup, React + Convex is a great choice." Or "If your app is primarily an admin panel, back-office tool, or data management system, Laravel + Filament gives you a complete CRUD interface with minimal custom frontend work.").
+
+### Sub-Choices
+
+After the user picks a bundle, ask ONLY the necessary sub-choices:
+
+**Bundle 1 sub-choices:**
+- Next.js vs React SPA? (Recommend Next.js if SEO matters or if they want SSR; React SPA if it's a dashboard/internal tool)
+- Express vs NestJS? (Recommend Express for simplicity and speed; NestJS if they want structure and the app is complex)
+- MySQL vs PostgreSQL? (Recommend PostgreSQL as the default -- richer features, JSON support, better for most new projects. Recommend MySQL if team is already familiar or hosting is MySQL-only)
+
+**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.
+
+**Bundle 3 sub-choices:**
+- MySQL vs PostgreSQL? (Same guidance as above)
+
+**Bundle 4 sub-choices:**
+- MySQL vs PostgreSQL? (Same guidance as above)
+
+**Bundle 5 sub-choices:**
+- MySQL vs PostgreSQL? (Same guidance as above)
+- Filament panels: Admin only, or also a user-facing app panel? (Recommend admin-only for MVP -- add a user-facing panel later if needed. If the user needs a public-facing frontend beyond Filament, suggest combining with Blade or consider Bundle 4 instead.)
+
+Provide a brief recommendation for each sub-choice based on the project's stated needs.
+
+---
+
+## Step 8: Docker Preference (REQUIRED)
+
+Always ask:
+
+```
+Do you want Docker for this project? (Yes / No / Unsure)
+
+Quick context: Docker makes it easy to set up identical dev environments across machines and simplifies deployment. The tradeoff is a small learning curve and slightly more setup upfront.
+```
+
+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.").
+
+---
+
+## Step 9: Deployment & Hosting
+
+Ask:
+
+```
+Where do you plan to deploy?
+
+Common options:
+- **VPS** (e.g., DigitalOcean, Hetzner, Linode) -- most flexible, you manage the server
+- **PaaS** (e.g., Railway, Render, Fly.io) -- easier, less control
+- **Cloud** (e.g., AWS, GCP, Azure) -- most scalable, most complex
+- **Shared hosting** (e.g., cPanel) -- cheapest, limited
+
+Also: do you need separate environments? (e.g., dev / staging / production)
+```
+
+Recommendation: Match to their context (e.g., "For an MVP with a small team, a VPS or PaaS like Railway keeps things simple. You can migrate to AWS later if you need to scale.").
+
+---
+
+## Step 10: Final Summary (REQUIRED)
+
+After all questions are answered, produce the verified plan using the template in `assets/plan-summary-template.md`.
+
+Present it to the user and ask (using `AskUserQuestion`):
+
+```json
+{
+  "questions": [
+    {
+      "question": "Does this project plan look correct?",
+      "header": "Plan Review",
+      "multiSelect": false,
+      "options": [
+        { "label": "Looks good", "description": "Approve and save the plan" },
+        { "label": "Needs changes", "description": "I'll tell you what to correct" }
+      ]
+    }
+  ]
+}
+```
+
+Iterate if the user requests changes. The plan is final only when the user confirms.
+
+### Save the Plan (REQUIRED)
+
+Once the user approves, **write the final plan to `prompter/project-plan.md`** using the Write tool. Use the filled-in plan summary template as the file content.
+
+```
+Write the approved plan content to: prompter/project-plan.md
+```
+
+After saving, confirm to the user:
+
+```
+Your project plan has been saved to prompter/project-plan.md.
+```
+
+### Proposal Creation (Conditional)
+
+After confirming the plan is saved, check whether the proposal feature is installed by verifying that `prompter/core/proposal.md` exists (use the Glob tool). If the file does not exist, skip this section entirely.
+
+If the file exists, ask the user using `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Would you like to create a Prompter change proposal based on this project plan?",
+      "header": "Create Proposal",
+      "multiSelect": false,
+      "options": [
+        { "label": "Yes, create a proposal", "description": "Scaffold a change proposal using the project plan as context" },
+        { "label": "No, skip", "description": "I'll create the proposal manually later" }
+      ]
+    }
+  ]
+}
+```
+
+If the user agrees, read `prompter/core/proposal.md` and `prompter/AGENTS.md` and follow their instructions to scaffold the proposal. Use the approved project plan from `prompter/project-plan.md` as the source of context (e.g., to derive the change-id, capabilities, requirements, and tasks).
+
+---
+
+## Conversation Tips
+
+### Handling "I don't know" / "Unsure"
+- Always recommend a sensible default.
+- Explain the recommendation in 1-2 sentences.
+- Frame it as: "You can always change this later."
+
+### Handling Overly Complex Requests
+- Gently suggest deferring non-essential features.
+- Use: "That's a great v2 feature. For MVP, I'd recommend [simpler alternative]."
+
+### Handling Very Technical Users
+- Skip basic explanations if the user demonstrates expertise.
+- Engage at their level -- discuss tradeoffs, not definitions.
+
+### Handling Non-Technical Users
+- Avoid jargon. Use analogies when helpful.
+- Make decisions for them when they're stuck, but always explain why.
+
+---
+
+## Resources
+
+- **Plan summary template**: [plan-summary-template.md](assets/plan-summary-template.md) -- Structured output format for the final verified plan

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

@@ -0,0 +1,124 @@
+# 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] | [Why] |
+| ORM / DB Layer | [e.g., Drizzle] | [Why] |
+| Database | [e.g., PostgreSQL] | [Why] |
+| Styling | [e.g., Tailwind CSS] | [Why] |
+| 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
+# 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. 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

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