# Owl Skill (SPT — Spacetime / Sentience Pocket Transacter) ## What This Is A zero-dependency inter-agent messaging and live-agent lifecycle system for Claude Code, shipped as the `spt` plugin via the `cplugs` marketplace. Native Rust binary (`owl.exe`) uses TCP-primary delivery with SQLite spool fallback. Live agents run a detached Psyche wrapper (periodic `claude -p --resume` sessions) that absorbs `COMMUNE` updates from Self and reacts to scheduled pulses, file-drops, and SessionStart boundaries. Listener now streams `` envelopes via Claude Code's Monitor tool. Used by multiple people — Windows-native portability with no runtime dependencies is a hard constraint. ## Core Value Reliable, zero-dependency agent-to-agent messaging that just works on any machine, with a live-agent layer that survives `/clear`, `/compact`, binary handoffs, and orphan boundaries without losing context. ## Current State **Shipped: v1.7.1 Seamlessification II** (2026-05-18; deployed v1.10.13) Four phases (31-34) closed out the v1.7 polish arc — listing/picker correctness, skill hint surface, fresh-start commune flow, version-change notification: - **Phase 31** — `$LIVE pick-spec` `kind:"all-live"` variant (additive, D5 schema freeze preserved) - **Phase 32** — `--all` / `--offline` / `--here` flags default-online; 17/17 SKILL.md `argument-hint` frontmatter coverage - **Phase 33** — First-commune AskUserQuestion + `/spt:live --auto` + SessionStart `` emission + 8 casual-language triggers (3 explicit non-triggers) - **Phase 34** — `$SPT_HOME/last-seen-version.json` sentinel + Stop-hook silent owl-message transport + CHANGELOG.md (40 H2 entries) + DEPLOY.ps1 curation gate 11 plans, 94+ commits, 3-day execution window. Hotfix bundle folded in (260517-6om transport pivot, 260517-n4b UAT defect cleanup, 260517-wpf CHANGELOG-ordering closure). 39/39 v1.7.1 requirements verified end-to-end (6/6 cross-phase wiring + 6/6 E2E flows). Audit: `.planning/v1.7.1-MILESTONE-AUDIT.md` — PASS.
Previously shipped: v1.7 Seamlessification (2026-05-16; deployed v1.10.10) Five phases (26-30) focused on friction removal across the live-agent lifecycle: - **Phase 26** — `/spt:live` auto-pick + AskUserQuestion fork + free-text resolve - **Phase 27** — Listener poll migrated from Bash to Monitor tool (streaming `` envelopes) - **Phase 28** — SessionStart injects `` on live perches (`/clear` & `/compact`) - **Phase 29** — Auto-fire echo-commune at boundaries + typed `` envelope cutover - **Phase 30** — Commune/signoff file-drop protocol (`.claude/{id}-{commune,signoff}.md`) replaces stdin piping 26 plans, 211 commits, 7-day cycle. Off-roadmap sub-iterations 18.x continued through v1.10.x defense-in-depth deploys (stale-signoff drain, init_signoff envelope-shape predicate, FileDropOutcome::BreakLoop).
## Next Milestone Goals **v1.8 Psyche Restructure** — Phases 23/24/25: - Phase 23 — commune/signoff project-root + HEAD SHA stamping (per-repo context isolation) - Phase 24 — tracked-dir per-agent layout + sessions audit log - Phase 25 — psyche perch nesting + general/project context split - Phase 25.4 ✓ (2026-05-24) — central perch-path resolver (`src/common/perch_path.rs`) as single source of truth; all psyche/worker writers + 8 Class-E readers + 3 wrapper-state writers routed through resolver; operator-verified end-to-end (zero flat psyche/worker dirs post-deploy) Backlog candidates surfaced during v1.7.1: - Deferred PICK-03 (`online: bool` field on `kind:"pick"`) - `download_payload_for_injection` SessionStart destructive default — `--read-only` flag consideration - Shared-sentinel awareness (Phase 34 + quick-260517-rhw primer co-consume `$SPT_HOME/last-seen-version.json`) - 21 unrelated parallel-test failures in Phase 18/28/30/32 surfaces (pass in isolation; cleanup quick task candidate) ## Requirements ### Validated - ✓ Harden owl.sh against race conditions and edge cases — v1.0 - ✓ Unified output formatting: compact symbols, ANSI color codes, no emoji — v1.0 - ✓ Auto-setup env vars and session cleanup hook — v1.0 - ✓ Live Agent start + Psyche subagent + periodic pulse + COMMUNE format — v1.0 - ✓ Native Rust binary with P2P TCP messaging + SQLite offline spool — v1.1 - ✓ Golden test suite + cross-platform CI (4 targets) — v1.1 - ✓ Timed pulses + Spine supervisor + single-binary drop-in — v1.1 - ✓ Plugin migration to `/spt` namespace — v1.5 - ✓ Spacetime filesystem (`%LOCALAPPDATA%\spt` / `~/.spt`) with `SPT_HOME` override — v1.5 - ✓ Persistent offline perches + indefinite queueing + reconnection — v1.5 - ✓ Memformat-driven Psyche brainstorming + INSIGHT messages — v1.5 - ✓ PerchState enum + owl doctor + session detection + optional agent_id — v1.5 - ✓ Hand-rolled MCP server (JSON-RPC over stdio) — v1.6 - ✓ Spool unification (peek_all + mark_delivered) + Result variant refactor — v1.6 - ✓ 13 MCP tools + 5 MCP resources + check-on-request notifications — v1.6 - ✓ Seamless binary handoff for long-running spt processes — v1.6 (Phase 18.4/18.5 sub-iterations) - ✓ Echo-commune fresh-session jsonl excerpt + 15-min cadence gate — v1.6 (Phase 18.8 sub-iteration) - ✓ `/spt:live` auto-pick + AskUserQuestion fork + `$LIVE pick-spec`/`$LIVE fork` — v1.7 - ✓ Listener poll: Monitor tool primary + `` envelopes + Bash `--once` fallback — v1.7 - ✓ SessionStart `` injection on live perches — v1.7 - ✓ Auto-fire echo-commune on `/clear`+`/compact`+orphan; typed envelope cutover — v1.7 - ✓ Commune/signoff file-drop protocol (`.claude/{id}-{commune,signoff}.md`) — v1.7 ### Active - Phase 23 — Commune/signoff payload includes `project_root` + `HEAD` SHA (v1.8 candidate) - Phase 24 — `psyches/tracked//` per-agent layout + sessions audit log (v1.8) - Phase 25 — Psyche perch nesting + general.md / proj-{project}.md context split (v1.8 — central resolver landed in Phase 25.4) - Phase 19-22 — Capsule (psmux-based sendkeys pipeline, abrupt messages, GSD proceed via sendkeys) (v1.9) - Resolve `psyche-stale-after-clear` debug session (root cause known, fix pending) - 2 Phase 28 raw-stdout /clear-cycle Human-UAT tests (deferred, non-blocking) - Phase 35.2 — psyche-sync-setup second-machine data-loss + bootstrap-determinism fix landed in code (5/5 reqs verified; pending deploy + 2 Human-UAT items: Unix e2e + real-GitHub second-machine attach). `sync-setup-data-loss` debug Issues 3–6 deferred to Phase 35.3 (v1.8) ### Out of Scope - macOS/Linux-specific features — cross-platform CI covers builds but not platform-specific optimizations - External dependencies beyond the single binary — copy-one-file install is core constraint - MCP transport prioritization — deprioritized post-v1.6 in favor of CLI-first model (see `feedback_mcp_performance.md`); MCP layer remains but Phase 18.1+ sub-iterations refactored away from MCP-centric flows ## Context - v1.7 lands at ~23,886 LOC across src/ + plugin/ (Rust + skill markdown + JSON manifests) - Tech stack: Rust (clap, serde/serde_json, chrono, rusqlite, ctrlc; libc on Unix, windows-sys on Windows) - IPC: TCP primary, SQLite spool fallback; runtime state under `%LOCALAPPDATA%\spt\owlery\` (Windows) / `~/.spt/owlery/` (Unix) - Distribution: `cplugs` marketplace plugin; deploy via `docs/DEPLOY.ps1` (Windows-native primary path) - Plugin version of record: `plugin/spt/.claude-plugin/plugin.json` (current: v1.10.10) - Listener poll runs in Monitor-tool stream mode; Bash `--once` fallback retained per-skill - Live agents survive binary handoff via wrapper-state.json rehydration when `installed_plugins.json` flips - Known tech debt: AUTO-EC + SC entries in REQUIREMENTS.md milestone table were backfilled at v1.7 audit; Phase 27 VERIFICATION.md was backfilled at audit time; Bash `--once` fallback is a future cleanup candidate when Monitor tool reaches universal Claude Code coverage ## Constraints - **Platform**: Must work on Windows Git Bash with zero external dependencies (bash + coreutils only) - **Portability**: Shared with other users — install must be copy-files-and-go - **Backward compat**: Existing `/owl` commands must continue working unchanged - **Script exposure**: All complex logic lives in `owl.sh`/`live.sh` — agents should never compose raw complex terminal commands (per SKILL_SPEC-LIVE.md rule) ## Key Decisions | Decision | Rationale | Outcome | |----------|-----------|---------| | ANSI color + compact symbols for output | User wants scannable, visually distinct output without emoji | ✓ Good — cyan owl, orange live | | Live spec is flexible on details | Core concepts solid, implementation refined during planning | ✓ Good — all concepts shipped | | Research-first approach to hardening | Don't fix what isn't broken — analyze before acting | ✓ Good — targeted fixes only | | P2P TCP (not central daemon) | Each agent runs local server, shared registry for discovery | ✓ Good — sub-second delivery | | SQLite spool per perch | Offline message queuing with TTL for when target is down | ✓ Good — 30min default TTL | | Psyche wrapper in native binary | include_str! embeds psyche.md, no runtime file dependency | ✓ Good — single binary | | Sync TCP (not tokio/async) | Single-connection contract, async adds complexity for zero benefit | ✓ Good — simpler, smaller binary | | Poison file shutdown for Windows | Windows Git Bash lacks kill -USR1, .stop sentinel works everywhere | ✓ Good — cross-platform | | Touch as pure Rust (not Claude session) | No LLM reasoning needed for PID checking, satisfies SPINE-09 | ✓ Good — cheaper, always works | | Plugin namespace `/spt` (v1.5) | Group owl + live commands; ship via `cplugs` marketplace | ✓ Good — clean install path | | Spacetime filesystem out of `~/.claude` (v1.5 Phase 18.2) | `~/.claude` is volatile / cleared by user actions; spt runtime needs durable state | ✓ Good — survives /clear | | Hand-rolled MCP server, no tokio (v1.6) | Single-connection contract; async adds complexity for zero benefit | ✓ Good — small binary, no deps | | MCP transport deprioritized post-v1.6 | Performance overhead vs CLI not justified for this scale | ⚠️ Revisit if remote agents added | | Seamless binary handoff (v1.6 Phase 18.4/18.5) | Long-running spt processes can't be killed on deploy without losing live state | ✓ Good — wrapper-state.json rehydration works | | Echo-commune via fresh-session jsonl excerpt (v1.6 Phase 18.8) | Self-jsonl write contention killed in-process echo; spawn fresh session reads cleanly | ✓ Good — no contention since | | Monitor tool as primary poll transport (v1.7 Phase 27) | Eliminates per-message Bash spawn overhead and prompt prefix; Bash `--once` retained as fallback | ✓ Good — lower context cost per message | | File-drop protocol over stdin pipe for commune/signoff (v1.7 Phase 30) | stdin piping was lossy under listener handoff; `.claude/{id}-{commune,signoff}.md` is durable + atomic | ✓ Good — survives wrapper restart, listener exits clean on signoff | | Auto-fire echo-commune at `/clear`+`/compact`+orphan (v1.7 Phase 29) | Self-side delta was lost at boundaries; wrapper-driven fire captures it | ✓ Good — Psyche stays current | | Destructive consume of drop-files at psyche-download (v1.7 quick-260515-uf1) | Non-destructive Pending sections looped forever in SessionStart injection | ✓ Good — one-shot consume, retain-on-error | | Typed `` envelope cutover (v1.7 Phase 29) | Legacy prose envelope ambiguous with normal messages; typed envelope enables provenance + cleaner parsing | ✓ Good — repo-wide cutover clean | ## Evolution This document evolves at phase transitions and milestone boundaries. **After each phase transition** (via `/gsd:transition`): 1. Requirements invalidated? → Move to Out of Scope with reason 2. Requirements validated? → Move to Validated with phase reference 3. New requirements emerged? → Add to Active 4. Decisions to log? → Add to Key Decisions 5. "What This Is" still accurate? → Update if drifted **After each milestone** (via `/gsd:complete-milestone`): 1. Full review of all sections 2. Core Value check — still the right priority? 3. Audit Out of Scope — reasons still valid? 4. Update Context with current state --- *Last updated: 2026-05-30 after Phase 35.3 (psyche-sync-setup UX pass — error Display flip, doctor partial-state Warn row, exit-1 + recovery docs, and the non-git-host tracked-context sync fix / Issue 7) completion in v1.8*