claude-orator-mcp 0.2.0-beta.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +95 -90
- package/dist/analysis/detector.d.ts +3 -0
- package/dist/analysis/detector.js +30 -8
- package/dist/analysis/detector.js.map +1 -1
- package/dist/analysis/heuristics.d.ts +9 -3
- package/dist/analysis/heuristics.js +393 -31
- package/dist/analysis/heuristics.js.map +1 -1
- package/dist/analysis/industry.d.ts +50 -0
- package/dist/analysis/industry.js +303 -0
- package/dist/analysis/industry.js.map +1 -0
- package/dist/index.js +20 -1
- package/dist/index.js.map +1 -1
- package/dist/optimize.js +80 -60
- package/dist/optimize.js.map +1 -1
- package/dist/sampling.d.ts +19 -0
- package/dist/sampling.js +102 -0
- package/dist/sampling.js.map +1 -0
- package/dist/techniques/anthropic.d.ts +2 -0
- package/dist/techniques/anthropic.js +9 -1
- package/dist/techniques/anthropic.js.map +1 -1
- package/dist/types.d.ts +38 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,30 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
# claude-orator-mcp
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
An [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for deterministic prompt optimization in [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Score prompts across 7 quality dimensions, auto-select from 11 [Anthropic techniques](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview), and return a structural scaffold. No LLM calls, no network, sub-millisecond.
|
|
6
6
|
|
|
7
7
|
<br clear="right">
|
|
8
8
|
|
|
9
|
+
|
|
10
|
+
|
|
9
11
|
[](https://www.npmjs.com/package/claude-orator-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-orator-mcp)
|
|
10
12
|
|
|
11
13
|
---
|
|
12
14
|
|
|
13
|
-
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.
|
|
14
|
-
|
|
15
|
-
## what's new in 0.2.0
|
|
16
|
-
|
|
17
|
-
- **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.
|
|
18
|
-
- **Claude 4.6 anti-patterns** — 4 new detections: thoroughness backfire, imperative tool instructions, plan-sharing penalties, and suggest-framing traps.
|
|
19
|
-
- **Context-first assembly** — template now front-loads `<context>` before `<task>`, matching Codex research on grounding data ordering.
|
|
20
|
-
- **Scorer overhaul** — recalibrated dimension heuristics produce meaningful score jumps (avg +2.6, up from ~0.9).
|
|
21
|
-
- **Structured output format** — replaces the old prefill technique for Claude 4.6+ compatibility.
|
|
22
|
-
- **25 regression tests** — comprehensive self-test suite covering all intent categories, anti-patterns, and edge cases.
|
|
23
|
-
|
|
24
15
|
## install
|
|
25
16
|
|
|
26
17
|
**Requirements:**
|
|
27
18
|
|
|
28
|
-
[](https://claude.ai/code)
|
|
29
20
|
|
|
30
21
|
**From shell:**
|
|
31
22
|
|
|
@@ -41,7 +32,7 @@ Add this to our global mcp config: npx claude-orator-mcp
|
|
|
41
32
|
Install this mcp: https://github.com/Vvkmnn/claude-orator-mcp
|
|
42
33
|
```
|
|
43
34
|
|
|
44
|
-
**From any manually configurable `mcp.json
|
|
35
|
+
**From any manually configurable `mcp.json`**: (Cursor, Windsurf, etc.)
|
|
45
36
|
|
|
46
37
|
```json
|
|
47
38
|
{
|
|
@@ -55,7 +46,7 @@ Install this mcp: https://github.com/Vvkmnn/claude-orator-mcp
|
|
|
55
46
|
}
|
|
56
47
|
```
|
|
57
48
|
|
|
58
|
-
There is **no `npm install` required**
|
|
49
|
+
There is **no `npm install` required** -- no external dependencies or databases, only deterministic heuristics.
|
|
59
50
|
|
|
60
51
|
However, if `npx` resolves the wrong package, you can force resolution with:
|
|
61
52
|
|
|
@@ -76,7 +67,7 @@ This makes Claude automatically optimize prompts before dispatching subagents, w
|
|
|
76
67
|
|
|
77
68
|
## [plugin](https://github.com/Vvkmnn/claude-emporium)
|
|
78
69
|
|
|
79
|
-
For automatic prompt optimization hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:
|
|
70
|
+
For automatic prompt optimization with hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:
|
|
80
71
|
|
|
81
72
|
```bash
|
|
82
73
|
/plugin marketplace add Vvkmnn/claude-emporium
|
|
@@ -85,12 +76,11 @@ For automatic prompt optimization hooks and commands, install from the [claude-e
|
|
|
85
76
|
|
|
86
77
|
The **claude-orator** plugin provides:
|
|
87
78
|
|
|
88
|
-
**Hooks** (
|
|
79
|
+
**Hooks** (fires before subagent dispatch):
|
|
89
80
|
|
|
90
|
-
-
|
|
91
|
-
- Before dispatching any subagent → quick heuristic score, suggest `orator_optimize` if < 5.0
|
|
81
|
+
- Before Task -- Suggest prompt optimization before launching agents
|
|
92
82
|
|
|
93
|
-
**
|
|
83
|
+
**Commands:** `/reprompt-orator`
|
|
94
84
|
|
|
95
85
|
Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.
|
|
96
86
|
|
|
@@ -113,7 +103,7 @@ orator_optimize prompt="Extract all emails from this text" techniques=["xml-tags
|
|
|
113
103
|
> Force-applies specific techniques regardless of auto-selection
|
|
114
104
|
```
|
|
115
105
|
|
|
116
|
-
**Score meter** (
|
|
106
|
+
**Score meter** (gradient fill bar):
|
|
117
107
|
|
|
118
108
|
```
|
|
119
109
|
🪶 3.2 ░░░▓▓▓▓▓▓▓▓ 7.8
|
|
@@ -131,25 +121,25 @@ Three-zone bar: `░░░` (baseline) `▓▓▓▓▓` (improvement) `░░`
|
|
|
131
121
|
|
|
132
122
|
**Input:**
|
|
133
123
|
|
|
134
|
-
| Parameter
|
|
135
|
-
|
|
136
|
-
| `prompt`
|
|
137
|
-
| `intent`
|
|
138
|
-
| `target`
|
|
139
|
-
| `techniques` | string[] | No
|
|
124
|
+
| Parameter | Type | Required | Description |
|
|
125
|
+
| ------------ | -------- | -------- | -------------------------------------------------------------------------------------- |
|
|
126
|
+
| `prompt` | string | Yes | The raw prompt to optimize |
|
|
127
|
+
| `intent` | enum | No | `code \| analysis \| creative \| extraction \| conversation \| system` (auto-detected) |
|
|
128
|
+
| `target` | enum | No | `claude-code \| claude-api \| claude-desktop \| generic` (default: `claude-code`) |
|
|
129
|
+
| `techniques` | string[] | No | Force-apply specific technique IDs |
|
|
140
130
|
|
|
141
131
|
**Output:**
|
|
142
132
|
|
|
143
|
-
| Field
|
|
144
|
-
|
|
145
|
-
| `optimized_prompt`
|
|
146
|
-
| `score_before`
|
|
147
|
-
| `score_after`
|
|
148
|
-
| `summary`
|
|
149
|
-
| `detected_intent`
|
|
150
|
-
| `applied_techniques` | string[] | Technique IDs applied
|
|
151
|
-
| `issues`
|
|
152
|
-
| `suggestions`
|
|
133
|
+
| Field | Type | Description |
|
|
134
|
+
| -------------------- | -------- | ------------------------------------------ |
|
|
135
|
+
| `optimized_prompt` | string | Rewritten prompt scaffold (primary output) |
|
|
136
|
+
| `score_before` | number | Quality score of original (0-10) |
|
|
137
|
+
| `score_after` | number | Quality score after optimization (0-10) |
|
|
138
|
+
| `summary` | string | 1-line explanation of improvements |
|
|
139
|
+
| `detected_intent` | string | Auto-detected intent category |
|
|
140
|
+
| `applied_techniques` | string[] | Technique IDs applied |
|
|
141
|
+
| `issues` | string[] | Detected problems |
|
|
142
|
+
| `suggestions` | string[] | Actionable fixes |
|
|
153
143
|
|
|
154
144
|
The `optimized_prompt` is a structural scaffold. Claude refines it with domain knowledge, codebase context, and conversation history.
|
|
155
145
|
|
|
@@ -247,78 +237,78 @@ How [claude-orator-mcp](https://github.com/Vvkmnn/claude-orator-mcp) [works](htt
|
|
|
247
237
|
|
|
248
238
|
**7 quality dimensions** (weighted scoring, deterministic):
|
|
249
239
|
|
|
250
|
-
| Dimension
|
|
251
|
-
|
|
252
|
-
| Clarity
|
|
253
|
-
| Specificity
|
|
254
|
-
| Structure
|
|
255
|
-
| Examples
|
|
256
|
-
| Constraints
|
|
257
|
-
| Output Format
|
|
258
|
-
| Token Efficiency | 10%
|
|
240
|
+
| Dimension | Weight | Measures |
|
|
241
|
+
| ---------------- | ------ | --------------------------------------- |
|
|
242
|
+
| Clarity | 20% | Strong verbs, single task, no hedging |
|
|
243
|
+
| Specificity | 20% | Named tech, numbers, constraints |
|
|
244
|
+
| Structure | 15% | XML tags, headers, lists |
|
|
245
|
+
| Examples | 15% | Input/output pairs, demonstrations |
|
|
246
|
+
| Constraints | 10% | Negative constraints, scope, edge cases |
|
|
247
|
+
| Output Format | 10% | Format spec, structure definition |
|
|
248
|
+
| Token Efficiency | 10% | No filler, no redundancy |
|
|
259
249
|
|
|
260
250
|
**11 Anthropic techniques** (auto-selected based on intent, scores, and complexity):
|
|
261
251
|
|
|
262
|
-
| ID
|
|
263
|
-
|
|
264
|
-
| `chain-of-thought`
|
|
265
|
-
| `xml-tags`
|
|
266
|
-
| `few-shot`
|
|
267
|
-
| `role-assignment`
|
|
268
|
-
| `structured-output`
|
|
269
|
-
| `prefill`
|
|
270
|
-
| `prompt-chaining`
|
|
271
|
-
| `uncertainty-permission` | [Say "I Don't Know"](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/ask-claude-for-rewrites)
|
|
272
|
-
| `extended-thinking`
|
|
273
|
-
| `long-context-tips`
|
|
274
|
-
| `tool-use`
|
|
252
|
+
| ID | Name | Auto-selected when |
|
|
253
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
254
|
+
| `chain-of-thought` | [Let Claude Think](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-of-thought) | Analysis intent, complex tasks |
|
|
255
|
+
| `xml-tags` | [Use XML Tags](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags) | Long prompt + low structure score |
|
|
256
|
+
| `few-shot` | [Multishot Examples](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting) | Low example score + extraction/code |
|
|
257
|
+
| `role-assignment` | [System Prompts & Roles](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/system-prompts) | System intent or low specificity |
|
|
258
|
+
| `structured-output` | [Control Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/fill-in-the-blank) | Low output format score |
|
|
259
|
+
| `prefill` | [Structured Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prefill-claudes-response) | API target + extraction/code |
|
|
260
|
+
| `prompt-chaining` | [Chain Complex Tasks](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-prompts) | Complex + multiple subtasks |
|
|
261
|
+
| `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 |
|
|
262
|
+
| `extended-thinking` | [Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) | Complex + analysis/code intent |
|
|
263
|
+
| `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) |
|
|
264
|
+
| `tool-use` | [Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview) | Prompt mentions tool/function calling |
|
|
275
265
|
|
|
276
266
|
**Core algorithms:**
|
|
277
267
|
|
|
278
|
-
- **[Intent detection](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/analysis/detector.ts)** (`detectIntent`): Priority-ordered regex patterns across 6 categories
|
|
268
|
+
- **[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.
|
|
279
269
|
- **[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.
|
|
280
270
|
- **[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.
|
|
281
271
|
- **[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.
|
|
282
272
|
|
|
283
273
|
**Design principles:**
|
|
284
274
|
|
|
285
|
-
- **Single tool
|
|
286
|
-
- **Deterministic
|
|
287
|
-
- **Scaffold, not final
|
|
288
|
-
- **Lean output
|
|
289
|
-
- **Weighted dimensions
|
|
290
|
-
- **Technique cap
|
|
291
|
-
- **Anti-pattern detection
|
|
292
|
-
- **Zero dependencies
|
|
275
|
+
- **Single tool**: one entry point, minimal cognitive overhead
|
|
276
|
+
- **Deterministic**: same input, same output. No LLM calls, no network
|
|
277
|
+
- **Scaffold, not final**: the optimized prompt is structural; Claude adds substance
|
|
278
|
+
- **Lean output**: flat string arrays for issues/suggestions, no nested objects
|
|
279
|
+
- **Weighted dimensions**: clarity and specificity matter most (20% each)
|
|
280
|
+
- **Technique cap**: max 4 techniques per optimization (diminishing returns beyond)
|
|
281
|
+
- **Anti-pattern detection**: 12 Claude-specific anti-patterns + 20 industry patterns from 34 production AI tools
|
|
282
|
+
- **Zero dependencies**: only `@modelcontextprotocol/sdk` + `zod`
|
|
293
283
|
|
|
294
284
|
## alternatives
|
|
295
285
|
|
|
296
|
-
Every existing prompt optimization tool requires LLM calls, labeled datasets, or evaluation infrastructure. When you need structural improvement at zero latency
|
|
286
|
+
Every existing prompt optimization tool requires LLM calls, labeled datasets, or evaluation infrastructure. When you need structural improvement at zero latency (CI/CD, subagent dispatch, offline), they cannot help.
|
|
297
287
|
|
|
298
|
-
| Feature
|
|
299
|
-
|
|
300
|
-
| **Zero latency**
|
|
301
|
-
| **Offline/airgapped**
|
|
302
|
-
| **Deterministic**
|
|
303
|
-
| **No labeled data**
|
|
304
|
-
| **Claude-specific**
|
|
305
|
-
| **MCP native**
|
|
306
|
-
| **Structural scoring** | **7 dimensions**
|
|
307
|
-
| **Dependencies**
|
|
288
|
+
| Feature | **orator** | DSPy | promptfoo | TextGrad | OPRO | LLMLingua | Anthropic Generator |
|
|
289
|
+
| ---------------------- | ----------------------- | -------------- | --------------- | -------------- | -------------- | -------------- | ------------------- |
|
|
290
|
+
| **Zero latency** | **Yes (<1ms)** | No (LLM calls) | No (eval runs) | No (LLM calls) | No (LLM calls) | No (LLM calls) | No (LLM call) |
|
|
291
|
+
| **Offline/airgapped** | **Yes** | No | Partial | No | No | No | No |
|
|
292
|
+
| **Deterministic** | **Yes** | No | No | No | No | Partial | No |
|
|
293
|
+
| **No labeled data** | **Yes** | No (examples) | No (test cases) | No (feedback) | No (examples) | Yes | Yes |
|
|
294
|
+
| **Claude-specific** | **Yes (anti-patterns)** | No | No | No | No | No | Yes |
|
|
295
|
+
| **MCP native** | **Yes** | No | No | No | No | No | No |
|
|
296
|
+
| **Structural scoring** | **7 dimensions** | None | Custom metrics | None | None | None | None |
|
|
297
|
+
| **Dependencies** | **0 (pure TS)** | PyTorch + LLM | Node + LLM | PyTorch + LLM | LLM | PyTorch + LLM | LLM API |
|
|
308
298
|
|
|
309
|
-
**[DSPy](https://github.com/stanfordnlp/dspy)
|
|
299
|
+
**[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.
|
|
310
300
|
|
|
311
|
-
**[promptfoo](https://github.com/promptfoo/promptfoo)
|
|
301
|
+
**[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.
|
|
312
302
|
|
|
313
|
-
**[TextGrad](https://github.com/zou-group/textgrad)
|
|
303
|
+
**[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.
|
|
314
304
|
|
|
315
|
-
**[OPRO](https://github.com/google-deepmind/opro)
|
|
305
|
+
**[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.
|
|
316
306
|
|
|
317
|
-
**[LLMLingua](https://github.com/microsoft/LLMLingua)
|
|
307
|
+
**[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.
|
|
318
308
|
|
|
319
|
-
**[Anthropic Prompt Generator](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prompt-generator)
|
|
309
|
+
**[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.
|
|
320
310
|
|
|
321
|
-
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
|
|
311
|
+
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.
|
|
322
312
|
|
|
323
313
|
## development
|
|
324
314
|
|
|
@@ -332,7 +322,7 @@ npm test
|
|
|
332
322
|
|
|
333
323
|
- **Node.js**: >=20.0.0 (ES modules)
|
|
334
324
|
- **Runtime**: `@modelcontextprotocol/sdk`, `zod`
|
|
335
|
-
- **Zero external databases
|
|
325
|
+
- **Zero external databases**: works with `npx`
|
|
336
326
|
|
|
337
327
|
**Development workflow:**
|
|
338
328
|
|
|
@@ -345,7 +335,7 @@ npm run lint:fix # Auto-fix linting issues
|
|
|
345
335
|
npm run format # Prettier formatting (src/)
|
|
346
336
|
npm run format:check # Check formatting without changes
|
|
347
337
|
npm run typecheck # TypeScript validation without emit
|
|
348
|
-
npm run test # Lint + type check
|
|
338
|
+
npm run test # Lint + type check + vitest (25 tests)
|
|
349
339
|
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)
|
|
350
340
|
```
|
|
351
341
|
|
|
@@ -362,14 +352,29 @@ Learn from examples:
|
|
|
362
352
|
|
|
363
353
|
- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations
|
|
364
354
|
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices
|
|
355
|
+
- [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) for npm package development
|
|
365
356
|
- [Anthropic prompt engineering docs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) for technique details
|
|
366
357
|
|
|
358
|
+
## acknowledgments
|
|
359
|
+
|
|
360
|
+
Industry pattern data derived from deep analysis of system prompts from 34 AI coding tools
|
|
361
|
+
collected in [system-prompts-and-models-of-ai-tools](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools),
|
|
362
|
+
including Claude Code, Cursor, Windsurf, v0, Devin, Cline, Lovable, Replit, Amp, Gemini, and
|
|
363
|
+
25 others. Patterns are curated with prevalence data and embedded — no external dependency
|
|
364
|
+
or installation required. Cross-referenced with research from the
|
|
365
|
+
[Prompt Report](https://arxiv.org/abs/2406.06608) (1,500 papers surveyed) and
|
|
366
|
+
[Anthropic's prompt engineering documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).
|
|
367
|
+
|
|
367
368
|
## license
|
|
368
369
|
|
|
369
370
|
[MIT](LICENSE)
|
|
370
371
|
|
|
371
372
|
<hr>
|
|
372
373
|
|
|
373
|
-
<a href="https://en.wikipedia.org/wiki/Cicero_Denounces_Catiline"><img src="logo/maccari-cicero.jpg" alt="Cicero Denounces Catiline
|
|
374
|
+
<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>
|
|
375
|
+
|
|
376
|
+
<p align="center">
|
|
377
|
+
|
|
378
|
+
_**[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)._
|
|
374
379
|
|
|
375
|
-
|
|
380
|
+
</p>
|
|
@@ -7,7 +7,10 @@
|
|
|
7
7
|
* 3. Fallback heuristics: code blocks, "build me", debugging language → code before conversation
|
|
8
8
|
*/
|
|
9
9
|
import type { Complexity, Intent } from '../types.js';
|
|
10
|
+
export declare const INTENT_PATTERNS: [Intent, RegExp[]][];
|
|
10
11
|
/** Detect intent from prompt content with disambiguation and fallback heuristics. */
|
|
11
12
|
export declare function detectIntent(prompt: string): Intent;
|
|
13
|
+
/** Count how many distinct intent categories match the prompt. */
|
|
14
|
+
export declare function countIntentMatches(prompt: string): number;
|
|
12
15
|
/** Detect complexity based on word count and structural indicators. */
|
|
13
16
|
export declare function detectComplexity(prompt: string): Complexity;
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* 3. Fallback heuristics: code blocks, "build me", debugging language → code before conversation
|
|
8
8
|
*/
|
|
9
9
|
// Ordered by priority: most distinctive patterns first
|
|
10
|
-
const INTENT_PATTERNS = [
|
|
10
|
+
export const INTENT_PATTERNS = [
|
|
11
11
|
[
|
|
12
12
|
'system',
|
|
13
13
|
[
|
|
@@ -28,17 +28,25 @@ const INTENT_PATTERNS = [
|
|
|
28
28
|
/\brefactor\b/i,
|
|
29
29
|
/\bdebug\b/i,
|
|
30
30
|
/\bfix\s+(the\s+)?(bug|error|issue|crash)\b/i,
|
|
31
|
-
/\bcreate\s+(a\s+)?(\w+\s+)*(class|component|api|endpoint|module|service|app|application|middleware|hook|plugin|decorator|wrapper)\b/i,
|
|
32
|
-
/\
|
|
31
|
+
/\bcreate\s+(a\s+)?(\w+\s+)*(class|component|api|endpoint|module|service|app|application|middleware|hook|plugin|decorator|wrapper|tool|utility|cli|command|program)\b/i,
|
|
32
|
+
/\b(convert|transform|parse|migrate)\s+/i,
|
|
33
|
+
/\badd\s+(a\s+)?(method|function|handler|route|feature|caching|logging|validation|auth(entication)?|middleware|tests?|monitoring|pagination|search|sorting|filtering|indexing|endpoint|field|column|index|hook|event|listener|integration)\b/i,
|
|
33
34
|
/\bcode\s+(that|which|to)\b/i,
|
|
34
35
|
/\banalyze\s+(this\s+)?(code|function|class|module)\b/i,
|
|
35
36
|
/\breview\s+(this\s+)?(code|function|PR|pull\s+request|diff)\b/i,
|
|
36
|
-
/\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,
|
|
37
|
-
/\bmake\s+(me\s+)?(a\s+)?(\w+\s+)*(app|application|tool|script|server|client|cli|bot)\b/i,
|
|
38
|
-
/\bwrite\s+(me\s+)?(a\s+)?(\w+\s+)*(script|program|app|tool|cli|bot)\b/i,
|
|
37
|
+
/\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|form|file|config|system|pipeline|workflow|container|schema|template|component|view|screen|widget|layout|query|migration|chart|graph|table|image)\b/i,
|
|
38
|
+
/\bmake\s+(me\s+)?(a\s+)?(\w+\s+)*(app|application|tool|script|server|client|cli|bot|form|component|page|dashboard|system|workflow|pipeline)\b/i,
|
|
39
|
+
/\bwrite\s+(me\s+)?(a\s+)?(\w+\s+)*(script|program|app|tool|cli|bot|tests?|specs?|benchmarks?|function|class|method|module|handler|middleware|query|migration|hook|component|service)\b/i,
|
|
39
40
|
/\bwhat'?s?\s+wrong\s+with\b/i,
|
|
40
41
|
/\bhow\s+do\s+I\s+(fix|solve|implement|build|make|write|create)\b/i,
|
|
41
42
|
/\bhere'?s?\s+(my|the|some)\s+code\b/i,
|
|
43
|
+
// Infrastructure/DevOps verbs — need targets to avoid false positives
|
|
44
|
+
/\b(set\s+up|setup|configure)\s+(a\s+|the\s+|an\s+)?(\w+\s+){0,3}(docker|nginx|eslint|webpack|jest|prettier|ci\/?cd|pipeline|server|database|cluster|environment|container|k8s|kubernetes|monitoring|logging|terraform|ansible|redis|postgres|mysql|mongodb|api|service|auth(entication)?|ssl|tls|proxy|cache|caching|linter|formatter|bundler|compiler|runtime|framework|sdk|toolchain)\b/i,
|
|
45
|
+
/\b(deploy|migrate)\s+(the\s+|a\s+|an\s+|from\s+|to\s+)/i,
|
|
46
|
+
/\boptimize\s+(the\s+)?(\w+\s+)*(code|database|queries?|performance|build|bundle|app|application|algorithm|function|rendering|loading|memory|cpu|latency|throughput)\b/i,
|
|
47
|
+
/\bupdate\s+(the\s+)?(\w+\s+)*(code|schema|config(uration)?|dependency|dependencies|package|migration|module|component|library|framework|version|model|auth(entication)?)\b/i,
|
|
48
|
+
/\bdesign\s+(a\s+|the\s+)?(\w+\s+)*(database|schema|api|system|architecture|microservice|interface|component|module|class|data\s*model|erd|pipeline|protocol)\b/i,
|
|
49
|
+
/\binstall\s+(the\s+|a\s+|an\s+)?(\w+\s+)*(package|library|dependency|framework|tool|cli|sdk|runtime|module|plugin|extension)\b/i,
|
|
42
50
|
],
|
|
43
51
|
],
|
|
44
52
|
[
|
|
@@ -71,11 +79,11 @@ const INTENT_PATTERNS = [
|
|
|
71
79
|
[
|
|
72
80
|
'creative',
|
|
73
81
|
[
|
|
74
|
-
/\bwrite\s+(a\s+)?(story|poem|essay|blog|article|post|letter|email)\b/i,
|
|
82
|
+
/\bwrite\s+(me\s+)?(a\s+)?(story|poem|essay|blog|article|post|letter|email|haiku|sonnet|limerick|ballad|verse|screenplay|monologue|dialogue|lyric|song|novel|fiction|narrative)\b/i,
|
|
75
83
|
/\bbrainstorm\b/i,
|
|
76
84
|
/\bdraft\b/i,
|
|
77
85
|
/\bgenerate\s+(a\s+)?(name|title|tagline|slogan|headline)\b/i,
|
|
78
|
-
/\bcreate\s+(a\s+)?(story|narrative|description)\b/i,
|
|
86
|
+
/\bcreate\s+(a\s+)?(story|narrative|description|poem|haiku|song|screenplay)\b/i,
|
|
79
87
|
],
|
|
80
88
|
],
|
|
81
89
|
[
|
|
@@ -116,6 +124,10 @@ const CODE_FALLBACK_SIGNALS = [
|
|
|
116
124
|
/\bhere'?s?\s+(my|the|some)\s+code\b/i,
|
|
117
125
|
/\b(TypeError|SyntaxError|ReferenceError|Error|Exception|stack\s*trace|segfault)\b/,
|
|
118
126
|
/\b(npm|pip|cargo|yarn|pnpm|go\s+get|brew|apt|gem)\s+(install|add|run|build|test)\b/i,
|
|
127
|
+
// Targeted infrastructure signals (tool + action, not bare keywords)
|
|
128
|
+
/\b(docker|terraform|kubernetes|k8s|ansible)\s+(compose|build|run|file|config|deploy|apply|plan|init|image|volume|network)\b/i,
|
|
129
|
+
/\bwrite\s+(a\s+)?(\w+\s+)*(in|using|with)\s+(typescript|javascript|python|rust|go|java|ruby|php|swift|kotlin|c\+\+)\b/i,
|
|
130
|
+
/\b(cron\s*job|git\s*hook|pre-?commit|webhook|dockerfile|makefile|yaml\s*file|env\s*file)\b/i,
|
|
119
131
|
];
|
|
120
132
|
/** Detect intent from prompt content with disambiguation and fallback heuristics. */
|
|
121
133
|
export function detectIntent(prompt) {
|
|
@@ -141,6 +153,16 @@ export function detectIntent(prompt) {
|
|
|
141
153
|
}
|
|
142
154
|
return 'conversation';
|
|
143
155
|
}
|
|
156
|
+
/** Count how many distinct intent categories match the prompt. */
|
|
157
|
+
export function countIntentMatches(prompt) {
|
|
158
|
+
let count = 0;
|
|
159
|
+
for (const [, patterns] of INTENT_PATTERNS) {
|
|
160
|
+
if (patterns.some((p) => p.test(prompt))) {
|
|
161
|
+
count++;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return count;
|
|
165
|
+
}
|
|
144
166
|
/** Detect complexity based on word count and structural indicators. */
|
|
145
167
|
export function detectComplexity(prompt) {
|
|
146
168
|
const wordCount = prompt.split(/\s+/).filter(Boolean).length;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../src/analysis/detector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,uDAAuD;AACvD,MAAM,eAAe,GAAyB;
|
|
1
|
+
{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../src/analysis/detector.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,12 +3,18 @@
|
|
|
3
3
|
* All scoring is deterministic: same input always produces same output.
|
|
4
4
|
* Each dimension is 0-10, overall is weighted sum.
|
|
5
5
|
*/
|
|
6
|
-
import { type Scores } from '../types.js';
|
|
6
|
+
import { type AttributedIssue, type AttributedSuggestion, type Complexity, type Intent, type Scores, type SemanticHint } from '../types.js';
|
|
7
7
|
/** Score a prompt across all 7 dimensions. Returns individual scores. */
|
|
8
8
|
export declare function scorePrompt(prompt: string): Scores;
|
|
9
9
|
/** Compute weighted overall score from dimension scores. */
|
|
10
10
|
export declare function overallScore(scores: Scores): number;
|
|
11
11
|
/** Detect issues in the prompt as flat string descriptions. */
|
|
12
|
-
export declare function detectIssues(prompt: string, scores: Scores): string[];
|
|
12
|
+
export declare function detectIssues(prompt: string, scores: Scores, intent?: Intent): string[];
|
|
13
13
|
/** Generate actionable suggestions as flat strings. */
|
|
14
|
-
export declare function generateSuggestions(prompt: string, scores: Scores): string[];
|
|
14
|
+
export declare function generateSuggestions(prompt: string, scores: Scores, intent?: Intent): string[];
|
|
15
|
+
/** Detect issues with full attribution metadata. */
|
|
16
|
+
export declare function detectAttributedIssues(prompt: string, scores: Scores, intent?: Intent): AttributedIssue[];
|
|
17
|
+
/** Generate suggestions with full attribution metadata. */
|
|
18
|
+
export declare function generateAttributedSuggestions(prompt: string, scores: Scores, intent?: Intent): AttributedSuggestion[];
|
|
19
|
+
/** Generate semantic hints — meta-observations about analysis uncertainty for calling Claude. */
|
|
20
|
+
export declare function generateSemanticHints(prompt: string, scores: Scores, intent: Intent, complexity: Complexity): SemanticHint[];
|