Authority: runtime-extension truth lives in this SSOT. Framework and memory-system depth lives at omp.0rk.de/extensions.
1. ⚡ Non-negotiables
runtime: "omp + @oh-my-pi/* only"
human_ui: "one discoverable slash-command root per extension"
llm_tools: "may stay granular when schemas improve model reliability"
aliases: "never register synonym commands; every registration pollutes discovery"
interaction: "overview → focused action → confirm mutation → concise result"
rendering: "event-driven; widgets for passive state, overlays for focused work"
fallback: "every TUI flow has a readable non-interactive result"OMP exposes no hidden command-alias API: duplicate registrations are visible and can receive :N suffixes. Use subcommands and argument completions inside one root handler instead.
2. 🧩 Progressive disclosure
| Layer | User sees | Rule |
|---|---|---|
| L0 | Command list | One compelling line: capability · benefit · next step |
| L1 | Bare command | Status + three safe/high-value actions |
| L2 | Category | Short, emoji-labelled actions with practical descriptions |
| L3 | Detail | Context, preview, flags, and the narrowest useful controls |
| L4 | Mutation | Explicit confirmation; explain effect and recovery path |
flowchart LR root[PrimaryCommand] --> overview[StatusAndTopActions] overview --> category[FocusedCategory] category --> detail[ActionPreview] detail --> confirm[MutationConfirmation] confirm --> result[ResultAndNextStep]
3. 🎛️ Surface selection
| Need | Use | Avoid |
|---|---|---|
| Persistent, passive signal | ctx.ui.setWidget / status segment | Polling dashboards |
| Focused, keyboard-driven task | ctx.ui.custom(..., { overlay: true }) | New sibling slash commands |
| Simple choice or confirmation | ctx.ui.select / ctx.ui.confirm | Custom component overhead |
| Scriptable fast path | <root> <subcommand> [flags] + completions | Undocumented magic syntax |
| Model operation | registerTool with narrow schema | Human-only slash-command fan-out |
Widgets must be event-driven, change-gated, ASCII-safe where applicable, and hide unavailable data rather than emitting noise or errors.
4. 🏷️ Command ownership
| Extension | Sole human root | Notes |
|---|---|---|
| OmpKeep | /ok | Memory hub; no separately registered /ompkeep alias |
| ompbar | /statusbar | Passive-HUD configuration exception |
| mythomp | /mythic | Codes and mode management |
| omptask | /tm | Human backlog control; model tool is backlog |
| omparc | /arc | Read-only learning arc |
| ompfuse | none | Telemetry is event-only |
Before adding a command, update this table and verify it does not collide with OMP built-ins or another extension.
5. 🛡️ Safety and feedback
- Preview and confirm writes, curation, deprecation, reindexing, and irreversible actions.
- Keep L1 identity memory human-ratified; route L2 changes through OmpKeep candidates and patches.
- Do not show private memory text in aggregate dashboards by default.
- After every action, show outcome, scope, and one relevant next step.
6. 📚 Documentation contract
Every extension blueprint must contain:
status: shipped, planned, or superseded.- Primary command, UI surface, model-tool boundary, and state paths.
- A short smoke test and explicit done criteria.
- A link to this contract plus the relevant OMP framework/memory depth.
Within one garden use wikilinks. Across gardens use absolute https://ssot.0rk.de/... or https://omp.0rk.de/... URLs. Superseded pages keep a brief banner and canonical link; they do not maintain competing instructions.
7. ✅ Author checklist
- One visible human command root only
- Bare command is useful without arguments
- Completions explain subcommands
- TUI and non-TUI paths both work
- Writes have confirmation and recovery guidance
- Widget work is event-driven and bounded
- Blueprint, status, smoke test, and command registry are updated