# Roadmap: Owl Skill

## Milestones

- [x] **v1.0 Live Agent System** - Phases 1-4 (shipped 2026-03-29)
- [ ] **v1.1 Native Runtime** - Phases 5-9 (in progress)

## Phases

<details>
<summary>v1.0 Live Agent System (Phases 1-4) - SHIPPED 2026-03-29</summary>

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation & Hardening** - Harden owl.sh messaging, add output formatting and auto-setup, scaffold live.sh with Self registration
- [x] **Phase 2: Psyche Core** - Psyche spawn, COMMUNE/PULSE cycle, graceful stop, and SKILL.md documentation (completed 2026-03-28)
- [x] **Phase 2.1: Live Skill Extraction** (INSERTED) - Extract /live into standalone LIVE-SKILL.md
- [x] **Phase 2.2: Owl & Live Hardening** (INSERTED) - Signal-based lifecycle, BUSY state, Psyche persistence, restart shortcuts
- [x] **Phase 3: Timed Pulses** - Deferred to v1.1 as Phase 8
- [x] **Phase 4: Spine Supervisor** - Deferred to v1.1 as Phase 9

### Phase 1: Foundation & Hardening
**Goal**: Agents have a robust, race-free messaging layer with consistent output, automatic environment setup, and a working live.sh scaffold that registers Self agents
**Depends on**: Nothing (first phase)
**Requirements**: HARD-01, HARD-02, HARD-03, FMT-01, FMT-02, FMT-03, SETUP-01, SETUP-02, SETUP-03, LIVE-02, LIVE-08, LIVE-10
**Success Criteria** (what must be TRUE):
  1. Messages are delivered atomically -- a concurrent reader never sees a partial message file
  2. Two agents sending messages in rapid succession never produce filename collisions
  3. All /owl and /live output uses ANSI colors and compact symbols (no emoji), and /owl output is visually distinct from /live output
  4. Running /owl or /live for the first time on a clean machine auto-adds required env vars and session cleanup hook to settings.json (with user notification)
  5. `/live list` shows Self agents marked as live; all existing `/owl` commands work unchanged
**Plans:** 3/3 plans complete

Plans:
- [x] 01-01-PLAN.md -- Harden owl.sh (atomic writes, collision-resistant IDs, TOCTOU-safe poll) and add ANSI color output
- [x] 01-02-PLAN.md -- Auto-setup settings.json (env vars, SessionEnd hook) and session-scoped cleanup
- [x] 01-03-PLAN.md -- Scaffold live.sh (Self registration, /live list) and update SKILL.md

### Phase 2: Psyche Core
**Goal**: A user can start a live agent session and receive contextual, periodic nudges from a background Psyche that tracks what they are doing
**Depends on**: Phase 1
**Requirements**: LIVE-01, LIVE-03, LIVE-04, LIVE-05, LIVE-06, LIVE-07, LIVE-09, LIVE-11, SKILL-01, SKILL-02, SKILL-03
**Success Criteria** (what must be TRUE):
  1. `/live [id]` starts an owl listener with Self role and spawns a Psyche subagent that begins its pulse loop
  2. Self sends COMMUNE updates that Psyche absorbs into context; when a pulse timer fires, Psyche judges whether Self should be doing something and notifies Self if so
  3. When Self stops, its Psyche is also torn down with no orphaned processes or perch files
  4. Pulse period is configurable via `--period` flag (minimum 1 minute)
  5. SKILL.md documents all /live subcommands, auto-setup behavior, and edge cases with the same depth as /owl
**Plans:** 3/3 plans complete

Plans:
- [x] 02-01-PLAN.md -- owl.sh extensions (--psyche flag, auto-setup poll, list filtering) and live.sh subcommands (commune, pulse-wait, enhanced start/stop, --period)
- [x] 02-02-PLAN.md -- psyche.md agent prompt template and DEPLOY.md update
- [x] 02-03-PLAN.md -- SKILL.md full /live documentation rewrite with ID recollection and edge cases

