{"_id":"@bulga138/peso","_rev":"2-10cdf0108edd488b509929aa392a01f6","name":"@bulga138/peso","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@bulga138/peso","version":"0.1.0","_id":"@bulga138/peso@0.1.0","maintainers":[{"name":"bulga138","email":"bulga.sl@hotmail.com"}],"homepage":"https://github.com/bulga138/peso#readme","bugs":{"url":"https://github.com/bulga138/peso/issues"},"dist":{"shasum":"b6375f7e43f6b225d90d6a2125f8d0f8e238c646","tarball":"https://registry.npmjs.org/@bulga138/peso/-/peso-0.1.0.tgz","fileCount":6,"integrity":"sha512-SX6PJXxF9H3IdhyvzKxOcz7Jp7UHoyLChKxAUNQmHiIalkto1WJvMDriRA5UY/hvdQhsaONMrUrslGmqPruXRA==","signatures":[{"sig":"MEUCIAoazqiC79cjiQeKqa6L3IP0Vic4p+dls8pgoKS994EgAiEApmtc2P/ZfJq/nf8PWmoUtMAVzOKxZQXWI5xetI+v1Ok=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4243834},"main":"src/index.ts","type":"module","exports":{".":"./src/index.ts"},"gitHead":"377695010df6084c3d5703c7b25f9d758d2a54ad","scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/index.ts","build":"bun build src/index.ts --outdir dist --target node","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bulga138","email":"bulga.sl@hotmail.com"},"repository":{"url":"git+https://github.com/bulga138/peso.git","type":"git"},"_npmVersion":"11.7.0","description":"Prompt Engineering Smart Optimizer — OpenCode plugin","directories":{},"_nodeVersion":"22.14.0","dependencies":{"@opencode-ai/plugin":"latest"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/peso_0.1.0_1778196967194_0.26579137550844933","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@bulga138/peso","version":"0.2.0","description":"Prompt Engineering Smart Optimizer — OpenCode plugin","type":"module","main":"src/index.ts","exports":{".":"./src/index.ts"},"repository":{"type":"git","url":"git+https://github.com/bulga138/peso.git"},"scripts":{"build":"bun build src/index.ts --outdir dist --target node","cli":"bun run src/cli.ts","dev":"bun run src/index.ts","lint":"eslint .","lint:fix":"eslint . --fix && prettier --write .","typecheck":"tsc --noEmit"},"dependencies":{"@opencode-ai/plugin":"latest"},"devDependencies":{"@eslint/js":"10.0.1","@types/bun":"latest","@typescript-eslint/eslint-plugin":"8.59.2","@typescript-eslint/parser":"8.59.2","eslint":"10.3.0","globals":"17.6.0","prettier":"3.8.3","typescript":"6.0.3"},"gitHead":"9e96a5a53386832d7f1246a4de5d83bd7b115041","_id":"@bulga138/peso@0.2.0","bugs":{"url":"https://github.com/bulga138/peso/issues"},"homepage":"https://github.com/bulga138/peso#readme","_nodeVersion":"22.14.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-RNOFS8PcY25HXSx+Wyb04bqHoU48/8m2CfICaDqEoJvdDpK8dUuwYsIRJyzNGZK0AbZo5Gtnh0kF1HJVB8XmWA==","shasum":"4496e95a076eb2413dee17f81715e86d9a319f88","tarball":"https://registry.npmjs.org/@bulga138/peso/-/peso-0.2.0.tgz","fileCount":6,"unpackedSize":4257900,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAI6u/F6X9Cm2JXf1MShP6YBtj8Zr75rF4zljYR9Xdb4AiBU75K/Othsj3sH/ELCU/FgW8hq0mOCgGFgWlC5uhXprg=="}]},"_npmUser":{"name":"bulga138","email":"bulga.sl@hotmail.com"},"directories":{},"maintainers":[{"name":"bulga138","email":"bulga.sl@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/peso_0.2.0_1778278524032_0.587973800561971"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T23:36:07.071Z","modified":"2026-05-08T22:15:24.488Z","0.1.0":"2026-05-07T23:36:07.498Z","0.2.0":"2026-05-08T22:15:24.378Z"},"bugs":{"url":"https://github.com/bulga138/peso/issues"},"homepage":"https://github.com/bulga138/peso#readme","repository":{"type":"git","url":"git+https://github.com/bulga138/peso.git"},"description":"Prompt Engineering Smart Optimizer — OpenCode plugin","maintainers":[{"name":"bulga138","email":"bulga.sl@hotmail.com"}],"readme":"![peso-banner](./assets/banner.png)\r\n\r\n# PESO\r\n\r\n**Prompt Engineering Smart Optimizer**\r\n\r\nAn OpenCode plugin that enhances prompts using a configurable small/cheap model before they reach your main (expensive) model.\r\n\r\n## How it works\r\n\r\n```\r\nUser types prompt\r\n      ↓\r\n  PESO plugin (chat.message hook)\r\n      ↓  short prompt? → intent detection (fix/explain/refactor/…) → expand\r\n      ↓  classifies prompt (rule-based, zero cost)\r\n      ↓  Agent Compass: reads agent permissions → sets intensity\r\n      ↓  10-stage pipeline + 26 VILA-Lab techniques (model-tier-aware)\r\n      ↓  style directives → system prompt; user prompt stays clean\r\n      ↓  if use_llm: calls small model via SDK for domain-specific rewrite\r\n      ↓         quality gate: keeps winner of (original, pipeline, llm)\r\n      ↓  injects context (git, tools, MCP tools)\r\n      ↓  mutates prompt → main model receives enhanced version\r\n      ↓  UI feedback line appended (score delta, techniques count, domain)\r\n```\r\n\r\n### Modes\r\n\r\n| Mode      | Behavior                                                   |\r\n| --------- | ---------------------------------------------------------- |\r\n| `on`      | Transparent — all prompts enhanced automatically (default) |\r\n| `passive` | Only enhances when agent explicitly calls the `peso` tool  |\r\n| `off`     | Fully disabled                                             |\r\n\r\nSet via `PESO_MODE=passive` env at startup, or toggle at runtime with the `peso-toggle` tool.\r\n\r\n### Agent Compass\r\n\r\nPESO reads real agent permissions from the SDK to determine enhancement intensity:\r\n\r\n| Agent Profile       | Permissions            | Intensity |\r\n| ------------------- | ---------------------- | --------- |\r\n| Plan (read-only)    | edit:deny, bash:deny   | Light     |\r\n| Build (full access) | edit:allow, bash:allow | Full      |\r\n| Explore (search)    | edit:deny, bash:ask    | None      |\r\n| General             | mixed                  | Medium    |\r\n\r\n## Installation\r\n\r\n```json\r\n{\r\n  \"$schema\": \"https://opencode.ai/config.json\",\r\n  \"plugin\": [\"@bulga138/peso\"]\r\n}\r\n```\r\n\r\n## Configuration\r\n\r\n### Model Resolution\r\n\r\nIn plugin mode, PESO uses the OpenCode SDK to resolve the model — no API keys or base URLs needed:\r\n\r\n| Priority | Source                                | Example                                         |\r\n| -------- | ------------------------------------- | ----------------------------------------------- |\r\n| 1        | `PESO_MODEL` env var                  | `export PESO_MODEL=groq/llama-3.1-8b-instant`   |\r\n| 2        | SDK: `small_model` in `opencode.json` | `\"small_model\": \"anthropic/claude-haiku-4-5\"`   |\r\n| 3        | SDK auto-detection                    | OpenCode picks cheapest model for your provider |\r\n| 4        | SDK: `model` in `opencode.json`       | Falls back to main model                        |\r\n| 5        | Hardcoded fallback                    | `opencode/zen` (free, always available)         |\r\n\r\n> **Note:** In plugin mode (the default), all auth and routing is handled by the OpenCode SDK via `client.session.prompt()`. The `PESO_API_KEY` and `PESO_BASE_URL` env vars only apply to the standalone CLI fallback path.\r\n\r\n### Example opencode.json\r\n\r\n```json\r\n{\r\n  \"$schema\": \"https://opencode.ai/config.json\",\r\n  \"model\": \"anthropic/claude-sonnet-4-5\",\r\n  \"small_model\": \"anthropic/claude-haiku-4-5\"\r\n}\r\n```\r\n\r\nPESO will automatically use `claude-haiku-4-5` for enhancement work.\r\n\r\n### Config File (`peso.json`)\r\n\r\nPESO loads config from two locations (deep-merged):\r\n\r\n1. `~/.config/peso/peso.json` — global defaults\r\n2. `<project>/peso.json` — project overrides\r\n\r\n```json\r\n{\r\n  \"mode\": \"passive\",\r\n  \"shortPromptThreshold\": 15,\r\n  \"toolPriorities\": {\r\n    \"prefer\": [\"read\", \"glob\", \"grep\", \"serena_find_symbol\"],\r\n    \"avoid\": [\"task\", \"webfetch\", \"websearch\"]\r\n  },\r\n  \"techniques\": {\r\n    \"enabled\": \"all\",\r\n    \"disabled\": [\"emotional-stimuli\"]\r\n  },\r\n  \"techniquePacks\": {\r\n    \"enabled\": \"all\",\r\n    \"disabled\": []\r\n  },\r\n  \"context\": {\r\n    \"injectGit\": true,\r\n    \"injectMcpTools\": true,\r\n    \"maxChangedFiles\": 10\r\n  },\r\n  \"options\": {\r\n    \"baseURL\": \"{env:ANTHROPIC_URL}\",\r\n    \"apiKey\": \"{env:ANTHROPIC_AUTH_TOKEN}\"\r\n  }\r\n}\r\n```\r\n\r\n**Tool priorities** tell the model which tools are cheap (prefer) vs expensive (avoid). This gets injected as `<prefer-tools>` and `<avoid-tools>` in the context block, nudging the model to use `read`/`glob`/`grep` before spawning a `task` subagent.\r\n\r\n**`toolPriorities.mode`**:\r\n\r\n- `\"manual\"` (default) — only tools listed in `prefer`/`avoid` are hinted\r\n- `\"mcp-first\"` — all MCP tools auto-added to `prefer` (favors MCP over native OpenCode tools)\r\n\r\nRun `peso-config` to see all available tools and set up your priorities.\r\n\r\n**`techniquePacks`** (optional): controls which globally-installed technique packs are active for this project. Packs are `.js` files placed in `~/.config/peso/packs/`. See [Extensible Techniques](#extensible-techniques) below.\r\n\r\n### Environment Variables\r\n\r\n| Variable        | Purpose                                         | Default         |\r\n| --------------- | ----------------------------------------------- | --------------- |\r\n| `PESO_MODE`     | Set mode at startup: `on`, `passive`, `off`     | `on`            |\r\n| `PESO_AUTO`     | Set to `0` to disable (same as `PESO_MODE=off`) | —               |\r\n| `PESO_MODEL`    | Override model for enhancement                  | SDK auto-detect |\r\n| `PESO_API_KEY`  | API key for CLI fallback path only              | —               |\r\n| `PESO_BASE_URL` | Base URL for CLI fallback path only             | —               |\r\n\r\n> In plugin mode, `PESO_API_KEY` and `PESO_BASE_URL` are not needed — the SDK handles auth.\r\n\r\n## Tools Provided\r\n\r\n### `peso`\r\n\r\nFull enhancement pipeline. Classifies the prompt, applies research-backed techniques, optionally calls the small model for a complete rewrite.\r\n\r\n```\r\nUse the peso tool to enhance: \"fix the login bug\"\r\n```\r\n\r\nArguments:\r\n\r\n- `prompt` (required): The prompt to enhance\r\n- `mode` (optional): `auto` | `code` | `general` | `creative` | `research`\r\n- `use_llm` (optional): Whether to call the small model (default: true)\r\n\r\n### `peso-score`\r\n\r\nScore a prompt 0-10 without modifying it. Shows rule violations and dimension breakdown.\r\n\r\n### `peso-debug`\r\n\r\nRun the full pipeline with trace output: classification, techniques applied, before/after scores, agent compass vector, LLM call result.\r\n\r\n### `peso-toggle`\r\n\r\nSwitch PESO mode at runtime:\r\n\r\n```\r\npeso-toggle passive   # only enhances when agent calls peso tool\r\npeso-toggle on        # transparent enhancement (default)\r\npeso-toggle off       # fully disabled\r\npeso-toggle           # show current mode\r\n```\r\n\r\n### `peso-config`\r\n\r\nShow current configuration: SDK-resolved model, local fallback model, API key status, agent compass table with per-agent intensities.\r\n\r\n## Performance\r\n\r\nPESO uses aggressive caching to minimize overhead:\r\n\r\n| Data                            | Strategy                          | Cost on cache hit |\r\n| ------------------------------- | --------------------------------- | ----------------- |\r\n| CLI tools (`git`, `node`, etc.) | Session-scoped (never re-checked) | 0                 |\r\n| Git branch                      | `.git/HEAD` mtime check           | 1 `stat` call     |\r\n| Git changed files               | `.git/index` mtime check          | 1 `stat` call     |\r\n| Git recent commit               | `.git/HEAD` mtime check           | 1 `stat` call     |\r\n| Agent list                      | Cached after first SDK call       | 0                 |\r\n| MCP/plugin tool IDs             | Cached after first SDK call       | 0                 |\r\n\r\n**Typical per-message overhead: <1ms** (no shell forks, no network) unless git state actually changed.\r\n\r\n## Context Injection\r\n\r\nPESO injects a `<peso:context>` block into enhanced prompts:\r\n\r\n```xml\r\n<peso:context>\r\n  <date>2026-05-07</date>\r\n  <cwd>/Users/you/project</cwd>\r\n  <git-branch>feat/my-feature</git-branch>\r\n  <git-changed-files>src/index.ts, src/utils.ts</git-changed-files>\r\n  <available-tools>git, bun, node, npm, npx, curl, jq</available-tools>\r\n  <mcp-tools>bash, read, glob, grep, edit, write, task, webfetch, peso, ...</mcp-tools>\r\n  <project-instructions>true</project-instructions>\r\n</peso:context>\r\n```\r\n\r\n- `<mcp-tools>` lists all MCP + plugin tools from the SDK (not just CLI binaries)\r\n- `<project-instructions>` signals when CLAUDE.md / .cursorrules exist (avoids redundant injections)\r\n- `<freshness-warning>` added when prompt references \"latest\", \"current\", or future dates\r\n\r\n## What it enhances\r\n\r\n### Rule-based (free, always runs):\r\n\r\n- Position sensitivity: critical instructions moved to first 15%\r\n- Nesting depth check (max 4 levels)\r\n- Instruction ratio optimization (40-50%)\r\n- Duplicate rule consolidation\r\n- Priority statement injection\r\n- 26 VILA-Lab principled techniques (auto-selected by domain and model tier)\r\n\r\n### Model-tier-aware filtering\r\n\r\nPESO detects the active model and skips techniques that add noise for capable models:\r\n\r\n| Tier       | Models                              | Behavior                                                             |\r\n| ---------- | ----------------------------------- | -------------------------------------------------------------------- |\r\n| `frontier` | Opus, GPT-4o, o1/o3, Gemini 2.5 Pro | Minimal injection — only task-specific techniques (verify, examples) |\r\n| `standard` | Sonnet, GPT-4-turbo                 | Same as frontier — style directives go to system prompt only         |\r\n| `small`    | Haiku, GPT-4o-mini, Gemini Flash    | Full injection — includes step-by-step, chain-of-thought, decompose  |\r\n\r\nStyle/constraint directives (`constraints`, `brevity`, `output-length`, `scope-limit`, `language-spec`, `positive-framing`) always go to the **system prompt**, never the user prompt. This keeps user prompts clean and avoids wasting input tokens on every message.\r\n\r\nReasoning nudges (`step-by-step`, `emotional-stimuli`, `chain-of-thought`, `decompose`) only fire for `small` models where they measurably help\r\n\r\n### LLM-based (costs small-model tokens):\r\n\r\n- Full prompt rewrite preserving intent, using a **domain-specific system prompt** (code/research/creative/general)\r\n- **Quality gate:** scores the original, pipeline output, and LLM rewrite — keeps the highest-scoring version. Falls back to the original if both enhancements score lower.\r\n- Context-aware restructuring\r\n\r\n### Short-prompt expansion\r\n\r\nPrompts of 6 words or fewer are matched against a set of verb-first intent patterns before entering the pipeline:\r\n\r\n| Input                | Expanded to                                                                                                             |\r\n| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |\r\n| `fix login`          | `Fix the issue with login. Identify the root cause, explain what is wrong, and provide the corrected code.`             |\r\n| `refactor auth`      | `Refactor auth. Improve readability and reduce complexity while maintaining the same behaviour. Show before and after.` |\r\n| `explain middleware` | `Explain how middleware works. Cover the key logic, data flow, and any non-obvious behaviour.`                          |\r\n\r\nRecognised verbs: `fix`, `explain`, `refactor`, `add`, `remove`, `test`, `debug`, `update`, `implement`, `review`. Single-word non-verb prompts (e.g. `hello`) are still skipped.\r\n\r\n### Inline feedback\r\n\r\nAfter each transparent enhancement (mode `on`), PESO appends a UI-visible, LLM-hidden feedback line:\r\n\r\n```\r\n✦ peso: 5.8→8.1 (+2.3) | 4 techniques | code/medium\r\n```\r\n\r\nThis line uses the `ignored: true` SDK part flag — it appears in the OpenCode UI but is never sent to the model.\r\n\r\n## Extensible Techniques\r\n\r\nYou can add your own technique packs without modifying PESO's source. Packs are installed globally and each project controls which are active.\r\n\r\n### 1. Create a pack file\r\n\r\n```js\r\n// ~/.config/peso/packs/security.js\r\nexport default {\r\n  name: 'security-pack',\r\n  version: '1.0.0',\r\n  techniques: [\r\n    {\r\n      id: 'security-review',\r\n      name: 'Security Review Nudge',\r\n      description: 'Flags security concerns for auth/token prompts',\r\n      domains: ['code'],\r\n      applies: prompt => /auth|login|password|token|secret/i.test(prompt),\r\n      inject: prompt =>\r\n        prompt + '\\n\\nIMPORTANT: Review for security vulnerabilities (injection, XSS, auth bypass, secrets exposure).',\r\n    },\r\n  ],\r\n};\r\n```\r\n\r\n### 2. Drop it in the global packs directory\r\n\r\n```bash\r\nmkdir -p ~/.config/peso/packs\r\ncp security.js ~/.config/peso/packs/\r\n```\r\n\r\nPESO auto-discovers all `.js` files in `~/.config/peso/packs/` at startup. No registration needed — just drop the file.\r\n\r\n### 3. Control per project\r\n\r\nBy default, all discovered packs are loaded. Use the project's `peso.json` to filter:\r\n\r\n```json\r\n{\r\n  \"techniquePacks\": {\r\n    \"enabled\": \"all\",\r\n    \"disabled\": [\"noisy-pack\"]\r\n  }\r\n}\r\n```\r\n\r\n| Config                                    | Effect                                                 |\r\n| ----------------------------------------- | ------------------------------------------------------ |\r\n| `\"enabled\": \"all\"`                        | Load all discovered packs (default)                    |\r\n| `\"enabled\": [\"security-pack\"]`            | Load only named packs                                  |\r\n| `\"disabled\": [\"noisy-pack\"]`              | Exclude specific packs (takes precedence over enabled) |\r\n| `\"disabled\": [\"security-pack/xss-check\"]` | Disable a single technique within a pack               |\r\n\r\nThe global `~/.config/peso/peso.json` can also set `techniquePacks.disabled` to block packs across all projects.\r\n\r\n> **Security note:** Pack files are executed as real JavaScript modules via dynamic `import()`. Only load packs from sources you trust.\r\n\r\n## Inspirations\r\n\r\n| Source                                                                                      | Contribution                               |\r\n| ------------------------------------------------------------------------------------------- | ------------------------------------------ |\r\n| [mtayfur/opencode-prompt-enhancer](https://github.com/mtayfur/opencode-prompt-enhancer)     | Plugin pattern, workspace context          |\r\n| [diegohb gist](https://gist.github.com/diegohb/5bbe7bfa48900e302aa99a2b2760b05a)            | Argument intelligence                      |\r\n| [lim-hyo-jeong/Prompt-Enhancer](https://github.com/lim-hyo-jeong/Prompt-Enhancer)           | 26 VILA-Lab principles                     |\r\n| [meta-introspector dotfiles](https://github.com/meta-introspector/benbrastmckie-dotfiles)   | 10-stage pipeline, scoring                 |\r\n| [ruhanirabin/vscode-prompt-enhancer](https://github.com/ruhanirabin/vscode-prompt-enhancer) | Template system                            |\r\n| DeepMind OPRO                                                                               | Step-by-step breathing (small models only) |\r\n| Microsoft Research                                                                          | Emotional stimuli (small models only)      |\r\n| Stanford/Anthropic                                                                          | Position sensitivity                       |\r\n| Anthropic Prompting Best Practices (2026)                                                   | Model-tier-aware technique filtering       |\r\n","readmeFilename":"README.md"}