OMP Architecture Report

ECHO:
Perform ultra-deep, obsessive research on OMP architecture to achieve absolute enlightenment on:
1. OMP magic words/phrases (slash commands) addition & editing.
2. Quickest workflows to overwrite/edit agents and their prompts.
3. Chat interactive features (e.g., the `ask` tool with multi-select).
4. OMP extensions for UI (advanced statusbars, pie charts, progress bars).
5. OMP Swarm extension and agentic workflows.
6. The /autoresearch command and experiment harness.
7. Persona edit/add functionality via settings.
Respond with genius-level overstanding, applying DRY/KISS/SOLID.

🪄 1. OMP Magic Words & Phrases (Slash Commands)

• Source of Truth: src/extensibility/slash-commands.ts
• Mechanism: Capability items implementing the SlashCommand interface are deduplicated first-wins. They are materialized/converted into FileSlashCommand objects afterwards in loadSlashCommands(). Embedded slash commands bypass the capability system, do not implement SlashCommand, and are appended and deduplicated after capability items are materialized.
• Providers:
  • native: <cwd>/.omp/commands/*.md (Project beats User).
  • claude: ~/.claude/commands/**/*.md (User beats Project).
  • claude-plugins: Prefixed as <plugin>:<command>.
• Quickest Edit/Add: Drop a .md file in <cwd>/.omp/commands/. The frontmatter name overrides the filename. The body dictates the prompt expansion. File-based slash commands execute before normal prompt expansion.

🤖 2. Overwriting & Editing Agents

• Source of Truth: src/extensibility/extensions/types.ts and src/extensibility/hooks/types.ts (with AGENTS.md serving as developer/agent alignment documentation).
• Mechanism: The actual technical contract is defined in TypeScript. Only the Extension API version of before_agent_start receives systemPrompt (string[]) in its event payload and must return a modified systemPrompt (string[]) as a full replacement (appends are no longer supported via systemPromptAppend). The Hook API version of before_agent_start in src/extensibility/hooks/types.ts does not receive or return systemPrompt at all.
• Hook vs Extension Support: The Hook API version only supports returning an optional { message?: HookMessage } to inject message context and cannot modify the system prompt.

💬 3. Interactive Chat Features (ask tool)

• Source of Truth: packages/coding-agent/src/tools/ask.ts
• Mechanism: Prompts the interactive user via UI selection (context.ui.select(...)).
• Options & Returns:
  • Single-select: Returns selectedOptions. UI appends (Recommended) if index provided.
  • Multi-select: Set multi: true. UI provides a checkbox loop with a Done selecting sentinel.
  • Multi-question: In multi-question mode, the tool returns details.results[] containing individual results instead of top-level selectedOptions.
  • Other/Custom: The UI implicitly adds an Other (type your own) fallback which invokes a text editor (context.ui.editor(...)).
• Genius Tip: Pass recommended: <index> for lightning-fast defaults. If options are already selected by the user, the timeout preserves them rather than forcing the recommended option. The timeout defaults to index 0 if recommended is missing or invalid.

📊 4. Advanced Statusbar & Simple Extensions

• Source of Truth: OMP_STATUSLINE_ULTIMATE_GUIDE.md
• Mechanism: YAML-driven interface DOM configuration.
• Enlightened Setup (custom preset): Define statusLine.preset: custom in your config.
  • Build arrays for leftSegments and rightSegments.
  • For advanced elements (like pie charts/progress bars), you must leverage segmentOptions to micro-manage rendering (e.g., granular data like context_pct, token_rate).
  • Colors: Bind via statusLineSep, statusLineContext, etc., to enforce a strict signal-to-noise ratio.

🐝 5. Swarm OMP Addon & Agentic Workflowz

• Source of Truth: _lab_sandbox/package/src/swarm/
• Mechanism: The Swarm extension is written in TypeScript and executes subagents via runSubprocess with full tool access (bash, python, etc.) instead of restricted Python eval sandboxes. It orchestrates parallel waves using JavaScript’s Promise.all rather than a Python parallel() function, and parses YAML config definitions via Bun.YAML, not strict JSON schemas.
• Core Philosophy: NEVER process serially. SWARM the AST/filesystem!
• Genius Tip: Batch file reads before swarming. Define execution pipelines using YAML config definitions.

🔬 6. Autoresearch & The /autoresearch Command

• Source of Truth: ~/.omp/autoresearch/--<encoded-path>--.db and autoresearch.sh
• Mechanism: The AI agent itself mutates the approaches by editing source files, while the bash harness (autoresearch.sh) only executes the benchmark/workload and reports metrics.
• SQLite DB: The SQLite DB is project-scoped and persistent across multiple sessions/runs (path-encoded as ~/.omp/autoresearch/--<encoded-path>--.db), not episodic.
• Genius Tip: Trap failures instead of halting; allow the harness to mutate its approach and log telemetry in the persistent project SQLite DB for subsequent run intelligence.

🎭 7. Persona Edit/Add in Settings

• Source of Truth: src/config/settings-schema.ts and src/config/settings.ts
• Mechanism: Controlled via the personality setting key (not persona).
• Settings Files: Settings are persisted and loaded via config.yml (globally) and settings.json (project-level), not settings.yml. The codebase contains documentation comments referencing settings.yml, but the actual runtime loader does not parse a file by that name.
• Architecture Note: The selected personality injects directly into the <personality> block of the base system prompt.

⚡ OMP QUICK-START CHEAT SHEET

📊 OMP Core Architecture & Settings Matrix

