pi-must-have-extension

Normalize RFC 2119/8174 and BCP 14-adjacent language in Pi prompts by automatically rewriting lowercase modal terms (must, should not, optional) and common variants (mustn't, ought not, not allowed) into uppercase normative forms (MUST, SHOULD NOT, OPTIONAL, MUST NOT, NOT ALLOWED).

Demo

Features

• RFC 2119/8174 compliance — Transforms modal keywords to standard uppercase notation
• Expanded wording coverage — Includes contractions and adjacent policy terms such as mandatory, mustn't, ought not, not allowed, prohibited, and forbidden
• Intelligent matching — Case-insensitive with longest-first phrase replacement
• Word-boundary aware — Does not replace keywords embedded inside larger words
• Configurable replacements — Customize or extend the default keyword mappings
• Input filtering — Leaves slash commands (/) and shell input (!) unchanged
• Auto-configuration — Creates a default config file when none exists
• Legacy migration — Automatically migrates configs from previous plugin versions
• Debug mode — Optional file-backed debug logging for config and replacement details without terminal output

Installation

Local Extension Folder

Copy this repository to one of the following locations:

~/.pi/agent/extensions/pi-must-have-extension     # Global default (when PI_CODING_AGENT_DIR is unset)
.pi/extensions/pi-must-have-extension             # Project-specific

Pi will auto-discover the extension on startup.

NPM Package

pi install npm:pi-must-have-extension

Usage

Once installed, the extension works automatically. When you type prompts containing RFC 2119 keywords:

Input:

The function must validate input and should log errors.

Transformed to:

The function MUST validate input and SHOULD log errors.

Skipped Input

The extension does not transform:

• Slash commands (e.g., /help, /reload)
• Shell commands (e.g., !ls, !git status)
• Empty input

Configuration

The extension uses a JSONC configuration file (JSON with comments):

Default global path: ~/.pi/agent/extensions/pi-must-have-extension/config.jsonc
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-must-have-extension/config.jsonc when PI_CODING_AGENT_DIR is set

Default Configuration

{
  // Enable file-backed debug logging under debug/
  // "debug": true,

  "replacements": {
    "must": "MUST",
    "must not": "MUST NOT",
    "mustn't": "MUST NOT",
    "required": "REQUIRED",
    "mandatory": "MANDATORY",
    "shall": "SHALL",
    "shall not": "SHALL NOT",
    "shan't": "SHALL NOT",
    "should": "SHOULD",
    "should not": "SHOULD NOT",
    "shouldn't": "SHOULD NOT",
    "ought": "SHOULD",
    "ought not": "SHOULD NOT",
    "oughtn't": "SHOULD NOT",
    "recommended": "RECOMMENDED",
    "not recommended": "NOT RECOMMENDED",
    "may": "MAY",
    "permitted": "PERMITTED",
    "not permitted": "NOT PERMITTED",
    "allowed": "ALLOWED",
    "not allowed": "NOT ALLOWED",
    "optional": "OPTIONAL",
    "not optional": "NOT OPTIONAL",
    "prohibited": "PROHIBITED",
    "forbidden": "FORBIDDEN",
    "disallowed": "DISALLOWED"
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | debug | boolean | false | Enable file-backed debug logging under debug/; no debug output is printed to the terminal | | replacements | object | RFC 2119 defaults | Key-value map of terms to replace |

Custom Replacements

You can add custom replacement rules or modify existing ones:

{
  "replacements": {
    // Standard RFC 2119
    "must": "MUST",
    "should": "SHOULD",
    
    // Custom shortcuts
    "rfc!": "The key words in this document are to be interpreted as described in RFC 2119.\n\n",
    "always": "**ALWAYS**",
    "never": "**NEVER**"
  }
}

An advanced replacement sample is included at config/replacements.custom-sample.jsonc.

The expanded defaults preserve the official BCP 14 keywords from RFC 2119/RFC 8174 and add practical writing variants found in policy and instruction text. Official BCP 14 reference: https://www.rfc-editor.org/bcp/bcp14.txt.

Legacy Config Paths

The extension supports migration from previous versions. Legacy configs are read from:

Default global legacy paths (respect PI_CODING_AGENT_DIR for the Pi agent directory):
~/.pi/agent/extensions/pi-must-have-plugin/config.jsonc
~/.pi/agent/extensions/must-have-plugin/config.jsonc
~/.config/opencode/MUST-have-plugin.jsonc

On first run, legacy configs are automatically migrated to the new location.

Technical Details

How It Works

1. Session start: Ensures config exists (creates default or migrates legacy)
2. Input event: Intercepts user prompts before sending to the agent
3. Pattern matching: Uses regex with word boundaries and longest-match-first ordering
4. Transformation: Returns modified text while preserving images and other input data

Project Structure

├── index.ts                 # Pi extension entrypoint
├── src/
│   ├── index.ts             # Extension event wiring
│   ├── constants.ts         # Paths, defaults, and extension name
│   ├── types.ts             # TypeScript interfaces
│   ├── config/
│   │   ├── config-loader.ts # Config loading and migration
│   │   └── jsonc.ts         # JSONC parser (strips comments)
│   └── replacements/
│       └── replacement-engine.ts  # Core replacement logic
├── config/
│   ├── config.example.jsonc           # Starter template
│   └── replacements.custom-sample.jsonc  # Advanced samples
└── test/
    └── replacement-engine.test.ts     # Unit tests

Development

npm install          # Install dependencies
npm run build        # Type-check with TypeScript
npm run test         # Run test suite
npm run check        # Build + test

Origin

This extension is a Pi-harness adaptation of ariane-emory/MUST-have-plugin, converted into a modular TypeScript Pi extension.

Related Pi Extensions

• pi-permission-system — Permission enforcement for tool and command access
• pi-tool-display — Compact tool rendering and diff visualization
• pi-rtk-optimizer — RTK command rewriting and output compaction
• pi-multi-auth — Multi-provider credential management and quota-aware rotation

License

MIT