prompt-improver

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4const COMMAND = 'improver'
5
6const isEnabled = atom({ plugin: 'prompt-improver', key: 'isEnabled' } as const, true)
7
8/**
9 * What the model reads beside the prompt. The prompt as typed stays the
10 * instruction; this block only asks the model to settle its reading first.
11 */
12const RUBRIC = [
13  '[prompt-improver] Before acting on the prompt above, read it against this conversation and settle, silently:',
14  '1. Goal: what the user most likely wants, with every "it", "this", "that" and any elided object resolved to the concrete thing already in the conversation.',
15  '2. Shape: what they expect back. An answer in chat, a code change, a file, a decision, or a question back to them.',
16  '3. Implicit constraints: what they would assume you already know. Project conventions, decisions made earlier in this session, and the language they typed in.',
17  '4. Ambiguity: at most one real fork in meaning. If the readings would lead to materially different work, ask instead of guessing.',
18  'The prompt as typed is the instruction and wins on any conflict; this note adds no requirement the user did not imply. Reply in the language the prompt was typed in.',
19  'Open the reply with one short line, "Reading this as: ...", only when you resolved a pronoun or an elided object, or chose between readings. On a clear prompt, no preamble.',
20].join('\n')
21
22/** Prompt origins that are not a person typing. The rubric is for typed prompts only. */
23const MACHINE_ORIGINS: ReadonlySet<string> = new Set([
24  'plugin',
25  'peer',
26  'peer-send-message',
27  'task-notification',
28  'scheduled-trigger',
29  'projects-relay',
30  'coordinator',
31  'observer',
32  'observer-activity',
33])
34
35const countWords = (text: string): number => text.trim().split(/\s+/).filter(Boolean).length
36
37const asCount = (value: unknown, fallback: number): number =>
38  typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
39
40export const register: Register = (on, options) => {
41  const minWords = asCount(options.minWords, 4)
42  const maxWords = asCount(options.maxWords, 40)
43
44  on('session.start', async ($, e, next) => {
45    await $.command.register({
46      name: COMMAND,
47      description: 'Toggle the prompt improver for this session: /improver [on|off|status]',
48    })
49
50    return next(e)
51  })
52
53  on('command.run', { command: COMMAND }, async ($, e) => {
54    const arg = e.args.trim().toLowerCase()
55    const current = await read($, isEnabled)
56    const wanted =
57      arg === 'on' ? true : arg === 'off' ? false : arg === '' || arg === 'status' ? current : null
58
59    if (wanted === null) {
60      return { text: `Usage: /${COMMAND} [on|off|status]` }
61    }
62    if (wanted !== current) {
63      await update($, isEnabled, () => wanted)
64    }
65
66    return { text: `Prompt improver is ${wanted ? 'on' : 'off'}.` }
67  }).catch(() => ({ text: 'Prompt improver: could not read or change its state.' }))
68
69  on('prompt.submit', async ($, e, next) => {
70    // A slash command, a prompt the person never typed, or a machine's delivery: untouched.
71    // The origin is always stamped in a session; the test kit may leave it out.
72    const origin = e.origin?.kind ?? 'composer'
73    if (e.command || e.isMeta || MACHINE_ORIGINS.has(origin)) {
74      return next(e)
75    }
76    if (!(await read($, isEnabled))) {
77      return next(e)
78    }
79
80    const words = countWords(e.text)
81    if (words < minWords || words > maxWords) {
82      return next(e)
83    }
84
85    return next({ ...e, context: [...(e.context ?? []), RUBRIC] })
86  }).catch(($, e, next) => next(e)) // fail open: a broken hook never blocks a prompt
87}
88

1declare module 'claude-code' {
2  interface PluginState {
3    'prompt-improver': { isEnabled: boolean }
4  }
5}
6