Personal OMP plugins
README.md

ezxomp #

A curated OMP plugin marketplace — 11 OMP 18.0.6-compatible plugins, installable as a single marketplace.

Quick start #

# From the git remote (tangled):
omp plugin marketplace add https://tangled.org/expi.tngl.sh/ezxomp

# Or from the checkout you intend to use:
omp plugin marketplace add /path/to/ezxomp

# Install all 11 plugins (user scope):
omp plugin install code-nav@ezxomp codesight@ezxomp experiences@ezxomp \
  agent-learning@ezxomp compact-eng@ezxomp \
  plannotator@ezxomp augment@ezxomp evo@ezxomp cook@ezxomp backlog@ezxomp \
  better-custom@ezxomp --scope user

# Or, from a repo checkout, reset the whole set (with backup + local/market
# choice) — see "Quick setup (dev / test)" below:
just setup

# Or install individually:
omp plugin install code-nav@ezxomp --scope user

# Verify:
omp plugin list

Don't use omp plugin install git:<url> — it treats the URL as a single tarball and fails with ZlibError. This repo is a marketplace, not a single plugin. Add it with omp plugin marketplace add first, then install plugins by name@marketplace.

Quick setup (dev / test) #

Reset the full ezxomp plugin set (all 11 plugins from the catalog) in one shot, with an interactive clean/backup choice and a local-link vs marketplace install choice. Everything runs through scripts/setup-omp.sh (bash; needs only git, python3, omp) and is exposed as just recipes:

just setup          # interactive: (1) clean vs backup config, (2) local vs marketplace
just setup-local    # non-interactive: clean + link all 11 from the working tree
just setup-market   # non-interactive: backup + install all 11 from the ezxomp marketplace
just setup-clean    # non-interactive: remove all 11 (no reinstall)
Recipe Flags passed What it does
just setup none Interactive prompts: 1) backup (default) or clean, 2) local or market, then a confirmation.
setup-local --clean --local --yes Remove installed plugins, then omp plugin link every plugin from the repo working tree. Use to test unpushed changes.
setup-market --backup --market --yes Back up config/state, remove installed plugins, then omp plugin install every plugin from the marketplace. This is the shipping state.
setup-clean --remove-only --yes Remove all 11 plugins without reinstalling (symlink + lock + cache sweep).

Script CLI (scripts/setup-omp.sh) #

bash scripts/setup-omp.sh [flags]

  --clean | --backup   config policy
                       clean  — remove all installed ezxomp plugins, keep config/state as-is
                       backup — tar config/state to ~/ezxomp-omp-backups/ first, then clean
  --local | --market   install mode
                       local  — link every plugin from the repo working tree
                       market — install every plugin from the ezxomp marketplace
                                (registers/clones the marketplace from origin if unregistered)
  --remove-only        clean only; skip the install step
  --yes, -y            skip confirmations (implied when non-interactive)
  -h, --help           show help

