---
quick_id: 260517-rhw
slug: spt-first-install-primer-flow
date: 2026-05-18
status: ready-for-planning
---

# Quick Task 260517-rhw: SPT First-Install Primer Flow — Context

**Gathered:** 2026-05-18
**Status:** Ready for planning

<domain>
## Task Boundary

On first install of the SPT plugin, prompt the user with a Yes/Skip AUQ:

> "The SPT plugin is installed! Do you want a brief primer?" [Yes/Skip]

If **Yes**, the agent returns a nicely formatted, color-coded blurb:

```
--- SPT Getting Started ---
1. Start a live agent: Call `/live` in any session
2. `/clear` whenever you want: Your live agent will retain the important details across sessions.
3. Capture context: if you want to make sure an agent remembers something, use `/commune`. This happens routinely in the background, too
4. Message other agents: check availability with `/list-agents`, and message with `/send`. Or simply have your live agent do it!
5. End the session. You can call `/signoff` for a clean finish, or just close out. If your PC is running, the live agent's background "psyche" will capture everything from before the session ended
```

Flow mirrors the Phase 34 version-change-changelog plumbing but uses **PreToolUse hook** (NOT Stop hook) for the additionalContext + AUQ injection.

</domain>

<decisions>
## Implementation Decisions

### Trigger + Suppression
- **Sentinel:** Presence of `$SPT_HOME/last-seen-version.json` indicates the plugin has already run at least once.
- **First install = file absent.**
- **Single sentinel.** Reuse the existing `version_changelog::write_sentinel(&str)` at `src/owl/version_changelog.rs:112-115` and `owlery::sentinel_path()` at `src/common/owlery.rs:116-118`. There is NO second "plugin-dir version sentinel" to write — only `$SPT_HOME/last-seen-version.json` exists in shipped Phase 34 code. Writing it satisfies BOTH primer suppression AND prevents the next-session version-change banner.
- **Write timing: emit-time.** Sentinel written when the PreToolUse hook spools the primer message, NOT after AUQ ack. Closing the session before answering will not re-prompt.
- Both Yes and Skip suppress the primer for subsequent sessions (already guaranteed by emit-time write).

### Delivery Mechanism
- **PreToolUse hook** detects absent sentinel and emits `additionalContext` JSON to stdout **DIRECTLY** from the hook process. No perch lookup, no spool, no owl-message envelope, no `format_owl_messages` wrapper.
- **Why direct, not spool:** fresh-install user has NEVER run `/live`/`/owl`/anything → no perch exists → `find_perch_cached` returns None → the spool/perch transport never fires for this user. Primer MUST work for perch-less sessions.
- Hook process produces JSON of the shape `{"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": "<spt-primer>...</spt-primer>"}}` directly. Bypasses `handle_parent`'s perch gate.
- additionalContext payload is plain-text instruction to the agent: fire a 2-option Yes/Skip AUQ; on Yes, render the primer body inside a fenced monospace block.
- **`is_informational` extension NOT required** — that predicate gates the owl-message banner wrapping in `format_owl_messages`. Primer skips that wrapper entirely, so no STOP-banner risk. Defect-260517-n4b is structurally not reachable from this path.

### Primer Content + Formatting
- **Use the exact slash commands as written** in the user-supplied blurb: `/live`, `/clear`, `/commune`, `/list-agents`, `/send`, `/signoff`. Verbatim. No name auto-correction.
- **ANSI + monospace presented by the AGENT, not in additionalContext.** The additionalContext text itself is plain (ANSI in JSON-string additionalContext renders as literal `\x1b[36m`). The agent, after the user picks Yes, prints the primer body in chat using ANSI color codes from `src/common/output.rs:6-7` (`C_CYAN = "\x1b[36m"`, `C_ORANGE = "\x1b[38;5;208m"`) inside a ``` fenced monospace block.
- Header `--- SPT Getting Started ---` rendered as-is, centered or left-aligned in the monospace block.

</decisions>

<specifics>
## Specific Ideas

- Phase 34 (`.planning/phases/34-version-change-changelog/`) is the structural reference: same sentinel/parser/payload/hook-wiring stack, swapped from Stop → PreToolUse.
- `$SPT_HOME` resolution already implemented in `src/common/owlery.rs`.
- `last-seen-version.json` is the chosen sentinel — research must confirm the existing version-change-changelog sentinel path/format so this task reuses it instead of inventing a parallel file.
- Plugin-dir version sentinel update logic also already exists in the Phase 34 stack; primer handler calls into the same code path.

</specifics>

<canonical_refs>
## Canonical References

- `.planning/phases/34-version-change-changelog/34-01-PLAN.md` through `34-03-SUMMARY.md` — version-change-changelog implementation
- `src/common/owlery.rs` — `$SPT_HOME` resolution + status tag color palette
- `plugin/spt/hooks/` — existing hook wiring (PreToolUse, Stop, SessionStart)
- `CLAUDE.md` — output color conventions (owl cyan, live orange)

</canonical_refs>