🔮 Concept	📁 Source of Truth & Paths	⚡ Core Mechanism / Quick Snippet
🪄 Slash Commands	src/extensibility/slash-commands.ts <cwd>/.omp/commands/*.md	Deduplicated first-wins for Capability SlashCommand items. Embedded commands bypass capability registry and append/deduplicate afterwards.
🤖 Agent Prompts	src/extensibility/extensions/types.ts src/extensibility/hooks/types.ts	Extensions: before_agent_start receives and returns systemPrompt (string[]) for replacement. Hook version does not support prompt modification (returns optional HookMessage).
💬 Interactive ask	packages/coding-agent/src/tools/ask.ts	Prompts user. Returns selectedOptions (single) or details.results[] (multi-question). Timeouts default to index 0 on recommended invalid/missing, else preserves current selections. Snippet: ask(questions=[{"id":"auth","question":"Choice?","options":[{"label":"A"}]}])
📊 Advanced Statusbar	OMP_STATUSLINE_ULTIMATE_GUIDE.md	YAML DOM configuration. Customize leftSegments, rightSegments, and segmentOptions for stats/truncation. Snippet: statusLine:\n preset: custom\n leftSegments:\n - type: git\n segmentOptions:\n token_rate: { visible: true }
🐝 Swarm Extension	_lab_sandbox/package/src/swarm/	TypeScript runner executing subagents via runSubprocess with full tool access, orchestrated via Promise.all and parsed via Bun.YAML.
🔬 Autoresearch	~/.omp/autoresearch/--<encoded-path>--.db autoresearch.sh	Project-scoped persistent SQLite DB tracks metrics. Harness only runs workload; agent edits code to mutate approaches.
🎭 Personality Settings	src/config/settings-schema.ts src/config/settings.ts	Configured via personality settings key (not persona). Persisted in config.yml (global) and settings.json (project), not settings.yml.

---

🎨 Visualization Diagrams

1. 🪄 Slash Command Discovery Lifecycle

flowchart TD
    classDef default fill:#1e1e24,stroke:#333,stroke-width:1px,color:#dcdcdc;
    classDef seqDiag fill:#1f6feb,stroke:#58a6ff,stroke-width:2px,color:#fff;
    classDef stDiag_v2 fill:#238636,stroke:#3fb950,stroke-width:2px,color:#fff;

    Start([Start loadSlashCommands]) --> CapabilityRegistry[Load SlashCommand Capabilities]
    CapabilityRegistry --> DeduplicateCaps[Deduplicate first-wins seenNames]
    DeduplicateCaps --> MaterializeCaps[Materialize into FileSlashCommand objects]
    MaterializeCaps --> LoadEmbedded[Load Embedded Commands task/commands.ts]
    LoadEmbedded --> AppendEmbedded[Deduplicate & Append after materialized items]
    AppendEmbedded --> Complete([Slash Commands Ready])

    class Start,Complete seqDiag;
    class CapabilityRegistry,LoadEmbedded stDiag_v2;

2. 💬 The ask Tool Interactive Flow

flowchart TD
    classDef default fill:#1e1e24,stroke:#333,stroke-width:1px,color:#dcdcdc;
    classDef seqDiag fill:#1f6feb,stroke:#58a6ff,stroke-width:2px,color:#fff;
    classDef stDiag_v2 fill:#238636,stroke:#3fb950,stroke-width:2px,color:#fff;

    AskStart([Call ask tool]) --> ModeCheck{Single or Multi-Question?}

    ModeCheck -- Multi-Question --> UISelectMulti[Prompt user with checkbox loop]
    UISelectMulti --> ReturnResults[Return details.results array]

    ModeCheck -- Single-Select --> UISelectSingle[Prompt user for single option]
    UISelectSingle --> TimeoutCheck{Did interaction timeout?}

    TimeoutCheck -- No --> UserSelect[User selects option]
    UserSelect --> ReturnSelected[Return selectedOptions]

    TimeoutCheck -- Yes --> OptionCheck{Any option already selected?}
    OptionCheck -- Yes --> PreserveOptions[Preserve selected options]
    OptionCheck -- No --> RecommendedCheck{Is recommended property valid?}
    RecommendedCheck -- Yes --> AutoSelectRecommended[Auto-select recommended index]
    RecommendedCheck -- No --> DefaultIndex0[Auto-select Index 0]

    PreserveOptions --> ReturnSelected
    AutoSelectRecommended --> ReturnSelected
    DefaultIndex0 --> ReturnSelected
    ReturnResults --> EndAsk([End ask tool])
    ReturnSelected --> EndAsk

    class AskStart,EndAsk seqDiag;
    class UISelectMulti,UISelectSingle,ReturnResults,ReturnSelected stDiag_v2;

3. 🤖 before_agent_start Hook & Extension execution logic

flowchart TD
    classDef default fill:#1e1e24,stroke:#333,stroke-width:1px,color:#dcdcdc;
    classDef seqDiag fill:#1f6feb,stroke:#58a6ff,stroke-width:2px,color:#fff;
    classDef stDiag_v2 fill:#238636,stroke:#3fb950,stroke-width:2px,color:#fff;

    Start([Agent Start triggered]) --> PayloadGen[Generate event payload]
    PayloadGen --> ExtCheck{Is it Extension or Hook?}

    ExtCheck -- Extension --> ExtRunner[Execute before_agent_start extension handler]
    ExtRunner --> ExtModify[Modify systemPrompt string array]
    ExtModify --> ExtReturn[Return full systemPrompt array replacement]

    ExtCheck -- Hook --> HookRunner[Execute before_agent_start hook runner]
    HookRunner --> HookMessage[Return optional HookMessage context only]
    HookMessage --> HookNoPrompt[Cannot modify systemPrompt]

    ExtReturn --> RunAgent[Spawn Agent with final system prompt]
    HookNoPrompt --> RunAgent

    class Start,RunAgent seqDiag;
    class ExtRunner,ExtModify,ExtReturn stDiag_v2;