claude-orator-mcp 0.2.0-beta.0

package/.claude/skills/claude-orator/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: claude-orator
+description: Use when dispatching subagents with non-trivial prompts, writing system prompts or skill descriptions, or when any prompt feels vague — scores 7 quality dimensions, auto-selects from 11 techniques, and rewrites with before/after scores.
+---
+
+# Claude Orator
+
+Make prompts measurably better before sending them.
+
+## When to Use
+
+**Dispatching subagents** → Run the prompt through `orator_optimize` first. Better prompt = less back-and-forth, more accurate results.
+
+**Writing system prompts** → SKILL.md files, agent instructions, tool descriptions. Small improvements compound over many invocations.
+
+**Prompt feels vague or under-specified** → Score it. Orator identifies weak dimensions and applies targeted techniques.
+
+## Quick Reference
+
+```
+orator_optimize(prompt: "...", intent?: "code|analysis|creative|extraction|system", techniques?: ["xml-tags", "few-shot"])
+```
+
+**Output:** Before score → techniques applied → optimized prompt → after score.
+
+**Already good?** One-line confirmation: `🪶 ━━ already well-structured (8.4)`
+
+## When to Skip
+
+Skip for trivial prompts, simple questions, or prompts already scoring above 7.0. The overhead isn't worth it for single-step instructions.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Optimizing everything | Focus on high-leverage: subagent prompts, system prompts |
+| Ignoring the score delta | Close before/after scores mean the prompt was already good |
+| Not using `techniques` override | When you know which techniques apply, force them |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vvkmnn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+<img align="right" src="claude-orator.svg" alt="claude-orator-mcp" width="220">
+
+# claude-orator-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that **optimizes prompts** for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Heuristic analysis, Anthropic technique selection, and structural rewriting — zero external dependencies, fully deterministic.
+
+<br clear="right">
+
+[![npm version](https://img.shields.io/npm/v/claude-orator-mcp.svg)](https://www.npmjs.com/package/claude-orator-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/) [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff)](#) [![GitHub stars](https://img.shields.io/github/stars/Vvkmnn/claude-orator-mcp?style=social)](https://github.com/Vvkmnn/claude-orator-mcp)
+
+---
+
+Orator is the rhetoric coach — Claude is the orator. The MCP provides deterministic heuristic analysis and technique selection; Claude does the actual rewriting with full context. Built on [Anthropic's prompt engineering best practices](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview): XML tags, multishot examples, chain-of-thought, structured output, role assignment, prefill, prompt chaining, and uncertainty permission.
+
+## what's new in 0.2.0
+
+- **Intent disambiguation** — `"You are an expert Rust dev... build me an app"` now correctly resolves to `code`, not `system`. Fallback heuristics catch code blocks, "build me", and debugging language.
+- **Claude 4.6 anti-patterns** — 4 new detections: thoroughness backfire, imperative tool instructions, plan-sharing penalties, and suggest-framing traps.
+- **Context-first assembly** — template now front-loads `<context>` before `<task>`, matching Codex research on grounding data ordering.
+- **Scorer overhaul** — recalibrated dimension heuristics produce meaningful score jumps (avg +2.6, up from ~0.9).
+- **Structured output format** — replaces the old prefill technique for Claude 4.6+ compatibility.
+- **25 regression tests** — comprehensive self-test suite covering all intent categories, anti-patterns, and edge cases.
+
+## install
+
+**Requirements:**
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-555?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxOCAxMCIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj4KICAKICAKICAKICAKICAKICAKICAKICAKICAKICAKPC9zdmc+Cg==)](https://claude.ai/code)
+
+**From shell:**
+
+```bash
+claude mcp add claude-orator-mcp -- npx claude-orator-mcp
+```
+
+**From inside Claude** (restart required):
+
+```
+Add this to our global mcp config: npx claude-orator-mcp
+
+Install this mcp: https://github.com/Vvkmnn/claude-orator-mcp
+```
+
+**From any manually configurable `mcp.json`:** (Cursor, Windsurf, etc.)
+
+```json
+{
+  "mcpServers": {
+    "claude-orator-mcp": {
+      "command": "npx",
+      "args": ["claude-orator-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+There is **no `npm install` required** — no external dependencies or databases, only deterministic heuristics.
+
+However, if `npx` resolves the wrong package, you can force resolution with:
+
+```bash
+npm install -g claude-orator-mcp
+```
+
+## [skill](.claude/skills/claude-orator)
+
+Optionally, install the skill to teach Claude when to proactively optimize prompts:
+
+```bash
+npx skills add Vvkmnn/claude-orator-mcp --skill claude-orator --global
+# Optional: add --yes to skip interactive prompt and install to all agents
+```
+
+This makes Claude automatically optimize prompts before dispatching subagents, writing system prompts, or crafting any prompt worth improving. The MCP works without the skill, but the skill improves discoverability.
+
+## [plugin](https://github.com/Vvkmnn/claude-emporium)
+
+For automatic prompt optimization hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:
+
+```bash
+/plugin marketplace add Vvkmnn/claude-emporium
+/plugin install claude-orator@claude-emporium
+```
+
+The **claude-orator** plugin provides:
+
+**Hooks** (targeted, zero overhead on good prompts):
+
+- `PreToolUse (Task)` — suggest optimization for under-specified subagent prompts
+- Before dispatching any subagent → quick heuristic score, suggest `orator_optimize` if < 5.0
+
+**Command:** `/reprompt-orator <prompt>` — manual prompt optimization
+
+Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.
+
+## features
+
+[MCP server](https://modelcontextprotocol.io/) with a single tool. Prompt in, optimized prompt out.
+
+#### `orator_optimize`
+
+Analyze a prompt across 7 quality dimensions, auto-select from 11 Anthropic techniques, and return a structurally optimized scaffold with before/after scores.
+
+```
+orator_optimize prompt="Write a function that sorts users"
+  > Returns optimized scaffold with XML tags, output format, examples section
+
+orator_optimize prompt="You are a helpful assistant" intent="system"
+  > Returns role-assigned system prompt with structure and constraints
+
+orator_optimize prompt="Extract all emails from this text" techniques=["xml-tags", "few-shot"]
+  > Force-applies specific techniques regardless of auto-selection
+```
+
+**Score meter** (unique notification format — gradient fill bar):
+
+```
+🪶 3.2 ░░░▓▓▓▓▓▓▓▓ 7.8
+   +xml-tags +few-shot +structured-output · 3 issues
+   Wrapped in XML tags, added examples, specified output format
+```
+
+Three-zone bar: `░░░` (baseline) `▓▓▓▓▓` (improvement) `░░` (headroom to 10).
+
+**Minimal case** (already well-structured):
+
+```
+🪶 ━━ already well-structured (8.4)
+```
+
+**Input:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | The raw prompt to optimize |
+| `intent` | enum | No | `code \| analysis \| creative \| extraction \| conversation \| system` (auto-detected) |
+| `target` | enum | No | `claude-code \| claude-api \| claude-desktop \| generic` (default: `claude-code`) |
+| `techniques` | string[] | No | Force-apply specific technique IDs |
+
+**Output:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `optimized_prompt` | string | Rewritten prompt scaffold (primary output) |
+| `score_before` | number | Quality score of original (0-10) |
+| `score_after` | number | Quality score after optimization (0-10) |
+| `summary` | string | 1-line explanation of improvements |
+| `detected_intent` | string | Auto-detected intent category |
+| `applied_techniques` | string[] | Technique IDs applied |
+| `issues` | string[] | Detected problems |
+| `suggestions` | string[] | Actionable fixes |
+
+The `optimized_prompt` is a structural scaffold. Claude refines it with domain knowledge, codebase context, and conversation history.
+
+## methodology
+
+How [claude-orator-mcp](https://github.com/Vvkmnn/claude-orator-mcp) [works](https://github.com/Vvkmnn/claude-orator-mcp/tree/main/src):
+
+```
+                🪶 claude-orator-mcp
+                ════════════════════
+
+
+                   orator_optimize
+                   ──────────────
+
+                      PROMPT
+                        │
+           ┌────────────┴────────────┐
+           ▼                         ▼
+     ┌───────────┐            ┌────────────┐
+     │  Detect   │            │  Measure   │
+     │  Intent   │            │ Complexity │
+     └─────┬─────┘            └──────┬─────┘
+           │                         │
+     system > code >           word count +
+     extraction >              clause depth
+     analysis >                      │
+     creative >                      │
+     conversation                    │
+     + disambiguation                │
+     + fallback heuristics           │
+           │                         │
+           └────────────┬────────────┘
+                        │
+                        ▼
+              ┌───────────────────┐
+              │   Score Before    │
+              │                   │
+              │  clarity      20% │  strong verbs, single task
+              │  specificity  20% │  named tech, constraints
+              │  structure    15% │  XML tags, headers, lists
+              │  examples     15% │  input/output pairs
+              │  constraints  10% │  scope, edge cases
+              │  output_fmt   10% │  format specification
+              │  efficiency   10% │  no filler, no redundancy
+              │                   │
+              │  ░░░░░░░░░░  3.2  │
+              └────────┬──────────┘
+                       │
+                       ▼
+              ┌───────────────────┐       techniques?
+              │ Select Techniques │◄──── (force override)
+              │                   │
+              │  when_to_use() ×  │  11 predicates
+              │  intent match  ×  │  filtered
+              │  score gaps    ×  │  sorted by impact
+              │  cap at 4        │
+              └────────┬──────────┘
+                       │
+                       ▼
+              ┌───────────────────┐
+              │ Template Assembly │
+              │                   │
+              │  role preamble    │  expert identity
+              │  → <context>      │  grounding data first
+              │  → <task>         │  XML-wrapped prompt
+              │  → <requirements> │  constraints + gaps
+              │  → <examples>     │  multishot I/O pairs
+              │  → output format  │  format specification
+              └────────┬──────────┘
+                       │
+                       ▼
+              ┌───────────────────┐
+              │   Score After     │
+              │                   │
+              │  ░░░▓▓▓▓▓▓▓░░ 7.8│
+              └────────┬──────────┘
+                       │
+                       ▼
+                    OUTPUT
+              optimized_prompt
+              + scores + techniques
+              + issues + suggestions
+
+
+     score meter (gradient fill bar):
+     ─────────────────────────────────
+
+     🪶 3.2 ░░░▓▓▓▓▓▓▓▓ 7.8
+        +xml-tags +few-shot +structured-output
+        Wrapped in XML, added examples, format
+
+     ░░░  baseline    ▓▓▓  improvement    ░░  headroom
+```
+
+**7 quality dimensions** (weighted scoring, deterministic):
+
+| Dimension | Weight | Measures |
+|-----------|--------|----------|
+| Clarity | 20% | Strong verbs, single task, no hedging |
+| Specificity | 20% | Named tech, numbers, constraints |
+| Structure | 15% | XML tags, headers, lists |
+| Examples | 15% | Input/output pairs, demonstrations |
+| Constraints | 10% | Negative constraints, scope, edge cases |
+| Output Format | 10% | Format spec, structure definition |
+| Token Efficiency | 10% | No filler, no redundancy |
+
+**11 Anthropic techniques** (auto-selected based on intent, scores, and complexity):
+
+| ID | Name | Auto-selected when |
+|----|------|--------------------|
+| `chain-of-thought` | [Let Claude Think](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-of-thought) | Analysis intent, complex tasks |
+| `xml-tags` | [Use XML Tags](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags) | Long prompt + low structure score |
+| `few-shot` | [Multishot Examples](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting) | Low example score + extraction/code |
+| `role-assignment` | [System Prompts & Roles](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/system-prompts) | System intent or low specificity |
+| `structured-output` | [Control Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/fill-in-the-blank) | Low output format score |
+| `prefill` | [Structured Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prefill-claudes-response) | API target + extraction/code |
+| `prompt-chaining` | [Chain Complex Tasks](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-prompts) | Complex + multiple subtasks |
+| `uncertainty-permission` | [Say "I Don't Know"](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/ask-claude-for-rewrites) | Analysis or extraction intent |
+| `extended-thinking` | [Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) | Complex + analysis/code intent |
+| `long-context-tips` | [Long Context](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips) | Long prompt (>2000 chars or >50 lines) |
+| `tool-use` | [Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview) | Prompt mentions tool/function calling |
+
+**Core algorithms:**
+
+- **[Intent detection](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/analysis/detector.ts)** (`detectIntent`): Priority-ordered regex patterns across 6 categories — `system > code > extraction > analysis > creative > conversation`. Includes disambiguation (e.g., `system` + `code` signals → resolves to `code`) and fallback heuristics for code blocks, "build me" patterns, and debugging language.
+- **[Heuristic scoring](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/analysis/heuristics.ts)** (`scorePrompt`): 7-dimension weighted analysis. Each dimension 0-10, overall is weighted sum. Also generates flat `issues[]` and `suggestions[]` arrays.
+- **[Technique selection](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/techniques/index.ts)** (`selectTechniques`): Each technique has a `when_to_use()` predicate. Auto-selected based on intent + scores + complexity. Sorted by impact, capped at 4.
+- **[Template assembly](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/optimize.ts)** (`optimize`): Builds structural scaffold from selected techniques. Context-first ordering: role → `<context>` → `<task>` → `<requirements>` → `<examples>` → output format.
+
+**Design principles:**
+
+- **Single tool** — one entry point, minimal cognitive overhead
+- **Deterministic** — same input = same output, no LLM calls, no network
+- **Scaffold, not final** — the optimized prompt is structural; Claude adds substance
+- **Lean output** — flat string arrays for issues/suggestions, no nested objects
+- **Weighted dimensions** — clarity and specificity matter most (20% each)
+- **Technique cap** — max 4 techniques per optimization (diminishing returns beyond)
+- **Anti-pattern detection** — 10 Claude-specific anti-patterns including 4 for Claude 4.6 (thoroughness backfire, tool over-triggering, plan-sharing penalty, suggest framing)
+- **Zero dependencies** — only `@modelcontextprotocol/sdk` + `zod`
+
+## alternatives
+
+Every existing prompt optimization tool requires LLM calls, labeled datasets, or evaluation infrastructure. When you need structural improvement at zero latency — during CI/CD, before subagent dispatch, or offline — they cannot help.
+
+| Feature | **orator** | DSPy | promptfoo | TextGrad | OPRO | LLMLingua | Anthropic Generator |
+|---|---|---|---|---|---|---|---|
+| **Zero latency** | **Yes (<1ms)** | No (LLM calls) | No (eval runs) | No (LLM calls) | No (LLM calls) | No (LLM calls) | No (LLM call) |
+| **Offline/airgapped** | **Yes** | No | Partial | No | No | No | No |
+| **Deterministic** | **Yes** | No | No | No | No | Partial | No |
+| **No labeled data** | **Yes** | No (examples) | No (test cases) | No (feedback) | No (examples) | Yes | Yes |
+| **Claude-specific** | **Yes (anti-patterns)** | No | No | No | No | No | Yes |
+| **MCP native** | **Yes** | No | No | No | No | No | No |
+| **Structural scoring** | **7 dimensions** | None | Custom metrics | None | None | None | None |
+| **Dependencies** | **0 (pure TS)** | PyTorch + LLM | Node + LLM | PyTorch + LLM | LLM | PyTorch + LLM | LLM API |
+
+**[DSPy](https://github.com/stanfordnlp/dspy)** — Stanford's framework for compiling LM programs with automatic prompt optimization. Requires labeled examples, LLM calls for optimization, and PyTorch. Optimizes for task accuracy, not structural quality. Latency: seconds to minutes per optimization. Use DSPy when you have labeled data and want to tune for a specific metric.
+
+**[promptfoo](https://github.com/promptfoo/promptfoo)** — Test-driven prompt evaluation framework. Requires test cases, LLM calls for evaluation, and an evaluation dataset. Measures output quality, not prompt structure. Complementary: use Orator for structural scaffolding, then promptfoo to evaluate output quality.
+
+**[TextGrad](https://github.com/zou-group/textgrad)** — Automatic differentiation via text feedback from LLMs. Requires LLM calls for both forward and backward passes. Research-oriented, PyTorch dependency. Latency: minutes. Use when iterating on prompt wording with measurable objectives.
+
+**[OPRO](https://github.com/google-deepmind/opro)** — DeepMind's optimization by prompting: uses an LLM to iteratively rewrite prompts. Requires examples of good/bad outputs, multiple LLM calls per iteration. Latency: minutes. Use when exploring creative prompt variations with evaluation feedback.
+
+**[LLMLingua](https://github.com/microsoft/LLMLingua)** — Microsoft's prompt compression via perplexity-based token removal. Reduces token count by 2-20x but requires a local LLM for perplexity scoring. Different goal: compression, not structural improvement. Use when context window is the bottleneck.
+
+**[Anthropic Prompt Generator](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prompt-generator)** — Anthropic's own tool that generates prompts via Claude. Excellent quality but requires an LLM call, non-deterministic, and not available offline or via MCP. Use when you want Claude to write your prompt from scratch.
+
+Orator's approach is deliberately different: structural analysis via deterministic heuristics. No LLM calls means no API keys, no latency variance, no cost per optimization, and identical results every run. The trade-off is that Orator optimizes prompt *structure* (clarity, specificity, constraints, format) rather than prompt *wording* — it can't tell you if your prompt produces good *output*, only that it's well-formed for Claude. This makes it complementary to evaluation tools like promptfoo: scaffold with Orator, then validate with eval.
+
+## development
+
+```bash
+git clone https://github.com/Vvkmnn/claude-orator-mcp && cd claude-orator-mcp
+npm install && npm run build
+npm test
+```
+
+**Package requirements:**
+
+- **Node.js**: >=20.0.0 (ES modules)
+- **Runtime**: `@modelcontextprotocol/sdk`, `zod`
+- **Zero external databases** — works with `npx`
+
+**Development workflow:**
+
+```bash
+npm run build          # TypeScript compilation with executable permissions
+npm run dev            # Watch mode with tsc --watch
+npm run start          # Run the MCP server directly
+npm run lint           # ESLint code quality checks
+npm run lint:fix       # Auto-fix linting issues
+npm run format         # Prettier formatting (src/)
+npm run format:check   # Check formatting without changes
+npm run typecheck      # TypeScript validation without emit
+npm run test           # Lint + type check
+npm run prepublishOnly # Pre-publish validation (build + lint + format:check)
+```
+
+**Git hooks (via Husky):**
+
+- **pre-commit**: Auto-formats staged `.ts` files with Prettier and ESLint
+
+Contributing:
+
+- Fork the repository and create feature branches
+- Follow TypeScript strict mode and [MCP protocol](https://modelcontextprotocol.io/specification) standards
+
+Learn from examples:
+
+- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations
+- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices
+- [Anthropic prompt engineering docs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) for technique details
+
+## license
+
+[MIT](LICENSE)
+
+<hr>
+
+<a href="https://en.wikipedia.org/wiki/Cicero_Denounces_Catiline"><img src="logo/maccari-cicero.jpg" alt="Cicero Denounces Catiline — Cesare Maccari" width="100%"></a>
+
+_**[Cicero Denounces Catiline](https://en.wikipedia.org/wiki/Cicero_Denounces_Catiline)** by **[Cesare Maccari](https://en.wikipedia.org/wiki/Cesare_Maccari)** (1889). "Quo usque tandem abutere, Catilina, patientia nostra?" [How long, Catiline, will you abuse our patience?] [Claudius](https://en.wikipedia.org/wiki/Claudius), once dismissed for his stammer, later addressed this same Senate — proof that the right words, well-structured, can move an empire._

package/dist/analysis/detector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Intent detection via keyword pattern-matching with disambiguation.
+ *
+ * Strategy:
+ * 1. First-pass: priority-ordered pattern matching (system > code > ... > conversation)
+ * 2. Disambiguation: "You are an expert... build me X" → system match overridden to code
+ * 3. Fallback heuristics: code blocks, "build me", debugging language → code before conversation
+ */
+import type { Complexity, Intent } from '../types.js';
+/** Detect intent from prompt content with disambiguation and fallback heuristics. */
+export declare function detectIntent(prompt: string): Intent;
+/** Detect complexity based on word count and structural indicators. */
+export declare function detectComplexity(prompt: string): Complexity;

package/dist/analysis/detector.js

@@ -0,0 +1,160 @@
+/**
+ * Intent detection via keyword pattern-matching with disambiguation.
+ *
+ * Strategy:
+ * 1. First-pass: priority-ordered pattern matching (system > code > ... > conversation)
+ * 2. Disambiguation: "You are an expert... build me X" → system match overridden to code
+ * 3. Fallback heuristics: code blocks, "build me", debugging language → code before conversation
+ */
+// Ordered by priority: most distinctive patterns first
+const INTENT_PATTERNS = [
+    [
+        'system',
+        [
+            /^you are\b/i,
+            /\bact as\b/i,
+            /\byour role\b/i,
+            /\bbehave as\b/i,
+            /\bsystem prompt\b/i,
+            /\byou\s+must\s+always\b/i,
+            /\byour\s+task\s+is\b/i,
+        ],
+    ],
+    [
+        'code',
+        [
+            /\bwrite\s+(a\s+)?(\w+\s+)?function\b/i,
+            /\bimplement\b/i,
+            /\brefactor\b/i,
+            /\bdebug\b/i,
+            /\bfix\s+(the\s+)?(bug|error|issue|crash)\b/i,
+            /\bcreate\s+(a\s+)?(\w+\s+)*(class|component|api|endpoint|module|service|app|application|middleware|hook|plugin|decorator|wrapper)\b/i,
+            /\badd\s+(a\s+)?(method|function|handler|route|feature)\b/i,
+            /\bcode\s+(that|which|to)\b/i,
+            /\banalyze\s+(this\s+)?(code|function|class|module)\b/i,
+            /\breview\s+(this\s+)?(code|function|PR|pull\s+request|diff)\b/i,
+            /\bbuild\s+(me\s+)?(a\s+)?(\w+\s+)*(app|application|tool|script|server|client|cli|bot|crawler|fetcher|scraper|parser|service|api|site|website|page|dashboard|plugin|extension|library|package|module)\b/i,
+            /\bmake\s+(me\s+)?(a\s+)?(\w+\s+)*(app|application|tool|script|server|client|cli|bot)\b/i,
+            /\bwrite\s+(me\s+)?(a\s+)?(\w+\s+)*(script|program|app|tool|cli|bot)\b/i,
+            /\bwhat'?s?\s+wrong\s+with\b/i,
+            /\bhow\s+do\s+I\s+(fix|solve|implement|build|make|write|create)\b/i,
+            /\bhere'?s?\s+(my|the|some)\s+code\b/i,
+        ],
+    ],
+    [
+        'extraction',
+        [
+            /\bextract\b/i,
+            /\bparse\b/i,
+            /\bfind\s+all\b/i,
+            /\blist\s+(all|the|every)\b/i,
+            /\bidentify\b/i,
+            /\bcollect\b/i,
+            /\bpull\s+out\b/i,
+            /\bscrape\b/i,
+        ],
+    ],
+    [
+        'analysis',
+        [
+            /\banalyze\b/i,
+            /\breview\b/i,
+            /\bexplain\b/i,
+            /\bevaluate\b/i,
+            /\bcompare\b/i,
+            /\bassess\b/i,
+            /\baudit\b/i,
+            /\bwhy\s+(does|did|is|are|was)\b/i,
+            /\bwhat\s+causes?\b/i,
+        ],
+    ],
+    [
+        'creative',
+        [
+            /\bwrite\s+(a\s+)?(story|poem|essay|blog|article|post|letter|email)\b/i,
+            /\bbrainstorm\b/i,
+            /\bdraft\b/i,
+            /\bgenerate\s+(a\s+)?(name|title|tagline|slogan|headline)\b/i,
+            /\bcreate\s+(a\s+)?(story|narrative|description)\b/i,
+        ],
+    ],
+    [
+        'conversation',
+        [
+            /\bchat\s+(with|about)\b/i,
+            /\bdiscuss\b/i,
+            /\bhelp\s+me\s+(understand|think|decide)\b/i,
+            /\btalk\s+(about|through)\b/i,
+            /\bwhat\s+do\s+you\s+think\b/i,
+        ],
+    ],
+];
+/**
+ * Signals that a prompt body is primarily about code, even if the opening
+ * matches a non-code intent (e.g., "You are an expert... implement X").
+ */
+const CODE_BODY_SIGNALS = [
+    /\bimplement\b/i,
+    /\bbuild\b/i,
+    /\bwrite\s+(a\s+)?(\w+\s+)*(function|class|method|script|program|app|tool|cli|bot|server|client)\b/i,
+    /\brefactor\b/i,
+    /\bdebug\b/i,
+    /\bcreate\s+(a\s+)?(class|component|api|endpoint|module|service|app)\b/i,
+    /```[\s\S]*?```/, // fenced code blocks
+    /\b(async|await|function|const|let|var|import|export|class|interface|type|def|fn|pub|struct|enum)\b/,
+    /\breturn\s+(a|the|an)?\s*\w/i,
+    /\b(typescript|javascript|python|rust|go|java|ruby)\b/i,
+];
+/**
+ * Fallback heuristics: detect code intent from prompts that didn't match
+ * any explicit pattern (would otherwise default to 'conversation').
+ */
+const CODE_FALLBACK_SIGNALS = [
+    /```[\s\S]*?```/, // contains code blocks
+    /\bbuild\s+me\b/i, // "build me a ..."
+    /\bmake\s+(it|this)\s+(work|run|compile|pass)\b/i, // "make it work"
+    /\bhere'?s?\s+(my|the|some)\s+code\b/i,
+    /\b(TypeError|SyntaxError|ReferenceError|Error|Exception|stack\s*trace|segfault)\b/,
+    /\b(npm|pip|cargo|yarn|pnpm|go\s+get|brew|apt|gem)\s+(install|add|run|build|test)\b/i,
+];
+/** Detect intent from prompt content with disambiguation and fallback heuristics. */
+export function detectIntent(prompt) {
+    let matched = null;
+    for (const [intent, patterns] of INTENT_PATTERNS) {
+        if (patterns.some((p) => p.test(prompt))) {
+            matched = intent;
+            break;
+        }
+    }
+    // Disambiguation: "You are an expert X" + code body → code, not system
+    if (matched === 'system') {
+        const signalCount = CODE_BODY_SIGNALS.filter((p) => p.test(prompt)).length;
+        if (signalCount >= 2) {
+            return 'code';
+        }
+    }
+    if (matched)
+        return matched;
+    // Fallback heuristics before defaulting to 'conversation'
+    if (CODE_FALLBACK_SIGNALS.some((p) => p.test(prompt))) {
+        return 'code';
+    }
+    return 'conversation';
+}
+/** Detect complexity based on word count and structural indicators. */
+export function detectComplexity(prompt) {
+    const wordCount = prompt.split(/\s+/).filter(Boolean).length;
+    const hasMultipleClauses = /\b(and\s+also|additionally|furthermore|moreover|then\s+also)\b/i.test(prompt);
+    const hasMultipleSteps = /\b(first|second|third|step\s+\d|then)\b/i.test(prompt);
+    const hasConditions = /\b(if\s+.+then|when\s+.+should|unless|except\s+when)\b/i.test(prompt);
+    if (wordCount > 200 ||
+        (wordCount > 100 && (hasMultipleClauses || hasMultipleSteps)) ||
+        (hasMultipleSteps && hasConditions)) {
+        return 'complex';
+    }
+    if (wordCount > 50 || hasMultipleClauses || hasMultipleSteps) {
+        return 'moderate';
+    }
+    return 'simple';
+}
+//# sourceMappingURL=detector.js.map

package/dist/analysis/detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../src/analysis/detector.ts"],"names":[],"mappings":"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"}

package/dist/analysis/heuristics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 7-dimension quality scoring for prompts.
+ * All scoring is deterministic: same input always produces same output.
+ * Each dimension is 0-10, overall is weighted sum.
+ */
+import { type Scores } from '../types.js';
+/** Score a prompt across all 7 dimensions. Returns individual scores. */
+export declare function scorePrompt(prompt: string): Scores;
+/** Compute weighted overall score from dimension scores. */
+export declare function overallScore(scores: Scores): number;
+/** Detect issues in the prompt as flat string descriptions. */
+export declare function detectIssues(prompt: string, scores: Scores): string[];
+/** Generate actionable suggestions as flat strings. */
+export declare function generateSuggestions(prompt: string, scores: Scores): string[];