### Phase 2.1: Live Skill Extraction (INSERTED)
**Goal**: /live is a standalone Claude Code skill with its own SKILL.md, separate from /owl, matching the design in SKILL_SPEC-LIVE.md
**Requirements**: EXTRACT-01, EXTRACT-02, EXTRACT-03, EXTRACT-04
**Depends on:** Phase 2
**Success Criteria** (what must be TRUE):
  1. LIVE-SKILL.md exists as a standalone skill file with `name: live` frontmatter
  2. SKILL.md contains only /owl commands with no /live content
  3. Both skill files cross-reference each other
  4. DEPLOY.md includes LIVE-SKILL.md in all file operations
**Plans:** 1/1 plans complete

Plans:
- [x] 02.1-01-PLAN.md -- Extract /live documentation into standalone LIVE-SKILL.md, trim owl SKILL.md, update DEPLOY.md

### Phase 2.2: Owl & Live Hardening (INSERTED)
**Goal**: Harden owl.sh and live.sh with race condition fixes, signal-based lifecycle management, skill setup tooling, listener intelligence, Psyche persistence, session auto-resume, and restart shortcuts
**Requirements**: HARDEN-01, HARDEN-02, HARDEN-03, HARDEN-04, HARDEN-05, HARDEN-06, HARDEN-07, HARDEN-08, HARDEN-09, HARDEN-10
**Depends on:** Phase 2.1
**Success Criteria** (what must be TRUE):
  1. GC never cleans up a perch that is between polls (BUSY PID state protects the re-poll gap)
  2. Poll processes exit gracefully on signal with status output, and stop commands use graceful-then-force shutdown
  3. SKILL.md instructs listeners to name subagents and check background tasks before processing messages
  4. Psyche context persists across agent death and can be downloaded by a revived Psyche
  5. SessionStart hook auto-detects dead listeners and outputs resume instructions
  6. One-command restart shortcuts exist for both owl listeners and live agents
**Plans:** 4/4 plans complete

Plans:
- [x] 02.2-01-PLAN.md -- BUSY PID state in _poll_once + signal traps in poll + signal-based stop
- [x] 02.2-02-PLAN.md -- /owl gsd-setup command + SKILL.md listener intelligence instructions
- [x] 02.2-03-PLAN.md -- Psyche context persistence (context-save, psyche-download, clear-psyche)
- [x] 02.2-04-PLAN.md -- Restart shortcuts (reboot, revive) + stash + SessionStart auto-resume

</details>

### v1.1 Native Runtime (In Progress)

**Milestone Goal:** Replace owl.sh and live.sh with a compiled native Rust binary using P2P messaging architecture, while preserving the existing CLI interface exactly.

- [ ] **Phase 5: Golden Tests & CLI Skeleton** - Capture bash output as golden tests, build CLI skeleton with clap, set up cross-platform CI
- [ ] **Phase 6: P2P Messaging & Owl Parity** - P2P local-server architecture with SQLite spool, all owl subcommands passing golden tests
- [ ] **Phase 7: Live Parity & Distribution** - Live subcommands with native Psyche wrapper, drop-in binary distribution
- [ ] **Phase 8: Timed Pulses** - One-shot timed pulse requests and /live timed-pulse command (native)
- [ ] **Phase 9: Spine Supervisor** - Spine/Touch process supervision with health checks and recovery (native)

## Phase Details

### Phase 5: Golden Tests & CLI Skeleton
**Goal**: Every bash subcommand's exact output is captured as a golden test, and a compiled Rust binary parses all subcommands (stubbed) and builds on all target platforms
**Depends on**: Phase 4 (v1.0 complete)
**Requirements**: COMPAT-01, COMPAT-02, COMPAT-03, COMPAT-04, COMPAT-05, COMPAT-06, RUST-02, RUST-03
**Success Criteria** (what must be TRUE):
  1. A golden test suite exists that captures byte-for-byte stdout and stderr from every owl.sh and live.sh subcommand, including ANSI color codes and LF line endings
  2. Running the golden test suite against the bash scripts passes 100% (baseline proof)
  3. A Rust binary compiles and runs on Windows x86_64, Linux x86_64, and macOS x86_64/aarch64 via CI
  4. The binary accepts every `$OWL` and `$LIVE` subcommand with correct argument parsing (exits with "not yet implemented" stub)
