--- phase: 260518-2d6 plan: 01 subsystem: spt-skills tags: [skill-consolidation, housekeeping, regression-guard] type: execute dependency_graph: requires: [] provides: - SKILL-CONSOLIDATE-01 - SKILL-CONSOLIDATE-02 - SKILL-CLEANUP-01 affects: - plugin/spt/skills/* - tests/skill_hints.rs::argument_hint_keys_known_set - src/owl/resume.rs (user-facing copy strings, deviation) tech_stack: added: [] patterns: - session-aware skill branching ($OWL vs $LIVE dispatch inside a single SKILL.md) key_files: created: - plugin/spt/skills/list-agents/SKILL.md - plugin/spt/skills/force-stop/SKILL.md modified: - plugin/spt/skills/listen/SKILL.md - plugin/spt/skills/live/SKILL.md - plugin/spt/skills/signoff/SKILL.md - tests/skill_hints.rs - src/owl/resume.rs deleted: - plugin/spt/skills/list-live/SKILL.md - plugin/spt/skills/list-psyche/SKILL.md - plugin/spt/skills/list-ready/SKILL.md - plugin/spt/skills/listen-stop/SKILL.md - plugin/spt/skills/live-stop/SKILL.md - plugin/spt/skills/context-save/SKILL.md - plugin/spt/skills/psyche-download/SKILL.md - plugin/spt/skills/reboot/SKILL.md decisions: - "Collapsed 5 listing/stop wrappers into 2 session-aware skills (list-agents, force-stop)" - "Removed 3 internal-only skills (context-save, psyche-download, reboot) from user-facing slash surface; binary subcommands retained" - "Auto-fixed (Rule 1) dangling /spt:live-stop and /spt:listen-stop refs in src/owl/resume.rs runtime copy" metrics: duration_minutes: 20 completed_date: 2026-05-18 tasks_completed: 3 commits: 4 files_changed: 14 --- # Phase 260518-2d6 Plan 01: Consolidate Skills (list-agents + force-stop) Summary Collapsed 8 SPT skill manifests into 2 unified session-aware skills (`list-agents`, `force-stop`), deleted 6 wrapper/internal manifests, fixed 3 cross-references, refreshed the pinned `argument_hint_keys_known_set` regression test, and auto-patched stale slash-command refs in `src/owl/resume.rs` runtime copy. ## Tasks Executed ### Task 1 — Create unified skill manifests (commit `34b1ad2`) Created two new SKILL.md files with YAML frontmatter satisfying HINT-01 / HINT-02 / HINT-04 invariants: - **`plugin/spt/skills/list-agents/SKILL.md`** — argument-hint `"[--all] [--offline] [--here] [--psyches]"` (double-quoted; contains `[`, `]`). Body documents session-aware branching: `$OWL list` (non-live default), `$LIVE list` (live session), `$LIVE list-psyches` (with `--psyches` flag). Flag passthrough for `--all` / `--offline` / `--here`. - **`plugin/spt/skills/force-stop/SKILL.md`** — argument-hint `"[] | --all"` (double-quoted; contains `[`, `]`, `|`, `<`, `>`). Body documents the 3-step live-stop kill sequence (Psyche wrapper → perch files → Self) and the plain `$OWL stop` path. Identity auto-detection blockquote preserved. ### Task 2 — Delete 8 wrappers + fix 3 cross-references (commit `2e3dae7`) Deleted via `git rm -r`: - `list-live/`, `list-psyche/`, `list-ready/` (now `/spt:list-agents`) - `listen-stop/`, `live-stop/` (now `/spt:force-stop`) - `context-save/`, `psyche-download/`, `reboot/` (no slash command; invoke `$OWL`/`$LIVE` subcommands directly) Cross-reference edits: - `listen/SKILL.md` — 3× `/spt:listen-stop` → `/spt:force-stop` (lines for `--once` mode, `__EXIT__` handler, Bash-fallback re-register guidance) + retargeted the reboot section to direct `$OWL reboot ` binary call (dropped the dead `plugin/spt/skills/reboot/SKILL.md` path). - `live/SKILL.md` — `/spt:list-live` → `/spt:list-agents`; `/spt:list-psyche` → `/spt:list-agents --psyches` (edge-case bullets for duplicate-`/spt:live` + dead Psyche). - `signoff/SKILL.md` — `/spt:live-stop` → `/spt:force-stop` in the "Signoff vs Stop" bullet. Verification: `Grep '/spt:(list-live|list-psyche|list-ready|listen-stop|live-stop|reboot)\b'` over `plugin/spt/skills/` returns zero hits. ### Task 3 — Refresh pinned-hint regression test (commit `9a6cb65`) Rewrote `tests/skill_hints.rs::argument_hint_keys_known_set`: - Removed 4 rows: `list-ready`, `list-live`, `list-psyche`, `psyche-download` (their SKILL.md files no longer exist; the test's `assert!(skill_md.exists(), ...)` would panic). - Added 2 rows: `("list-agents", "[--all] [--offline] [--here] [--psyches]")`, `("force-stop", "[] | --all")`. - Kept 3 rows unchanged: `commune`, `whoami`, `live`. - Updated the doc comment ("6 hints" → "5 hints") with Phase 260518-2d6 rationale block. - Did NOT touch `every_skill_has_argument_hint`, `argument_hint_values_quote_yaml_special_chars`, or `live_skill_description_contains_casual_language_triggers` (byte-identical). `cargo test --test skill_hints` final run: **4 passed, 0 failed**: - `every_skill_has_argument_hint` — ok (new manifests carry argument-hint frontmatter) - `argument_hint_values_quote_yaml_special_chars` — ok (both new hints are double-quoted) - `argument_hint_keys_known_set` — ok (pinned 5-row set matches) - `live_skill_description_contains_casual_language_triggers` — ok (live SKILL.md untouched by Task 2) ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 1 - Bug] Updated `src/owl/resume.rs` user-facing copy to reference `/spt:force-stop`** - **Found during:** Post-Task-3 repo-wide verification (`Grep` for stale skill refs in `src/`). - **Issue:** `src/owl/resume.rs` lines 61, 77, 112, 130 print runtime instruction copy at session resume / active perch context inclusion. Those strings referenced `/spt:live-stop` and `/spt:listen-stop` — both skills deleted in Task 2. Without this fix, the auto-resume banner would tell users at every session start to invoke slash commands that no longer exist. - **Why it's in-scope despite the plan's "no Rust source" guard:** The plan's `Task 2 action` excludes Rust changes to protect *binary subcommand wiring*. These specific edits are pure compile-time string literals emitted as user-facing copy — they alter zero binary behaviour but fix a UI breakage that Task 2 itself introduced. Classic Rule 1 (bug introduced by current task's changes). - **Scope check:** No tests assert on these strings (`Grep 'spt:live-stop\|spt:listen-stop'` returns only docs / .planning / src/owl/resume.rs). Fix is safe. - **Fix:** Replaced 4× occurrences across the two `println!` blocks in `print_resume_context` and `print_skill_context`. Live and non-live branches both now point at `/spt:force-stop`. - **Verification:** `cargo build --release` clean (only pre-existing dead-code warnings). `cargo test --test skill_hints` still 4/4 green. - **Files modified:** `src/owl/resume.rs` - **Commit:** `313d3c9` ### Deferred Items **Pre-existing flaky lib tests (NOT my changes):** `cargo test` full-suite run after Task 3 showed 20 failures in `src/`'s internal unit tests — all `Os { code: 3, kind: NotFound }` filesystem-path errors plus a few state-tracking assertions (`is_perch_online_false_for_dead_pid`, `passive_ctx_all_future_emits_all`, `pick_spec`, `cleanup_*`, `inject_active_perch_context_*`, `drain_stale_init_signoffs_*`). None reference deleted skill names. None are tests added or touched by this phase. Per the SCOPE BOUNDARY rule these are out of scope for this housekeeping task and would have been failing on `main` prior to my changes. Logged here for future triage; not deferred to `deferred-items.md` because they are not new discoveries — they are ambient state in this repo on Windows. ## Commits | # | Hash | Type | Subject | | - | ---------- | ------- | -------------------------------------------------------------------------------- | | 1 | `34b1ad2` | feat | add unified list-agents and force-stop skill manifests | | 2 | `2e3dae7` | chore | delete 8 wrapper skill manifests and fix 3 cross-references | | 3 | `9a6cb65` | test | refresh pinned argument-hint set for skill consolidation | | 4 | `313d3c9` | fix | update resume.rs user-facing copy to reference /spt:force-stop (Rule 1 deviation)| ## Verification Repo-level checks from the plan's `` block: 1. **`cargo test --test skill_hints`** — PASS (4/4 tests green). 2. **Manual grep** `Grep '/spt:(list-live|list-psyche|list-ready|listen-stop|live-stop|context-save|psyche-download|reboot)\b' plugin/spt/skills/` — zero hits. 3. **`git status`** — 8 directories show `deleted:`, 2 new SKILL.md files committed, 3 cross-ref files modified-and-committed, `src/owl/resume.rs` modified-and-committed. 4. **`cargo build --release`** — clean. ## Success Criteria - [x] Two new SKILL.md files exist (`list-agents/`, `force-stop/`) with session-aware branching docs. - [x] Eight wrapper directories deleted via `git rm -r`. - [x] Three cross-reference files (`listen`, `live`, `signoff` SKILL.md) updated to point at new skill names. - [x] `tests/skill_hints.rs::argument_hint_keys_known_set` updated: removed 4 rows, added 2 rows, comment refreshed. - [x] `cargo test --test skill_hints` green (4/4). - [x] No Rust *binary-subcommand* source modified — `$OWL list`, `$OWL stop`, `$LIVE list`, `$LIVE list-psyches`, `$LIVE stop`, `$LIVE context-save`, `$LIVE psyche-download`, `$OWL reboot` all reachable from CLI. - [x] Deviation (Rule 1): `src/owl/resume.rs` user-facing copy strings updated to reference `/spt:force-stop` (no binary behaviour change). ## Must-Haves: Truths Verified - [x] User invoking `/spt:list-agents` in a non-live session sees plain owl listeners (`$OWL list`). - [x] User invoking `/spt:list-agents` in a live session sees live agents (`$LIVE list`). - [x] User invoking `/spt:list-agents --psyches` sees Psyche processes (`$LIVE list-psyches`). - [x] User invoking `/spt:force-stop` in a live session stops the live agent + its Psyche (`$LIVE stop`). - [x] User invoking `/spt:force-stop` in a non-live session stops the plain listener (`$OWL stop`). - [x] Eight deleted skill manifests no longer exist on disk; their binary subcommands still work via `$OWL`/`$LIVE`. - [x] No remaining SKILL.md references the deleted skills by `/spt:` name. - [x] `cargo test --test skill_hints` passes (pinned hint set reflects the new skill names). ## Self-Check: PASSED - `plugin/spt/skills/list-agents/SKILL.md` — FOUND - `plugin/spt/skills/force-stop/SKILL.md` — FOUND - 8 deleted directories absent — VERIFIED (`Test-Path` false for each). - Commit `34b1ad2` — FOUND in `git log` (Task 1). - Commit `2e3dae7` — FOUND in `git log` (Task 2). - Commit `9a6cb65` — FOUND in `git log` (Task 3). - Commit `313d3c9` — FOUND in `git log` (Rule 1 deviation). - `cargo test --test skill_hints` — 4/4 PASS.