@younndai/lyt-skills 0.9.0

package/skills/lyt-retro/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: lyt-retro
+description: >
+  Write a deliberate retrospective on a session, sprint, or completed plan. Trigger when the user runs /lyt-retro, or says "retro this", "what did we learn", "lessons from this sprint", "post-mortem". Wraps `lyt pattern run work-management retro`. Writes to <vault>/Projects/<project>/work/<date>-retro-<slug>.md.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-retro
+
+Capture a deliberate retrospective. What worked. What didn't. What we'd change next time. Distinct from `/lyt-result` (which records WHAT shipped); a retro records WHY it went the way it did.
+
+## When to invoke
+
+- `/lyt-retro` slash trigger
+- "let's retro this"
+- end of a sprint, arc, project, or contentious decision
+- after a meaningful handoff (often required by the handoff-execute protocol)
+
+## Phase 1 — Resolve target
+
+Same chain as `/lyt-plan`. Slug usually matches the artifact being retro'd (e.g., `phase-7-session-2-bulk-init-patterns-skills-retro`).
+
+If retro'ing a specific session/sprint/handoff, set `retro-of:` frontmatter to its wikilink.
+
+## Phase 2 — Run the verb
+
+```
+lyt pattern run work-management retro --vault <vault> --project <project> --slug <slug>
+```
+
+## Phase 3 — Fill the body
+
+Sections to fill:
+
+- **What worked** — bullets, specific
+- **What didn't** — bullets, specific (no euphemisms)
+- **What we'd change next time** — bullets, actionable
+- **Lessons (durable enough to keep)** — if any rise to insight-level, promote
+
+## Promotion
+
+A retro's durable lessons promote either to:
+
+- `<date>-insight-<slug>.md` in the same `work/` folder (project-specific)
+- `Nuggets/<subject>/<date>-nugget-<slug>.md` at vault root (project-agnostic)
+
+## Companion skills
+
+- `/lyt-result` — what shipped (this retro reflects on)
+- `/lyt-insight` — durable lessons promoted from this retro

