# OMO-Paseo Bridge: Synthesis

## The Problem

Two agent registries, one blind spot:

```
paseo ls                          list-child-sessions
─────────────                     ───────────────────
f17ff66f  Implement Phases 3-11   ses_15cf07  Search boocode (@explore)
12bbde1   Pattern 5 dashboard     (not shown in paseo ls)
f328c5b   Diagnose Discord API
...                              ...
```

OMO `task()` creates child sessions that Paseo's daemon never hears about. Users who orchestrate across both systems get a fragmented view of their agent fleet.

## The Bridge

Paseo already has the right primitive: `paseo import <session-id> --provider opencode` wraps an existing session as a Paseo agent **without spawning a new process**. The gap was that nothing called it for OMO child sessions.

The bridge is three layers, each independent:

```
Layer 1: Skill (durable, scripted)    ← IMPLEMENTED
  .opencode/skills/omo-paseo-bridge/
    SKILL.md          - Reusable skill descriptor
    bin/omo-paseo-bridge.sh - 5 commands: register, unregister, status, list, find

Layer 2: Prompt instruction (zero-code) ← READY TO USE
  Atlas prompt fragment for automatic task() → paseo import mapping
  
Layer 3: Hook (fully automatic)       ← FUTURE
  PreToolUse hook watches task() lifecycle, auto-imports/archives
```

## What Was Built

### OpenSpec Change: `omo-paseo-bridge`

| Artifact | Content |
|----------|---------|
| `proposal.md` | Motivation and scope |
| `design.md` | Architecture with 3 integration layers |
| `tasks.md` | 4 implementation tasks |
| `specs/omo-paseo-visibility/spec.md` | 3 validated requirements with scenarios |
| `artifacts/synthesis.md` | This document |

### Feature Branch

```
/opt/forks/opencode → feat/omo-paseo-bridge (from dev)
```

### Bridge Skill

Two files at `.opencode/skills/omo-paseo-bridge/`:

**SKILL.md** (200 lines)
- Frontmatter with trigger patterns
- Register/unregister operations with exact CLI invocations
- Error handling for 4 common failure modes
- Data model for agent labels
- Atlas integration protocol

**bin/omo-paseo-bridge.sh** (196 lines)
- `register <session-id> [--type <cat>] [--description <text>]` — Calls `paseo import`, prints agent UUID
- `unregister <agent-id>` — Calls `paseo archive`, falls back to name/ID search
- `status` — Daemon health check
- `list [--omo-only]` — Agent listing
- `find <session-id>` — Name-based agent search

## Verification Results

| Test | Outcome |
|------|---------|
| Script syntax (`bash -n`) | ✅ PASS |
| Register real child session `ses_15cf07...` | ✅ Agent `695e978e` created, shown in `paseo ls` as "Search the boocode codebase thoroughly..." |
| Register fake session `ses_test_xxx` | ✅ Agent created (as imported, no title when session doesn't exist) |
| Unregister by UUID | ✅ Agent archived, removed from active list |
| Unregister by shortId | ✅ Agent archived via 8-char prefix |
| Daemon not running | ✅ Clear error: "Paseo daemon is not running. Start it with: paseo daemon start" |
| `paseo ls` shows OMO agent | ✅ Agent appears with task description as name, status "idle" |
| OpenSpec validation | ✅ Change is valid (all 3 requirements, all scenarios) |

## The Bigger Picture: Two-Level Hierarchy

```ascii
User
  │
  ├── Paseo (persistent daemon)
  │     ├── Agent A: Orchestrator (codex/gpt-5.4)
  │     │     └── OMO subagents (imported via bridge):
  │     │           ├── ses_xxx  Research architecture    (deep)
  │     │           ├── ses_yyy  Implement module X       (ultrabrain)
  │     │           └── ses_zzz  Build frontend widget    (visual-engineering)
  │     ├── Agent B: Long-running analysis (claude/opus)
  │     └── Agent C: Scheduled health check (codex)
  │
  └── paseo ls -- shows ALL agents including OMO imports
```

The bridge makes the hierarchy flat for visibility purposes. Paseo sees everything. OMO sees its children. The user sees both in one place.

## What's Next

| Priority | Item | Status |
|----------|------|--------|
| P0 | Add bridge instruction to Atlas prompt | Ready — needs CLAUDE.md or prompt template update |
| P1 | Wire `register` into `task()` lifecycle automatically | Needs hook support |
| P2 | Add `omo-paseo sync` bulk-import command | Future enhancement |
| P3 | Paseo-side labels query filter | Would need `paseo ls --label` support |

## File Manifest

### New files created
```
/home/samkintop/opt/forks/
├── openspec/changes/omo-paseo-bridge/
│   ├── proposal.md
│   ├── design.md
│   ├── tasks.md
│   ├── specs/omo-paseo-visibility/spec.md
│   └── artifacts/synthesis.md
├── .opencode/skills/omo-paseo-bridge/
│   ├── SKILL.md
│   └── bin/omo-paseo-bridge.sh
```