**Plans:** 2/3 plans executed

Plans:
- [x] 05-01-PLAN.md -- Golden test capture script and fixture generation from bash scripts
- [x] 05-02-PLAN.md -- Rust CLI skeleton with clap derive structs and parse verification tests
- [x] 05-03-PLAN.md -- Golden test Rust integration tests and cross-platform CI workflow

### Phase 6: P2P Messaging & Owl Parity
**Goal**: Agents communicate via direct local-server connections with SQLite offline spool, and every owl subcommand passes its golden test
**Depends on**: Phase 5
**Requirements**: RUST-01, RUST-04, P2P-01, P2P-02, P2P-03, P2P-04, P2P-05, P2P-06, P2P-07, P2P-08, OWL-01, OWL-02, OWL-03, OWL-04, OWL-05, OWL-06, OWL-07, OWL-08, OWL-09, OWL-10, OWL-11, OWL-12, PROC-01, PROC-02, PROC-03, PROC-04, PROC-05
**Success Criteria** (what must be TRUE):
  1. `$OWL poll` starts a lightweight local server that accepts direct message deliveries from other agents -- message delivery is sub-second when target is online
  2. When a target agent is offline, messages are written to the target's SQLite spool with configurable TTL (default 30 minutes); the agent drains its spool on next poll
  3. A shared registry at `~/.claude/owlery/.registry` enables agents to discover each other's server addresses
  4. Every owl subcommand (setup, poll, deliver, reply, send, list, stop, cleanup-session, reboot, stash, session-resume, gsd-setup) passes its golden test with byte-identical output
  5. The single Rust binary replaces both owl.sh and live.sh -- `$OWL` and `$LIVE` env vars point to the same binary with different subcommand prefixes
**Plans:** 3/6 plans executed

Plans:
- [x] 06-01-PLAN.md -- Project restructure, dependencies, and common utility modules (output, owlery, types, auto-setup)
- [x] 06-02-PLAN.md -- P2P infrastructure: SQLite registry, per-perch spool, TCP protocol, process management
- [x] 06-03-PLAN.md -- Filesystem owl subcommands: setup, list, stop, cleanup-session
- [x] 06-04-PLAN.md -- Core P2P messaging subcommands: poll, deliver, reply, send
- [x] 06-05-PLAN.md -- Lifecycle subcommands: reboot, stash, session-resume, gsd-setup
- [x] 06-06-PLAN.md -- Integration wiring, native tests, golden test pass, and verification

### Phase 7: Live Parity & Distribution
**Goal**: All live subcommands work natively with the Psyche wrapper loop ported to Rust, and the binary is a copy-one-file drop-in replacement
**Depends on**: Phase 6
**Requirements**: LIVE-12, LIVE-13, LIVE-14, LIVE-15, LIVE-16, LIVE-17, LIVE-18, LIVE-19, LIVE-20, DIST-01, DIST-02, DIST-03, DIST-04
**Success Criteria** (what must be TRUE):
  1. `owl live start` launches an external Psyche process (claude CLI), registers Self perch, and outputs POLL_CMD -- the Psyche wrapper loop runs natively in the binary (not bash)
  2. All live subcommands (start, stop, revive, commune, list, list-psyches, context-save, psyche-download, clear-psyche, pulse-wait) pass their golden tests
  3. Updating `$OWL`/`$LIVE` env vars to point to the native binary is the only change needed -- SKILL.md and LIVE-SKILL.md require zero or minimal edits
  4. Bash scripts are retained as fallback and users can switch back by re-pointing env vars
  5. Installation is copy-one-file with no package manager, installer, or runtime dependencies