package/skills/lyt-search/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: lyt-search
+description: >
+  Search a Lyt pod (or a single mesh or vault) using the tiered-cascade engine — Tier 0 arcs (0.95) → Tier 1 lanes (0.90) → Tier 2 FTS5 (0.70) → Tier 3 edges (0.50) — with confidence ranking. Trigger when the user runs /lyt-search <query>, or says "search my pod for X", "find anything about X across my vaults", "search across all meshes for X", "what's in my pod about X", or similar phrasing on a query wider than a single vault. Wraps the `lyt search` CLI verb (v1.D.3b) — federation scope by default; --vault / --mesh narrow scope; --limit caps results. Returns ranked Figments with vault, mesh, snippet, and confidence. Companion to lyt-recall (single-vault keyword grep) for narrower local searches.
+visibility: public
+lyt-version: 0.5.0
+capabilities: [search]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-search
+
+Search a Lyt **pod** (default: every vault across every mesh) using the tiered-cascade engine. The skill is a thin LLM-driven wrapper around the `lyt search` CLI verb (shipped v1.D.3b); the heavy lifting — arc/lane/FTS5/edge cascade, confidence scoring, deterministic JSON emission — already lives in the CLI. The skill resolves the user's intent (query string + scope), invokes the verb with `--json`, parses the Lock 0.3 stable-key-ordered output, and presents ranked results to the handler.
+
+## When to invoke
+
+When the user runs `/lyt-search <query>`, or says something like:
+
+- "search my pod for <topic>"
+- "search across all my vaults for <topic>"
+- "find anything about <topic>"
+- "what's in my pod about <topic>"
+- "what did I write about <topic>" — _if the user's pod has multiple vaults_; for a single-vault keyword grep, prefer `/lyt-recall`
+- "search the `<mesh-name>` mesh for <topic>"
+- "search vault `<vault-name>` for <topic>"
+
+If the user's question depends on prior captured knowledge across multiple vaults, invoke this skill proactively — don't fabricate; check the pod first.
+
+## Phase 1 — Determine scope from user signal
+
+The CLI verb supports three mutually-exclusive scope flags; the default (no flag) is federation. Pick by the user's wording:
+
+- **Default — federation (entire pod, every vault across every mesh).** No scope flag. Use when the user says "my pod", "all my vaults", "everywhere", "across all meshes", or omits scope entirely. Invocation: `lyt search "<query>" --json`.
+- **Single mesh.** Use `--mesh <name>` when the user says "in mesh `<name>`", "across the `<name>` mesh", "in my `<name>` mesh". Invocation: `lyt search "<query>" --mesh <name> --json`.
+- **Single vault.** Use `--vault <name>` when the user says "in vault `<name>`", "in my `<name>` vault". Invocation: `lyt search "<query>" --vault <name> --json`.
+
+**Resolve names before passing them.** Don't guess at mesh/vault names — when the user names one:
+
+1. Run `lyt vault list --json` (vaults) or `lyt mesh list --json` (meshes) first.
+2. Match the user's term to the listed names (exact, then case-insensitive, then prefix).
+3. **Reject any resolved name that begins with `-` or `--`** before passing it to `--vault <name>` / `--mesh <name>` — closes the flag-injection surface the same way lyt-sync does at its Phase 1 (family: G.2 CR-1 gh-flag-injection). Vault names are user-controlled at vault-init time; a vault literally named `--evil` would otherwise smuggle a flag-shaped token into the verb's argv.
+4. If no match (or the only match is `--`-leading), tell the user the available names and stop — do not invent a name.
+
+Do **NOT** pass `--all` as an explicit flag — it's an alias for the default scope. Bare `lyt search` already searches federation; adding `--all` is redundant.
+
+## Phase 2 — Invoke the CLI verb
+
+Run the verb via the Bash tool (or your runtime's shell equivalent). **Pass the query as a single quoted argv argument; never shell-compose the command.** This matters because the user's query CAN contain shell metacharacters (backticks, `$()`, `;`, `&&`) — those MUST be conveyed as one argv element, not template-interpolated into a shell string.
+
+```
+# Shell-syntax (DOCUMENTATION ONLY — do NOT compose this as a string):
+lyt search "<user-query>" --json [--vault <name> | --mesh <name>] [--limit <n>]
+
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("lyt", ["search", userQuery, "--json", "--vault", vaultName]);
+# or with no scope flag (federation default):
+spawnSync("lyt", ["search", userQuery, "--json"]);
+```
+
+The Bash-tool variant: pass the argv array form to the tool's `args` field if the runtime exposes one; if the runtime only accepts a single shell-string, the LLM is responsible for shell-quoting `userQuery` correctly (this is the failure mode argv mode prevents). Precedent: lyt-sync's Phase 3 commits via `spawnSync("git", [..., "-m", message])` for the same reason.
+
+Key rules:
+
+- The first positional argument is the query — a single string. Multi-word queries are implicit AND. Quote the query so the shell treats it as one argv element.
+- `--json` is **mandatory** for this skill. It yields the deterministic Lock 0.3 stable-key-ordered output the skill parses below; without it, the CLI prints human-readable lines that the skill can't reliably parse.
+- `--limit <n>` defaults to 20 (CLI default), capped at 1000. Apply caller's `--limit` only when the user explicitly signals a cap ("top 5 results", "first 10"); otherwise rely on the CLI default.
+- Never combine `--vault` AND `--mesh` — the CLI rejects it with `error: "conflicting-scope-flags"` and exits 1.
+
+## Phase 3 — Parse the JSON output
+
+The CLI emits Lock 0.3 stable-key-ordered JSON on stdout (exit 0 on success). Expected shape:
+
+```json
+{
+  "query": "<the query>",
+  "scope": "federation" | "mesh" | "vault",
+  "scopeTarget": "<name>" | null,
+  "limit": 20,
+  "results": [
+    {
+      "confidence": 0.95,
+      "tier": 0,
+      "vault_name": "<vault>",
+      "mesh_name": "<mesh>",
+      "figment_path": "<relative/path.md>",
+      "snippet": "<≤80-char snippet>"
+    }
+  ],
+  "trace": {
+    "tiersRun": [0, 1, 2, 3],
+    "perTierHitCount": { "0": 1, "1": 3, "2": 12, "3": 4 },
+    "vaultsSearched": ["<vault1>", "<vault2>"]
+  },
+  "durationMs": 47
+}
+```
+
+Failure modes (CLI emits to stderr; exit non-zero):
+
+- **Empty query** (exit 1) → `{ "error": "empty-query", "message": "..." }`. Surface the message verbatim and ask the user to refine.
+- **Conflicting scope flags** (exit 1) → `{ "error": "conflicting-scope-flags", "flags": [...], "message": "..." }`. Skill-level bug if hit — Phase 1 should have prevented it; surface and stop.
+- **Invalid limit** (exit 1) → `{ "error": "invalid-limit", "value": "<bad>", "message": "..." }`. Re-invoke with the CLI default.
+- **Cascade error** (exit 2) → `{ "error": "cascade-error", "message": "..." }`. Surface verbatim; suggest re-running with narrower scope.
+
+## Phase 4 — Format results for the handler
+
+Group by mesh, then by vault within mesh. Order results within each vault by descending confidence (the CLI emits them ranked already). One line per result.
+
+The CLI emits each result with TWO ranking fields — `confidence` (the float: 0.95/0.90/0.70/0.50) and `tier` (the int: 0/1/2/3, where 0=arcs, 1=lanes, 2=FTS5, 3=edges). The two are isomorphic (one tier-int maps to one canonical confidence), so the handler-facing display shows `confidence` only (it's the more readable signal). The `tier` field stays in the JSON for callers that need to filter by tier source; the skill does not surface it in the one-line format.
+
+Format:
+
+> **Found N matches for `"<query>"` (scope=federation, <durationMs>ms · tiers: <tier counts>):**
+>
+> **Mesh: `<mesh1>`**
+>
+> - `[0.95]` `<vault1>/notes/2026-05-24-q4-planning.md` — _the auth rewrite is a P0 for Q4..._
+> - `[0.70]` `<vault1>/notes/2026-05-23-auth-decisions.md` — _moving to OAuth, deprecating session tokens..._
+>
+> **Mesh: `<mesh2>`**
+>
+> - `[0.50]` `<vault2>/notes/2026-05-22-stand-up.md` — _...session tokens flagged by legal..._
+
+Show each result as `[<confidence>] <vault>/<figment_path> — <snippet>`. Truncate snippets to ~80 characters with an ellipsis. The top-of-output tier-hit summary uses the CLI's `trace.perTierHitCount` map (`{0:N, 1:M, 2:K, 3:L}`) so the handler sees confidence distribution at a glance.
+
+On **empty results**: surface _"No matches for `"<query>"` across <scope>."_ and offer scope-widening hints (`--mesh` → federation; `--vault` → `--mesh`).
+
+## Rules
+
+- **MUST pass the user's query as a single quoted argv argument**, not template-interpolated into a shell command string. Filenames or queries containing shell metacharacters (`` ` ``, `$(...)`, `;`, `&&`) inside the query MUST be safely conveyed as argv.
+- **MUST pass `--json`** on every invocation. Human-readable output is not a contract this skill parses.
+- **MUST resolve mesh/vault names via `lyt vault list --json` or `lyt mesh list --json` before passing `--vault` or `--mesh`.** Do not guess names.
+- **MUST NOT pass `--all` explicitly.** Federation is the default; `--all` is a redundant alias. Use no scope flag instead.
+- **MUST NOT combine `--vault` and `--mesh`.** The CLI exits 1 with `conflicting-scope-flags`.
+- **MUST NOT re-interpret confidence tiers.** The CLI emits them as `0.95 / 0.90 / 0.70 / 0.50` per Tier 0/1/2/3 spec. Display verbatim; do not "smooth" or "round" or invent a derived score.
+- **MUST NOT modify or write any vault file.** This is a read-only skill (`requires_writable_vault: false`). If the user wants results persisted to a Figment, run `/lyt-capture` separately on the formatted output.
+- **MUST NOT widen scope without user signal.** If the user said "in my work vault", do not silently fall back to federation when the named vault is missing — surface the miss and stop.
+
+## Companion skills
+
+- **`/lyt-recall`** — single-vault keyword grep. Use when the user has only one vault in mind and wants filesystem-level grep semantics rather than the tiered-cascade engine.
+- **`/lyt-sync`** — pull-then-push a vault. Run before `/lyt-search` if the user has unpushed local edits and wants the FTS5 index reflect them (the cascade reads the local vault's libSQL state).
+- **`/lyt-capture`** — write a Figment. Pair with `/lyt-search` if the user wants the recall results persisted.

package/skills/lyt-sync/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: lyt-sync
+description: >
+  Sync a Lyt vault — pull from its GitHub repo, auto-commit any uncommitted local changes (with an inferred commit message or a handler-supplied one), then push back to origin gated on the 6-reason writable verdict from `vault info --json`. Trigger when the user runs /lyt-sync, or says "sync this vault", "pull and push", "sync my notes", "push my changes", or similar phrasing. Wraps `git pull --rebase`, dirty-tree detection, commit, and push under the hood. Read-only / subscriber / orphan / no-remote / gh-offline vaults pull but skip push and surface a reason-specific handler message. Pairs with /lyt-capture.
+visibility: public
+lyt-version: 0.4.0
+capabilities: [read, write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-sync
+
+Sync a Lyt vault — pull, detect-and-commit local changes, push (gated on the v1.G.2 writable verdict). The skill always runs; the push step gates internally on the 6-reason `writable` contract from `lyt vault info --json`, so even read-only / subscriber / orphan / no-remote vaults pull cleanly without touching origin.
+
+## When to invoke
+
+When the user runs `/lyt-sync`, or says something like:
+
+- "sync this vault"
+- "sync my notes"
+- "pull and push"
+- "push my changes"
+- "sync `<vault-name>`"
+- "/lyt-sync `<vault-name>`"
+
+If the user says "save and sync" or "/lyt-capture then sync", run /lyt-capture first, then /lyt-sync on the destination vault.
+
+## Phase 1 — Resolve the target vault
+
+Follow this chain, in order, and stop at the first success (mirrors /lyt-capture Phase 1):
+
+1. **`--vault <path>` argument** — if the user passed one in the invocation, use it as-is (resolve to absolute path if relative).
+2. **`$LYT_ACTIVE_VAULT` environment variable** — if set, use it.
+3. **`~/lyt/vaults/<handle>/main/`** — the default convention per the unified `{handle}/{repo}` naming (Windows: `%USERPROFILE%\lyt\vaults\<handle>\main`). Resolve `<handle>` from the pod identity (`identity.yon` / `pod.yon`); never hardcode it.
+
+Do **not** guess from cwd. If `--vault` / env var / home convention all miss, ask the user which vault to target — fabricating a path from cwd would silently operate on the wrong tree.
+
+If the resolved path **does not exist or is not a Lyt vault** (no `.lyt/vault.yon` inside), do **not** attempt git operations. Stop and tell the user:
+
+> The target vault `<path>` doesn't exist (or isn't a Lyt vault — no `.lyt/vault.yon`). Use `lyt vault init <name>`, or pass `--vault <existing-path>`.
+
+**Path-shape safety check.** Before invoking `git -C <vault-path>`, reject any resolved path that begins with `-` or `--` (defensive against a crafted `--vault` argument, `$LYT_ACTIVE_VAULT` env value, or any other resolver-input that could smuggle a flag-shaped token into the git positional). The `.lyt/vault.yon` existence check above already filters most invalid paths; this `--`-leading rejection closes the remaining flag-injection surface (same family as the G.2 CR-1 gh-flag-injection close). Resolved paths MUST be absolute and MUST start with a drive letter (Windows) or `/` (POSIX) before they enter any `git` argv.
+
+## Phase 2 — Pull with rebase
+
+Shell out to git directly with the vault path as `cwd`:
+
+```
+git -C <vault-path> pull --rebase
+```
+
+(On Windows, `git -C <path>` works with quoted paths, but the lyt-vault precedent — `flows/clone.ts`, `flows/repair.ts`, `util/git-history.ts` — uses `spawnSync` with `cwd: <vault-path>` so the path doesn't need to be embedded in argv. Skill prose recommends the `cwd` shape for cross-platform stability.)
+
+**On rebase conflict** (`git pull --rebase` exits non-zero with conflict markers): per the ratified default (2026-06-01), do NOT attempt auto-resolution. Surface a structured result to the handler and halt:
+
+```json
+{
+  "status": "conflict",
+  "vault": "<vault-name>",
+  "conflicted_files": ["<path1>", "<path2>"],
+  "message": "git pull --rebase failed; resolve the listed conflicts manually, then re-invoke /lyt-sync."
+}
+```
+
+The handler-facing prose to surface: _"Sync halted on rebase conflict in `<vault-name>`. Resolve the conflicts in `<files>`, then run `/lyt-sync` again."_
+
+## Phase 3 — Detect + commit local changes
+
+Run `git -C <vault-path> status --porcelain`. If the output is empty, skip to Phase 4 with a "no local changes" note for the handler. Otherwise:
+
+1. Parse the porcelain output into a `GitDiffSummary`-shaped object (`{staged: string[], modified: string[]}`). Porcelain v1 (the default) emits one line per change with a 2-character prefix: column 1 is the index/staged status, column 2 is the working-tree status. Treat any line whose column-1 char is not space or `?` as **staged** (e.g. `A `, `M `, `MM`, `D `); treat any line whose column-2 char is not space (or whose prefix is `??`) as **modified**. Strip the 3-character prefix to recover the file path. Files that appear staged AND modified land in both arrays — that's tolerated; the helper sorts and de-orders naturally and the resulting message just lists the file once or twice depending on its multi-state shape.
+2. Decide on a commit message. The skill exposes one **caller-options**-style choice:
+
+- `options.commit-message: "auto"` _(default — the oversight handler default per the ratified default)_ — call the `inferCommitMessage(diff)` heuristic to summarise the diff:
+- 0 files → `"no changes"` _(defensive; unreached because porcelain was non-empty)_
+- 1 file (non-mesh.yon) → `"sync: <filename>"`
+- 1 file (mesh.yon, at any depth) → `"sync: mesh.yon update"`
+- 2-4 files → `"sync: N files (<comma list>)"`
+- > 4 files → `"sync: N files (<first 3>, +M more)"`
+- `options.commit-message: "prompt-handler"` — pause and ask the handler for a one-line message; do not invent one.
+
+The heuristic lives in `packages/lyt-vault/src/util/sync-helpers.ts` as `inferCommitMessage`; the skill prose reproduces the rules above so an agent can run them inline without importing.
+
+3. Stage and commit. **Pass the message via argv, NOT through shell interpolation.** The shell-syntax pseudocode below is for documentation only; agents executing this skill MUST translate it to an argv-safe `spawnSync` / `execFileSync` call so a filename containing shell metacharacters (backticks, `$()`, `;`, `"`) inside the inferred message can't escape into command execution. Concretely:
+
+```
+# Pseudocode (DO NOT shell-interpolate):
+git -C <vault-path> add -A
+git -C <vault-path> commit -m "<message>"
+
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("git", ["-C", vaultPath, "add", "-A"]);
+spawnSync("git", ["-C", vaultPath, "commit", "-m", message]);
+```
+
+The matching precedent lives in `packages/lyt-vault/src/flows/clone.ts:87` (`execFileSync("git", ["clone", opts.url, target])`) — the same argv-array shape used everywhere the lyt-vault flow layer shells to git.
+
+Do **not** add a `Co-Authored-By` trailer (per the project's `CLAUDE.md` commit conventions). Do **not** add an `@STAMP` block — that is a `.yon`-write concern handled by lyt-runner, not the sync skill.
+
+## Phase 4 — Push (gated on the 6-reason writable verdict)
+
+Invoke `lyt vault info <vault-name> --json` and parse the `vault.writable` and `vault.writableDetermination` fields per the v1.G.2 read-only-awareness contract (see `packages/lyt-vault/src/flows/writability.ts:42-48`). The verdict is tri-state (`true | false | "unknown"`); the determination is one of **6 reasons** the skill must branch on explicitly.
+
+The actual reason strings emitted by `vault info --json` (per writability.ts at HEAD `16ccdf6`) are listed in the **emitted name** column. The **semantic name** column gives the human-readable synonym some briefs use; the SKILL.md surface uses the semantic name in handler-facing prose, but the comparison MUST be against the emitted name.
+
+| Emitted name (writableDetermination) | Semantic name               | writable    | Phase 4 behavior                                                                                                                                               |
+| ------------------------------------ | --------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gh-viewerCanPush-true`              | **home-pushable-true**      | `true`      | Push: `git -C <vault-path> push`. Report: _"Synced and pushed N commits to origin."_                                                                           |
+| `gh-viewerCanPush-false`             | **home-not-pushable-false** | `false`     | Skip push. Report: _"Skipped push: you don't have push permission on `<vault.gitUrl>`. Request write access from the owner, or capture into a vault you own."_ |
+| `subscriber-default-false`           | (subscriber)                | `false`     | Skip push. Report: _"Skipped push: this is a subscriber vault. Subscriber vaults pull but don't push. Capture into your home vault instead."_                  |
+| `gh-unavailable`                     | (gh-offline)                | `"unknown"` | Skip push. Report: _"Skipped push: gh CLI is unavailable (offline / rate-limited / not authenticated). Re-try when network is available."_                     |
+| `no-remote`                          | (no-remote)                 | `"unknown"` | Skip push. Report: _"Skipped push: vault has no git remote configured. Configure a remote with `gh repo create` or `git remote add origin <url>`."_            |
+| `orphan-vault`                       | (orphan)                    | `"unknown"` | Skip push. Report: _"Skipped push: vault has no mesh role (orphan). Adopt into a mesh with `lyt mesh adopt --cluster <name>`."_                                |
+
+**Note on emitted vs semantic names.** The brief that authored this skill (v1.G.3 handoff) lists `home-pushable-true` and `home-not-pushable-false` as the writable-determination reason strings. The actual strings emitted by `writability.ts` are `gh-viewerCanPush-true` and `gh-viewerCanPush-false`. The semantic names are kept here as a documentation alias so future renames of the underlying enum (e.g. when the gh-probe naming hardens in v1.G.2.1) don't silently break the skill prose. The 4 unchanged reason strings (`subscriber-default-false`, `gh-unavailable`, `no-remote`, `orphan-vault`) match in both surfaces.
+
+Final handler-facing result shape:
+
+```json
+{
+  "status": "ok",
+  "vault": "<vault-name>",
+  "pulled": true,
+  "committed_message": "<message>" | null,
+  "pushed": true | false,
+  "skipped_push_reason": "<one of the 6 writableDetermination values>" | null,
+  "handler_message": "<reason-specific prose from the table above>"
+}
+```
+
+## Rules
+
+- **MUST NOT auto-resolve a rebase conflict.** Halt with the structured-output shape in Phase 2 and let the handler resolve manually. Per the ratified default.
+- **MUST gate push on `vault.writable` / `vault.writableDetermination`.** Never `git push` unless `writableDetermination === "gh-viewerCanPush-true"` (equivalently, `writable === true`). The other 5 reasons all skip push.
+- **MUST branch on all 6 reasons.** Each has a distinct handler-facing message; collapsing them into a generic "can't push" message loses semantic signal the handler needs to recover.
+- **MUST NOT add a `Co-Authored-By` trailer** to the auto-commit. Per the project's `CLAUDE.md` commit conventions, unless the user explicitly requests one.
+- **MUST NOT touch any vault other than the resolved target.** Sync is single-vault. A multi-vault sweep is `mesh clone-all` / a future `lyt sync --mesh` verb, not this skill.
+- **MUST NOT modify `.lyt/vault.yon`, `.lyt/mesh.yon`, ledger YONs, or `@STAMP` blocks.** Those are runner / writer concerns; sync only commits handler-authored content as-is.
+- **MUST NOT silently degrade `writable === "unknown"` to push.** Surface the reason to the handler.
+
+## Companion skills
+
+- **/lyt-capture** — write a Figment into a vault. /lyt-sync is the natural follow-up when the captured vault has push access.
+- **/lyt-recall** — search the vault. Read-only; no sync interaction.