{ "markdown": "

\n \"Disambiguator\n

\n\n

Disambiguator

\n\n

\nA zero-dependency, pure instruction system prompt that intercepts ambiguous user instructions before any action is taken, surfaces assumptions as actionable multiple-choice options, and prevents wasted tokens and unintended code changes.\n

\n\n---\n\n## Why Disambiguator?\n\nAI coding assistants frequently rush into execution when handed vague instructions like *\"make the UI look nice\"* or *\"refactor the backend\"*. This leads to:\n- Wasted tokens rewriting files you didn't want touched\n- Hallucinated styling and unaligned architectural patterns\n- Silent drift and destructive unintended edits\n\n**Disambiguator acts as a zero-execution gatekeeper**: it halts the model before any tool execution, groups ambiguities by category, and generates realistic **multiple-choice suggestions (a/b/c/d)** so you can answer with just a letter instead of writing essays.\n\n---\n\n## Operating Modes\n\n| Mode | Type A (Subjectivity) | Type B (Scope) | Type C (Context Assumptions) |\n|---|---|---|---|\n| **`strict` (Default)** | Always halts | Always halts | Always halts |\n| **`soft`** | Always halts | Halts only on high-risk/destructive actions | Assumes safest standard, notes assumption, and proceeds |\n\n### Switching Modes at Runtime\nYou can switch modes on the fly in any agent conversation, terminal harness, or IDE without editing files:\n- Run `/disambiguator soft` to switch to soft mode.\n- Run `/disambiguator strict` to switch back to strict mode.\n- Run `/disambiguator off` to temporarily disable Disambiguator.\n- Run `/disambiguator status` to check the active mode.\n\nIn IDEs and skill-based agents (Cursor, Windsurf, Copilot, Antigravity, OpenCode, OpenChamber, etc.), you can also pick dedicated skills directly from autocomplete:\n- `/disambiguator-strict`: Instantly sets strict mode.\n- `/disambiguator-soft`: Instantly sets soft mode.\n- `/disambiguator-off`: Instantly disables gatekeeper.\n- `/disambiguator-status`: Displays the current active mode.\n\nTo change the permanent repository default, configure the top of [`system-prompt.md`](./system-prompt.md) and run `npm run sync`:\n```markdown\n# CONFIGURATION\n# MODE: strict <--- Change to \"soft\" to reduce interruptions\n```\n\n---\n\n## Install & Integration Tiers\n\nDisambiguator operates across three integration tiers depending on your agent harness's architecture:\n\n### Tier 1: Native Plugin & Lifecycle Hooks (Zero-Token Runtime Switching)\n\n#### Antigravity CLI (`agy`) & Antigravity IDE\n```bash\nagy plugin install https://github.com/agmonetti/disambiguator\n```\n*(On legacy Gemini CLI: `gemini extensions install https://github.com/agmonetti/disambiguator`).*\n\n- **Zero-Token Runtime Mode Switcher**: Toggle operational modes instantly in 0 ms without burning conversational tokens:\n ```bash\n npx @agmonetti/disambiguator strict # Enforce strict mode across ambiguities\n npx @agmonetti/disambiguator soft # Set soft mode (assume safest for Type C)\n npx @agmonetti/disambiguator off # Temporarily disable Disambiguator\n npx @agmonetti/disambiguator status # View active mode\n ```\n- **Antigravity Lifecycle Hook (`hooks.json`)**: Listens on `PreInvocation`, tracks slash commands (`/disambiguator strict|soft|off`), persists active mode, and injects ephemeral context notes.\n- **Native Workspace Rules (`.agents/rules/disambiguator.md`)**: Automatically loaded by Antigravity CLI and IDE with zero setup in cloned repositories.\n- **Marketplace Distribution**: Manifested in `.agents/plugins/marketplace.json` for seamless Antigravity plugin marketplace discovery.\n\n#### Pi Agent Harness\n```bash\npi install git:github.com/agmonetti/disambiguator\n```\n*(Or if running locally: `pi -e ./pi-extension/index.js`).*\n\n- **First-Class Slash Command**: Direct `/disambiguator [strict|soft|off|status]` command with argument autocomplete in Pi's terminal dropdown.\n- **Zero-Token Runtime Toggles**: Switching modes executes locally in 0 ms without sending conversational prompts or burning LLM tokens.\n- **Dual-Tier State Persistence**: Persists mode switches across Pi session journal and user configuration without polluting repository working trees.\n- **Terminal Status Bar**: Displays the live mode (`● disambiguator: Strict` / `Soft`) in the terminal footer.\n- **Dynamic Prompt Hook**: Injects or updates active mode directly on each turn via Pi's `before_agent_start` event.\n\n#### OpenCode\nAdd to `opencode.json`:\n```json\n{ \"plugin\": [\"@agmonetti/disambiguator\"] }\n```\nOr run directly from a local repository checkout:\n```json\n{ \"plugin\": [\"./.opencode/plugins/disambiguator.mjs\"] }\n```\n- **Transform Hook**: Injects Disambiguator into every chat turn with defensive array/string handling and idempotency to prevent duplicate prompts.\n- **Skills Catalog**: Automatically registers the full skills catalog (`disambiguator`, `disambiguator-strict`, `disambiguator-soft`).\n- **Slash Commands**: Exposes `/disambiguator [strict|soft|status|off]` and `/disambiguator-help`.\n- **Isolated Persistence**: Persists mode changes across sessions in `~/.config/opencode/.disambiguator-active`.\n\n---\n\n### Tier 2: Universal Rules & IDE Context (Always-On Workspace Gatekeeper)\n\n#### OpenChamber & VS Code\nOpenChamber and VS Code environments automatically discover and load `AGENTS.md` from your repository root with zero setup required. Drop `AGENTS.md` into your project root or clone this repository to activate Disambiguator immediately.\n\n#### Dedicated Editor Rules (Copy & Paste)\nFor editor environments with dedicated instruction directories, copy the matching rule file from this repo:\n\n| Editor / Environment | Target Path in Your Project | Global Path |\n|---|---|---|\n| **OpenChamber** | `AGENTS.md` | — |\n| **Cursor** | `.cursor/rules/disambiguator.mdc` | — |\n| **Codeium Windsurf** | `.windsurf/rules/disambiguator.md` | — |\n| **Cline / Roo-Code** | `.clinerules` | — |\n| **VS Code Copilot Chat** | `.github/copilot-instructions.md` | `~/.copilot/copilot-instructions.md` |\n| **Kiro** | `.kiro/steering/disambiguator.md` | `~/.kiro/steering/disambiguator.md` |\n| **Antigravity Workspace Rule** | `.agents/rules/disambiguator.md` | `~/.gemini/config/` |\n\n#### Zero-Setup Universal Context (`AGENTS.md`)\nThe following agents automatically discover and load `AGENTS.md` from your repository root:\n- **OpenChamber, Amp (Sourcegraph), Jules (Google), JetBrains Junie, VS Code with Codex extension, Zed, Qoder**.\n\n---\n\n### Tier 3: Assisted Configuration & Skills Catalog\n\n#### Claude Code\nInstall via plugin marketplace:\n```\n/plugin marketplace add agmonetti/disambiguator\n/plugin install disambiguator@disambiguator\n```\n*(You have to send two separate prompts for the install to work)*\n\n- **Slash Commands & Skills**: Registers `/disambiguator [strict|soft|status|off]` and the full skills catalog.\n- **Continuous Turn-by-Turn Protection**: Claude Code plugins register on-demand commands. To enforce Disambiguator as an always-on continuous gatekeeper across all prompts in your workspace, add `AGENTS.md` or append Disambiguator instructions to `CLAUDE.md` (or `~/.claude/CLAUDE.md`).\n\n#### Aider\nConfigure Aider to automatically load Disambiguator rules on every session:\n- In `.aider.conf.yml`:\n ```yaml\n read: [AGENTS.md]\n ```\n- Or pass via CLI:\n ```bash\n aider --read AGENTS.md\n ```\n\n#### Universal Agent Skills (`skills.sh` / `npx skills`)\nWorks across 70+ AI coding agents automatically:\n```bash\nnpx skills add agmonetti/disambiguator\n```\nTo install globally across all workspaces on your machine:\n```bash\nnpx skills add agmonetti/disambiguator -g\n```\n\n#### Other Supported Environments\n- **Codex CLI**: `codex plugin marketplace add agmonetti/disambiguator && codex plugin add disambiguator@disambiguator`\n- **GitHub Copilot CLI**: `/plugin marketplace add agmonetti/disambiguator && /plugin install disambiguator@disambiguator`\n- **Devin CLI**: `devin plugins install agmonetti/disambiguator`\n- **Hermes Agent**: `hermes plugins install agmonetti/disambiguator --enable`\n- **Swival**: `swival skills add --global https://github.com/agmonetti/disambiguator && swival skills add disambiguator`\n- **OpenClaw**: `clawhub install disambiguator`\n\n---\n\n### Generic Web LLMs (ChatGPT, Claude Web, LibreChat, OpenWebUI)\n1. Open [`system-prompt.md`](./system-prompt.md).\n2. Copy the full content.\n3. Paste into the **Custom Instructions**, **System Prompt**, or **Model Instructions** field of your preferred interface.\n\n---\n\n## Uninstall\n\n| Host | Command |\n|---|---|\n| **Claude Code** | `/plugin remove disambiguator` |\n| **Codex** | `codex plugin remove disambiguator` |\n| **Devin CLI** | `devin plugins remove disambiguator` |\n| **Pi agent** | `pi uninstall disambiguator` |\n| **Antigravity CLI** | `agy plugin remove disambiguator` |\n| **Agent Skills** | `npx skills remove disambiguator` |\n| **OpenClaw** | `clawhub uninstall disambiguator` |\n| **Cursor / Windsurf / Cline / OpenChamber / etc.** | Delete the copied rule file |\n\n---\n\n### Generic Web LLMs (ChatGPT, Claude Web, LibreChat, OpenWebUI)\n1. Open [`system-prompt.md`](./system-prompt.md).\n2. Copy the full content.\n3. Paste into the **Custom Instructions**, **System Prompt**, or **Model Instructions** field of your preferred interface.\n\n---\n\n## Uninstall\n\n| Host | Command |\n|---|---|\n| **Claude Code** | `/plugin remove disambiguator` |\n| **Codex** | `codex plugin remove disambiguator` |\n| **Devin CLI** | `devin plugins remove disambiguator` |\n| **Pi agent** | `pi uninstall disambiguator` |\n| **Antigravity CLI** | `agy plugin remove disambiguator` |\n| **Agent Skills** | `npx skills remove disambiguator` |\n| **OpenClaw** | `clawhub uninstall disambiguator` |\n| **Cursor / Windsurf / Cline / Qoder / etc.** | Delete the copied rule file |\n\n---\n\n\n## How It Works in Practice\n\n### Ambiguity Taxonomy\n\n- **Type A — Pure Subjectivity**: Unmeasurable adjectives (*\"clean\"*, *\"modern\"*, *\"elegant\"*, *\"faster\"*).\n- **Type B — Undefined Scope**: Unbounded targets or open-ended verbs (*\"fix the UI\"*, *\"refactor the code\"*, *\"clean up tests\"*).\n- **Type C — Missing Context**: Unspecified dependencies, stacks, or target files when multiple valid choices exist.\n\n### Example Interaction\n\n**User:**\n> *\"Update the landing page UI so it looks clean and modern.\"*\n\n**Disambiguator Response:**\n```markdown\nBefore proceeding, I found 3 items to clarify:\n\n1. **\"the landing page UI\"** (Type B — Undefined Scope) — The page contains multiple independent sections.\n\n - **a)** The entire page (Hero, Features, Pricing, and Footer)\n - **b)** Header and Hero section only\n - **c)** Content and conversion sections (Features and CTA)\n - **d) Other** — (specify target sections)\n\n2. **\"clean\"** (Type A — Pure Subjectivity) — No measurable aesthetic standard was provided.\n\n - **a)** Minimalist layout with generous whitespace and high-contrast typography\n - **b)** Subtle borders, soft background tones, and reduced element density\n - **c)** Structured corporate layout with clear grid dividers\n - **d) Other** — (describe your preferred style)\n\n3. **\"modern\"** (Type A — Unspecified Reference) — No design reference was specified.\n\n - **a)** Linear / Vercel style (subtle dark theme, fine borders, monochrome accents)\n - **b)** Glassmorphism with soft gradients and rounded corners\n - **c)** Geometric flat design with crisp edges\n - **d) Other** — (share a reference URL or design guideline)\n\nReply with your selected options (e.g., 1a, 2b, 3a) or describe your preferences to proceed.\n```\n\n---\n\n\n## Edge Case Protocols\n\nDisambiguator includes a prioritized 10-point robustness protocol to prevent deadlocks and maintain user trust:\n\n1. **\"Just assume\" override**: Maps to the safest, most conservative option (option `a`), states it explicitly in one line, and proceeds immediately without further questions.\n2. **Chained ambiguities (2-round limit)**: Imposes a hard limit of two clarification rounds. Round 1 presents primary ambiguities; Round 2 resolves any direct followup ambiguity. If ambiguity remains after Round 2, the safest conservative choice is applied with an explicit declaration.\n3. **Mid-clarification cancellation & partial answers**: If a user answers only one question and requests immediate action, unaddressed Type B/C items apply safe fallbacks with a 1-line declaration, while unaddressed Type A (subjectivity) items halt again to request the missing criterion.\n4. **Pseudo-technical buzzword blacklist**: Generic terms like *\"clean code\"*, *\"best practices\"*, *\"enterprise-grade\"*, and *\"scalable\"* are treated as Type A subjectivity unless grounded in concrete standards.\n5. **Nested ambiguity deconstruction**: When an instruction relies on a relative comparison anchored to an undefined baseline (*\"more professional than the current version\"*), it separates the baseline from the target criteria into a single coordinated item.\n6. **Overload triage (Phase 1 vs. Phase 2)**: When 4 or more ambiguities arise, core architectural choices are grouped into Phase 1 (max 3 questions), deferring visual styling and micro-details to Phase 2.\n7. **Scope shift recognition**: When a user's clarifying response expands scope (e.g., *\"actually redesign the entire auth flow\"*), it is recognized as a new request rather than an answer, resetting analysis without loops.\n8. **Conversational silence & implicit prompts**: When an asset (snippet, stack trace, image) is shared without an explicit action verb, Disambiguator prompts for the user's intent first rather than hallucinating options.\n9. **Mixed prompts / partial stops (deterministic core + ambiguous expansion)**: When an instruction pairs an unambiguous command with an ambiguous goal, Disambiguator decouples code output, acknowledges the unambiguous segment as identified/staged, halts tool execution, and clarifies only the ambiguous remainder.\n10. **Operational mode interactions (`strict`, `soft`, `off`)**: In `strict` mode, edge cases enforce halting on all ambiguity types; in `soft` mode, Type C and localized low-risk Type B adopt Option `a` automatically with a 1-line notice, reserving halts exclusively for Type A and high-risk destructive actions.\n\n---\n\n## Automated Test Runner & Benchmarks\n\nDisambiguator provides both an **instant offline test suite** and a standardized **multi-provider LLM-as-a-judge** evaluation harness.\n\n### 1. Instant Offline Test Suite (< 50ms)\nValidates parser schema, YAML assertion integrity, and zero-drift harness parity across all 20 adapters using Python's standard library:\n\n```bash\npython3 -m unittest discover -v -s tests\n\n# or execute both Python and Node test suites together:\nnpm test\n```\n\n### 2. Multi-Provider Automated LLM Runner\nEvaluates 20 real-world benchmark cases through a target model and grades compliance using an LLM judge (`tests/runner.py`).\n\n- **Zero Mandatory Dependencies**: Built entirely on Python standard library modules (`urllib`, `json`, `re`, `pathlib`, `unittest`).\n- **Universal Provider Support**: Native REST drivers for Google Gemini, OpenAI, Anthropic Claude, and local OpenAI-compatible runners (Ollama, Groq, DeepSeek, vLLM).\n- **Machine-Evaluable Assertions**: 20 test cases in [`tests/test-cases.md`](./tests/test-cases.md) specifying unambiguous evaluation schemas (`contains_question`, `min_questions`, `no_code_executed`, `ambiguity_types_flagged`, `proceeds_directly`, `aviso_emitido`, `partial_stop`).\n\n#### Running the Test Suite Locally\n\nConfigure environment variables in a `.env` file or export them directly:\n\n```bash\n# Example 1: Run with Google Gemini (default)\nGEMINI_API_KEY=\"your-api-key\" python3 tests/runner.py\n\n# Example 2: Run with local Ollama (zero API costs)\nPROVIDER=ollama OPENAI_BASE_URL=http://localhost:11434/v1 TEST_MODEL=llama3.2 python3 tests/runner.py\n\n# Example 3: Run with OpenAI\nPROVIDER=openai OPENAI_API_KEY=\"sk-...\" TEST_MODEL=gpt-4o-mini python3 tests/runner.py\n\n# Example 4: Run with Anthropic Claude\nPROVIDER=anthropic ANTHROPIC_API_KEY=\"sk-ant-...\" python3 tests/runner.py\n```\n\nResults are dumped to `results.json` with per-assertion verdicts, judge reasoning, and summary metrics.\n\n---\n\n## Design Decisions & Limitations\n\n- **Cognitive Gatekeeper vs. Tool Execution**: Disambiguator evaluates intent, gatekeeping rules, and ambiguity taxonomy. It does not contain language-specific execution tools. When hosted in an agentic IDE (Cursor, Claude Code, AGY CLI), modifying tools execute directly; in raw chat interfaces, actions are emitted as declarative diffs and execution plans.\n- **Decoupled Code Output in Partial Stops**: In mixed prompts where the model pauses for an ambiguous segment while identifying a deterministic core, code generation in the same turn is not required. A declarative statement identifying the active part suffices, avoiding unintended half-executions.\n- **Language Adaptation**: Prompts are matched dynamically. Spanish user prompts yield Spanish clarifying options; English prompts yield English options. No separate localized prompt files are required.\n\n---\n\n## Maintainers & Anti-Drift Architecture\n\nDisambiguator maintains strict parity across all 20 harness adapters (`AGENTS.md`, `SKILL.md`, `.cursor/rules/`, `.windsurf/rules/`, `.clinerules`, `.github/copilot-instructions.md`, `.kiro/steering/disambiguator.md`, `skills/*`, `commands/*`, `.opencode/*`, etc.).\n\nThe single canonical source of truth is always [`system-prompt.md`](./system-prompt.md).\n\n```bash\n# Synchronize all adapters after editing system-prompt.md\npython3 scripts/sync.py\n\n# Verify parity in CI or locally (fails with code 1 if drift is detected)\npython3 scripts/sync.py --check\n```\n\nContinuous integration runs `.github/workflows/sync-check.yml` on every pull request to enforce zero drift.\n\n---\n\n## License\n\n\nMIT License. Free for personal and commercial use.\n\n", "bytes": 17957, "sha": "bdd7ae987d341df2def37d1510101faf360666306679c261b53f72239cfb829e", "repo_slug": "agmonetti/disambiguator", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_agmonetti_disambiguator_44908ed0/readme" }