**Plans:** 1/4 plans executed

Plans:
- [x] 07-01-PLAN.md -- Simple filesystem live subcommands (list, list-psyches, context, pulse-wait, commune)
- [x] 07-02-PLAN.md -- Process management subcommands (stop, revive)
- [x] 07-03-PLAN.md -- Start subcommand with Psyche wrapper loop and generation tracking
- [x] 07-04-PLAN.md -- Golden test verification and distribution (SKILL.md/LIVE-SKILL.md updates)

### Phase 8: Timed Pulses
**Goal**: A user or agent can schedule a one-shot reminder at a specific future time, delivered as a pulse through the native binary
**Depends on**: Phase 7
**Requirements**: TPULSE-01, TPULSE-02, TPULSE-03
**Success Criteria** (what must be TRUE):
  1. Self can send a PULSE REQUEST with a target timestamp, and Psyche fires a TIMED PULSE to Self at approximately that time
  2. `/live timed-pulse {time} -- {message}` is a working user-facing command that schedules a timed pulse
  3. Timed pulses do not interfere with the regular periodic pulse cycle
**Plans**: 2 plans

Plans:
- [x] 08-01-PLAN.md -- Rust implementation: timed_pulse.rs, timed_pulse_wait.rs, cli.rs wiring, mod.rs dispatch
- [x] 08-02-PLAN.md -- psyche.md PULSE REQUEST handling section

### Phase 9: Spine Supervisor
**Goal**: Users running multiple live agents have a supervision layer that detects dead Psyches and notifies the affected Self for recovery
**Depends on**: Phase 7
**Requirements**: SPINE-01, SPINE-02, SPINE-03, SPINE-04, SPINE-05, SPINE-06, SPINE-07, SPINE-08, SPINE-09
**Success Criteria** (what must be TRUE):
  1. `/live boot-spine` starts a Spine agent that monitors Psyche health via a Touch subprocess (or absorbs Touch if subagent nesting is blocked)
  2. When a Psyche process dies, the affected Self receives a notification from Spine within approximately 5 minutes
  3. Spine cleans up orphaned perches when both Self and Psyche are gone
  4. `/live list-psyches` shows all Psyche agents (restricted visibility); Spine and Touch are hidden from all list commands
**Plans**: 3 plans

Plans:
- [x] 09-01-PLAN.md -- InfoJson spine/touch fields, list filters (owl/live/list-psyches), CLI BootSpine + hidden wrapper commands
- [x] 09-02-PLAN.md -- boot_spine.rs (Spine wrapper loop, PSYCHE_DEAD handling, perch cleanup) + touch_loop.rs (health-check, SPINE-09 fallback)
- [x] 09-03-PLAN.md -- mod.rs dispatch wiring, main.rs wrapper dispatch, live stop --all Spine/Touch teardown

## Progress

**Execution Order:**
Phases execute in numeric order: 5 -> 6 -> 7 -> 8 -> 9

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Foundation & Hardening | v1.0 | 3/3 | Complete | 2026-03-28 |
| 2. Psyche Core | v1.0 | 3/3 | Complete | 2026-03-28 |
| 2.1 Live Skill Extraction | v1.0 | 1/1 | Complete | 2026-03-28 |
| 2.2 Owl & Live Hardening | v1.0 | 4/4 | Complete | 2026-03-29 |
| 5. Golden Tests & CLI Skeleton | v1.1 | 2/3 | In Progress|  |
| 6. P2P Messaging & Owl Parity | v1.1 | 3/6 | In Progress|  |
| 7. Live Parity & Distribution | v1.1 | 1/4 | In Progress|  |
| 8. Timed Pulses | v1.1 | 2/2 | Complete | 2026-03-30 |
| 9. Spine Supervisor | v1.1 | 2/3 | In Progress|  |