Why OMP and Pi Use Different Plugin Subcommand Schemas for the Same Skill

OMP and Pi use different plugin subcommand schemas because each runtime follows its own CLI contract—OMP expects command, description, and handler fields for Open-Model-Plugin integration, while Pi requires name, run, and help fields for Pi-package compatibility.

The i-have-adhd repository supports dual runtime environments, requiring distinct command-line contracts for the same underlying skill implementation. While both OMP (Open-Model-Plugin) and Pi (Pi-package) runtimes load the identical TypeScript implementation from ./extensions/i-have-adhd.ts, they interpret the exported object through different plugin subcommand schemas that reflect their respective platform conventions.

Runtime-Specific Contracts in package.json

The divergence begins in the manifest configuration. According to the ayghri/i-have-adhd source code, package.json declares separate entry points under runtime-specific keys, while AGENTS.md documents the mapping between these environments.

For OMP, the extension registers under the "omp" key, specifying ./extensions/i-have-adhd.ts as the entry point. The OMP loader expects this file to export a subcommand object containing command, description, and handler properties that fit the Open-Model-Plugin CLI structure.

For Pi, the same file path registers under the "pi" key. However, Pi's loader interprets the export as a plugin definition requiring name, run, and help fields to satisfy Pi-package tooling expectations.

Comparing Schema Shape Requirements

The contrast between OMP and Pi plugin subcommand schemas determines how each runtime builds its command-line interface.

OMP Schema uses Open-Model-Plugin conventions:

• command: String identifier for the CLI subcommand
• description: Help text displayed in opencode --help
• handler: Function executed when running opencode i-have-adhd ...

Pi Schema follows Pi-package standards:

• name: Plugin identifier used for command routing
• run: Execution function invoked via pi i-have-adhd ...
• help: Documentation string for Pi's help system

Shared Implementation with Dual Bindings

Both runtimes ultimately execute the same logic located in ./extensions/i-have-adhd.ts. This TypeScript file serves as the canonical implementation of the "i-have-adhd" skill, while skills/i-have-adhd/SKILL.md provides the canonical behavior description used by both loaders.

When you invoke the skill through OMP:

opencode i-have-adhd "Explain how to create a to-do list"

The OMP loader reads the exported object, validates it against the OMP subcommand schema, and binds the handler function to the CLI command tree.

When using Pi:

pi i-have-adhd "Explain how to create a to-do list"

Pi's loader applies its own validation, extracting the run function according to Pi's plugin contract.

Why Different Schemas Are Necessary

The design follows runtime-specific contracts to maintain backward compatibility with existing tooling. OMP was created to integrate with the Open-Model-Plugin ecosystem, which merges subcommands into a host CLI tree using specific property names. Pi targets the Pi-package platform, which predates OMP and follows established "plugin" nomenclature rather than "subcommand" terminology.

Forcing either platform to adopt the other's schema would break existing integrations. By supporting both schemas simultaneously through the same source file, the repository achieves portability without forcing API changes on either runtime.

Summary

• OMP uses the fields command, description, and handler defined in the "omp" section of package.json.
• Pi uses the fields name, run, and help defined in the "pi" section of package.json.
• Both runtimes load the identical implementation from ./extensions/i-have-adhd.ts.
• The divergence exists to maintain compatibility with Open-Model-Plugin and Pi-package CLI conventions respectively.
• Invoke OMP with opencode i-have-adhd ... and Pi with pi i-have-adhd ....

Frequently Asked Questions

What fields does the OMP subcommand schema require?

The OMP subcommand schema requires three specific fields: command (the CLI identifier), description (help text), and handler (the execution function). These properties allow the OMP loader in package.json to register the skill as a native subcommand within the Open-Model-Plugin ecosystem.

How does the Pi plugin schema differ from OMP?

The Pi plugin schema replaces OMP's field names with name (instead of command), run (instead of handler), and help (instead of description). This naming convention aligns with Pi-package runtime expectations, where "plugins" rather than "subcommands" constitute the primary extension mechanism.

Can I use the same implementation file for both runtimes?

Yes. The ./extensions/i-have-adhd.ts file serves as the shared implementation for both OMP and Pi. Each runtime interprets the exported object according to its own schema, allowing a single source file to satisfy both Open-Model-Plugin and Pi-package requirements without code duplication.

Why not standardize on a single schema for both runtimes?

Standardization would force either the Open-Model-Plugin or Pi-package platform to abandon its existing public API and tooling conventions. The current design preserves backward compatibility for both ecosystems by allowing each runtime to translate the shared implementation into its native command structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}