Behavior notes:

  • Safe by default. With a TTY you are asked both questions (policy default: backup). Without a TTY, missing flags fall back to backup + local with a warning — a bare run never deletes config/state.
  • What clean touches: installed-plugin state only — ~/.omp/plugins/node_modules/@ezxomp/*, ~/.omp/plugins/omp-plugins.lock.json entries, ~/.omp/plugins/cache/plugins. Config/state dirs (agent, agents, profiles, logs, ids) are never modified; backup archives them to ~/ezxomp-omp-backups/omp-backup-<timestamp>.tar.gz first.
  • The sweep is idempotent. The removal handles the OMP CLI's asymmetry — omp plugin uninstall <name>@ezxomp does not remove linked plugins — by removing node_modules entries, scrubbing the lock, and clearing the plugin cache. Re-running any recipe converges to the requested state.
  • Verified end state. The script finishes with omp plugin doctor (0 errors) and classifies every plugin as LOCAL (repo link) or MKT (marketplace cache), exiting non-zero on any mismatch.
  • Isolatable. It honors $OMP_HOME (defaults to ~/.omp), so e2e runs work in a temp HOME: HOME=$(mktemp -d) bash scripts/setup-omp.sh --clean --market --yes.
  • Start a fresh OMP session after any setup run to pick up the new plugin set.

Plugins #

Plugin Version Upstream Description
code-nav 0.5.0-ezxomp.1 pi-code-nav Code navigation, definition, reference, implementation, AST-grep
codesight 0.2.2-ezxomp.1 pi-codesight CodeSight artifact reader, session-owned watcher, overlay
experiences 0.1.49-ezxomp.3 pi-experiences Experience capture, retrieval, consolidation, scheduling, CLI
agent-learning 0.1.0-ezxomp.3 in-house Unified agent learning: skills catalog + skills.sh surface, native-memory facts shim, skillforge evidence pipeline
compact-eng 2.0.0-ezxomp.1 pi-ultra-compact OMP-native compaction governor, Shake observer, and guarded text/snapcompact requests
augment 1.0.9-ezxomp.1 pi-augment Augment-style prompt rewriting with persisted OMP settings and editor review
plannotator 0.25.1-ezxomp.4 backnotprop/plannotator Planning, annotation, code/PR review, browser server
evo 0.1.7-ezxomp.8 pi-evo-mode evo mode toggle: marketplace-plugin tool profile for main agent and subagents
cook 0.1.7-ezxomp.9 pi-backlog-cook Backlog.md cookbook workflow: atomic sub-tickets, scout/planner/worker/validator/judge dispatch, Done-gate
backlog 0.1.0-ezxomp.1 in-house Backlog.md integration: backlog_* tool suite + canonical workflow instructions overlay
better-custom 0.1.3-ezxomp.1 in-house /custom-provider wizard, native /model registry registration, /better-models unified browser

Retired plugins #

extensible-workflows, gsd-browser, gsd-web, gsd-loop, gsd-graph, and pstack-suite are no longer in this marketplace or source tree. Their commands and tools are no longer available from a fresh catalog install. A marketplace update alone does not uninstall older copies; a whole-set reset with just setup-market removes leftover @ezxomp entries before reinstalling the 11 current plugins. This repository removal does not delete existing project .gsd/ or .gsd-loop/ data.

Local development #

# Scaffold a new plugin:
bun run scripts/scaffold-plugin.ts my-plugin --description "What it does" \
  --with-skills --with-tools --with-commands

# Verify a plugin scaffold:
bun run scripts/verify-scaffold.ts my-plugin

# Symlink all plugins from the working tree — Phase 1 dev-test vehicle ONLY;
# the shipping state must be a marketplace install (docs/omp-marketplace-update.md):
bun run install:local

# Verify on-disk manifests + live RPC:
bun run verify:omp

# Run plugin smoke tests:
bun run smoke:plugins

# Type-check:
bun run check

# Clean worktree setup (requires Bun, Node, npm/npx, tar, Git, backlog):
bun install --frozen-lockfile
bun plugins/experiences/scripts/fetch-local-embedding-assets.ts

# Full pre-push gate (types, root/plugin suites, bundle hashes, new-only audit):
just verify

# Opt-in Qlty lint for changed files (does not alter just verify):
just quality

Plannotator caveat. Plannotator loads its tracked index.bundle.js (see plugins/plannotator/AGENTS.md); source edits to its index.ts, server/, todo-providers/, or generated/ only take effect after bun run --cwd plugins/plannotator build:bundle and an OMP restart. just verify-bundles compares both shipped bundles against temporary rebuilds by SHA-256; timestamps do not affect the result.

Repository operations #

Use native Git for commits and integration, and Worktrunk (wt 0.78.0) for task worktree creation, inventory, and removal. Workers commit on task/<slug> and hand off branch plus immutable OID; coordinator verifies, fast-forwards main, and publishes with git push origin main. Follow docs/parallel-agents.md for exact commands. JJ workspace/bookmark commands in completed records are historical, not active repository guidance.

Keep the existing Tangled origin (git remote get-url origin). Installed standalone gh-axi is GitHub-specific, not a gh extension: check gh-axi --version and gh auth status before work on an explicitly targeted GitHub repo. It cannot target Tangled. Tangled PRs require a usable, authenticated tngl; verify the CLI rather than trusting a shim on PATH. See the Git/Tangled skill.

Qlty is opt-in: just quality runs qlty check --no-fix --no-upgrade-check --no-formatters for changed files, using Biome lint and ShellCheck from .qlty/qlty.toml. It is not part of the required just verify gate.

Refreshing upstream sources #

# Pull the pinned tarball, run upstream build:pi, stage into a fresh temp dir.
# The stage dir mirrors the upstream `apps/pi-extension` layout directly
# (no `plugins/plannotator/` prefix).
STAGE=$(mktemp -d)
bun run scripts/import-upstreams.ts stage plannotator --out "$STAGE"

# Replace the plugin source artifacts wholesale so changed files refresh.
rm -rf plugins/plannotator/generated
cp -R "$STAGE/generated" plugins/plannotator/
cp "$STAGE"/plannotator.html "$STAGE"/review-editor.html plugins/plannotator/
rm -rf "$STAGE"

# Re-bundle the extension entry so index.bundle.js reflects the refreshed source.
( cd plugins/plannotator && bun run build:bundle )

# Review the diff with `git status`; then follow the repository's
# Worktrunk lifecycle and native-Git Tangled workflow to commit and push
# (see `.omp/skills/git-tangled-workflow` and `AGENTS.md` § Work Guidance).
# Scope the commit to the refreshed artifacts only.

Do not run vendor.sh in this repo — it expects the upstream monorepo (packages/core, packages/shared, etc.) which is not checked out here. The locked stage command reproduces its effect against the pinned commit.

Marketplace catalog #

The catalog lives at .omp-plugin/marketplace.json. It uses the OMP marketplace schema:

  • name — marketplace name (must match /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/, max 64 chars)
  • owner.name — owner name
  • plugins — array of plugin entries ({ name, source, description?, version?, attribution? })
    • source must start with ./ (relative to repo root) for local-directory plugins

OMP discovers the catalog at .omp-plugin/marketplace.json (or .claude-plugin/marketplace.json as fallback). The array field is plugins, not entries.

Repository structure #

.
├── .omp/skills/                    # Project-local workflows and marketplace skills
├── .omp-plugin/marketplace.json   # OMP marketplace catalog (11 plugins)
├── plugins/                       # Plugin source (one dir per plugin)
│   └── ...
├── upstreams.lock.json             # Pinned upstream versions + integrity hashes
├── scripts/
│   ├── import-upstreams.ts         # Lock-driven importer (download, verify, copy)
│   ├── install-local.ts            # Symlink installer (omp plugin link)
│   ├── scaffold-plugin.ts          # New plugin scaffolder
│   ├── verify-scaffold.ts          # Plugin structure validator
│   └── verify-omp.ts               # Manifest + RPC verification
├── test/                           # Smoke + integration tests
└── package.json                    # Workspace root (plugins/*)

Project-local skills #

.omp/skills/ contains five skills for working in this repo:

  • git-tangled-workflow — Native-Git commits and Tangled delivery, Worktrunk task-worktree protocol pointer, DCO sign-off, coordinator git push origin main, and conditional tngl PRs (not GitHub gh-axi)
  • omp-plugin-authoring — Create and structure OMP-native plugins; manifest fields, auto-discovered capabilities (skills, hooks, commands, tools, MCP), feature gating, validation
  • omp-native-package — Publish and install OMP plugins via npm; package.json setup, files array, version strategy, lock file management
  • ezxomp-marketplace — Manage this marketplace catalog; add/remove plugins, install workflows, source resolution, debug install failures
  • ezxomp-plugin-e2e-test — End-to-end test a plugin change: just verify, local-link + marketplace install, fresh OMP agent self-checks per phase (HERDR optional)

License #

Forked plugins retain their upstream licenses (see plugins/*/LICENSE). Repository orchestration and newly scaffolded plugins are licensed under Apache-2.0; see LICENSE.