@younndai/lyt-skills 0.9.0

package/skills/lyt-handoff/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: lyt-handoff
+description: >
+  Write an inter-session handoff brief — what a fresh agent or human needs to pick up the work. Trigger when the user runs /lyt-handoff, or says "write a handoff", "brief the next session", "hand this off", "what does the next agent need". Wraps `lyt pattern run work-management handoff`. Writes to <vault>/Handoffs/<project>/<date>-<slug>.md.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-handoff
+
+Write a handoff brief — a self-contained document a fresh agent (or person) can pick up cold to continue work. Distinct from `/lyt-result` (which is about THIS session); a handoff is forward-looking for the NEXT session.
+
+## When to invoke
+
+- `/lyt-handoff` slash trigger
+- "write a handoff brief for the next agent"
+- "I need to leave a brief"
+- end of a multi-session arc when a fresh session needs to pick up
+
+## Phase 1 — Resolve target
+
+Same chain as `/lyt-plan`. Slug describes the work being handed off (e.g., `phase-7-session-3-npm-precheck-readmes`).
+
+## Phase 2 — Run the verb
+
+```
+lyt pattern run work-management handoff --vault <vault> --project <project> --slug <slug>
+```
+
+The verb writes to `<vault>/Handoffs/<project>/<date>-<slug>.md` (not under `work/` — handoffs live at vault root in their own folder per Work-Management convention).
+
+## Phase 3 — Fill the body
+
+A good handoff has:
+
+- **Acceptance sentence** — one paragraph that captures what "done" looks like
+- **State snapshot (@CONTINUATION)** — current branch, last commit, modified files, in-flight artifacts, pushed/unpushed state, test count
+- **Sources (@SOURCES.required + .optional)** — every file the next agent MUST read before drafting any plan
+- **Resume command** — numbered steps the next agent should follow
+- **Sign-off** — canonical retro path; structured @SESSION_REPORT format if applicable
+- **Activation phrase** — the `/handoff-execute "..."` command to paste into the fresh session
+
+The frontmatter `acceptance` field is load-bearing: the executing agent (via `/handoff-execute`) walks its clauses to verify the work matches the brief.
+
+## Companion skills
+
+- `/handoff-execute` (in the handoff-execute skill) — consumes briefs written by this skill
+- `/lyt-result` — what the prior session shipped (context for the handoff)
+- `/lyt-retro` — usually written alongside or after the next-session retro

package/skills/lyt-insight/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lyt-insight
+description: >
+  Capture a distilled project-specific learning as a Lyt Figment. Trigger when the user runs /lyt-insight, or says "this is a project insight", "promote this lesson", "make this durable", "extract the lesson". Wraps `lyt pattern run work-management insight`. Writes to <vault>/Projects/<project>/work/<date>-insight-<slug>.md. For project-agnostic lessons use Nuggets instead.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-insight
+
+Distilled learning specific to THIS project. Promotion target from a `result-` or `retro-` when the lesson earns durable value.
+
+## When to invoke
+
+- `/lyt-insight` slash trigger
+- "this is a project insight"
+- "promote this"
+- "we keep learning this — write it down"
+
+If the lesson is project-AGNOSTIC (applies to any future project), use `/lyt-capture` with a `Nuggets/<subject>/` target instead.
+
+## Phase 1 — Resolve target
+
+Same chain as `/lyt-plan`. If promoting from a result, prefer renaming the existing result file in place: `<date>-result-<slug>.md` → `<date>-insight-<slug>.md`, update `type:` in frontmatter, set `derived_from_session:`. No folder move; no wikilink rot.
+
+If writing a fresh insight that doesn't promote from a specific result, run the verb to create a new file.
+
+## Phase 2 — Run the verb (when creating fresh)
+
+```
+lyt pattern run work-management insight --vault <vault> --project <project> --slug <slug>
+```
+
+## Phase 3 — Fill the body
+
+Sections to fill:
+
+- **The insight** — state the lesson sharply, one paragraph
+- **Why it matters** — where this changes future decisions
+- **Evidence** — sessions, commits, decisions that support it
+- **Edge cases / qualifiers** — when this does NOT apply
+- **Related** — wikilinks to source results, decisions, plans
+
+## Promotion to Nuggets
+
+If after writing the insight you realize the lesson is project-agnostic, ALSO write a `Nuggets/<subject>/<date>-nugget-<slug>.md` at vault root. (Or: rename in place to the Nuggets folder if it's exclusively agnostic.) Two files are fine when the lesson is project-specific in flavor but applies elsewhere too.
+
+## Companion skills
+
+- `/lyt-result` — source of most insight promotions
+- `/lyt-retro` — source of retro-derived insights
+- `/lyt-decision` — for choices that warrant a separate decision artifact

package/skills/lyt-mesh-explore/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: lyt-mesh-explore
+description: >
+  Drill into a single Lyt mesh — surface mesh metadata, member home vaults, update cadences, and the published @MESH_PUBLIC description for one named mesh. Trigger when the user runs /lyt-mesh-explore <mesh>, or says "show me the X mesh", "what's in mesh X", "drill into X mesh", "explore the X mesh", "give me X mesh details", or similar phrasing on mesh-scoped browsing. Wraps `lyt mesh info <mesh> [--remote] [--json]` (v1.B.6) — local mode reads the mesh's `.lyt/mesh.yon` SoT; `--remote` peeks at the published mesh.yon via gh api without cloning. Read-only; pairs with /lyt-pod (pod-level enumeration across all meshes) for breadth and /lyt-search (tiered query) for content.
+visibility: public
+lyt-version: 0.8.0
+capabilities: [read]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-mesh-explore
+
+Render a handler-facing overview of a single Lyt **mesh** — its metadata, its home vaults, its update cadences, and its published `@MESH_PUBLIC` description — by wrapping one primary CLI verb (plus an upstream `lyt mesh list --json` for mesh-name resolution per Phase 1):
+
+- `lyt mesh info <mesh> [--remote] [--json]` (shipped v1.B.6). Canonical mesh-info verb per `packages/lyt-vault/src/commands/mesh-info.ts:20` (definition; registered at `commands/mesh.ts:37`). Local mode reads the registered mesh's main-vault `.lyt/mesh.yon` SoT; `--remote` peeks at the published mesh.yon via `gh api repos/<owner>/<mesh-main>/contents/.lyt/mesh.yon` without cloning the repo.
+
+The skill is pure prose around existing CLI verbs — no new CLI verb, no new helper, no lyt-vault change. The CLI does the parsing (mesh.yon → typed `MeshInfoResult`); the skill resolves the user's intent (mesh name + local-or-remote), invokes the verb with `--json`, and formats the deterministic emission into a handler-facing mesh summary.
+
+User-facing language uses **"mesh"** throughout per the LYT vocabulary convention (D1) — "pod" is reserved for the user's _full_ set of meshes (which is `/lyt-pod`'s scope); "mesh" is the individual group of vaults sharing a GitHub push target.
+
+## When to invoke
+
+When the user runs `/lyt-mesh-explore <mesh>`, or says something like:
+
+- "show me the `<name>` mesh"
+- "what's in mesh `<name>`"
+- "drill into `<name>` mesh"
+- "explore the `<name>` mesh"
+- "give me `<name>` mesh details"
+- "what vaults are in `<name>`"
+- "peek at the remote `<name>` mesh without cloning" — _use `--remote`_
+
+If the user wants a survey across _all_ their meshes (the pod-level view), prefer `/lyt-pod`. If the user wants to search content _inside_ the mesh's vaults, prefer `/lyt-search --mesh <name>`. This skill is the mesh-scoped drill-down between those two surfaces.
+
+## Phase 1 — Resolve mesh name from user signal
+
+The CLI verb takes one required positional `<mesh>` (the mesh name). Pick by the user's wording:
+
+- **Explicit mesh name from invocation.** When the user runs `/lyt-mesh-explore <name>` or names the mesh directly ("explore the `younndai` mesh"), use that name as the candidate.
+- **Keyword in natural language.** When the user says "show me the X mesh" / "what's in mesh X" / "drill into X", extract X as the candidate.
+
+**Resolve the candidate against `lyt mesh list --json` before passing it.** Don't guess — when the user names a mesh:
+
+1. Run `lyt mesh list --json` first (canonical mesh-enumeration verb per `packages/lyt-vault/src/commands/mesh.ts:277` — `buildMeshListSubcommand` definition; registered at `commands/mesh.ts:32`). The output's `meshes[].name` field is the source of truth for registered mesh names.
+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 the positional `<mesh>` argument — closes the flag-injection surface the same way lyt-sync, lyt-search, and lyt-pod close theirs (family: G.2 CR-1 gh-flag-injection). Mesh names are user-controlled at `lyt mesh init` time; a mesh 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 mesh names from `lyt mesh list --json` and stop — do not invent a name.
+
+**Decide `--remote` from explicit user signal only.** Pass `--remote` ONLY when the user explicitly says "without cloning" / "from GitHub" / "peek at the published mesh.yon" / "remote mesh info". The default is LOCAL invocation (no `--remote`) — it reads the locally-registered mesh's `.lyt/mesh.yon` SoT, which is faster, offline-safe, and authoritative for meshes the user owns. `--remote` requires the mesh to be registered locally with a `push_target` (the verb resolves the remote owner from the registry; it does NOT take a `--owner` override in v1.B.6).
+
+## Phase 2 — Invoke `lyt mesh info`
+
+Run the verb via the Bash tool (or your runtime's shell equivalent). **Pass argv as an array; never shell-compose the command.** Precedent: lyt-sync's Phase 3 (`spawnSync("git", [..., "-m", message])`), lyt-search's Phase 2 (`spawnSync("lyt", ["search", userQuery, "--json"])`), lyt-pod's Phases 2 + 3 (`spawnSync("lyt", ["mesh", "list", "--json"])` + `spawnSync("lyt", ["vault", "list", "--json"])`) — same argv-array shape, cross-platform-safe.
+
+```
+# Shell-syntax (DOCUMENTATION ONLY — do NOT compose this as a string):
+lyt mesh info <mesh> [--remote] --json
+
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("lyt", ["mesh", "info", meshName, "--json"]);
+
+# With --remote (only on explicit user signal):
+spawnSync("lyt", ["mesh", "info", meshName, "--remote", "--json"]);
+```
+
+Key rules:
+
+- The first positional argument is the mesh name — a single string already resolved + sanitized in Phase 1. Quote it in shell-equivalent docs; in argv form it is one element.
+- `--json` is **mandatory** for this skill. The deterministic JSON emission is the contract the skill parses below; human-readable output is not.
+- `--remote` is a boolean flag; pass it (or omit) per the Phase 1 decision. Never pass `--remote=true` or `--remote=<anything>` — the flag is bare.
+
+The CLI emits Lock 0.3 stable-key-ordered JSON on stdout (exit 0 on success). The actual emitted shape (per `packages/lyt-vault/src/flows/mesh-info.ts:103-118`, the `MeshInfoResult` interface — `mesh-info.ts:40` does `JSON.stringify(result, null, 2)` verbatim with no transformation, so the TypeScript shape IS the JSON contract):
+
+```json
+{
+  "source": "local" | "remote",
+  "mesh": {
+    "rid": "mesh:<uuid-dashed>",
+    "ridHex": "<hex>",
+    "name": "<mesh-name>",
+    "pushTarget": "<gh-target>" | null,
+    "pushKind": "handle" | "org" | null,
+    "mainVaultRid": "vault:<uuid-dashed>",
+    "createdAt": "<iso>",
+    "defaultVaultUpdateCadence": "<cadence-string>" | null
+  },
+  "publicMeta": {
+    "description": "<string>",
+    "topics": "<comma-separated>",
+    "maintainerContact": "<string>",
+    "maintainerHandle": "<string>",
+    "licenseOverride": "<spdx-id>",
+    "acceptContributions": true,
+    "contributionUrl": "<url>",
+    "homepageUrl": "<url>",
+    "chatUrl": "<url>",
+    "createdAt": "<iso>"
+  } | null,
+  "updateCadences": [
+    {
+      "vaultRid": "vault:<uuid-dashed>",
+      "vaultRidHex": "<hex>",
+      "cadenceType": "cron" | "interval" | "on-demand",
+      "cron": "<expr>",
+      "intervalSeconds": <number>,
+      "timezone": "<tz>",
+      "peakHours": "<expr>",
+      "onDemandAllowed": <boolean>
+    }
+  ],
+  "homeVaults": [
+    {
+      "vaultRid": "vault:<uuid-dashed>",
+      "vaultRidHex": "<hex>",
+      "vaultName": "<name>"
+    }
+  ]
+}
+```
+
+Within `publicMeta` and `updateCadences[]`, every field except `description` (in publicMeta) and `vaultRid` / `vaultRidHex` / `cadenceType` (in updateCadences[]) is omitted from the emission when undefined — they are conditional object-literal spreads at flow-emission time. Treat missing keys as "field not set on this mesh", not "field is null".
+
+Failure modes (CLI emits to stderr; exits non-zero):
+
+- **Mesh not registered locally** (`MeshInfoNotFoundError`, exit 2) → `{ "error": "mesh-info-not-found", "mesh_name": "<name>", "message": "..." }`. Surface the message verbatim and suggest `lyt mesh list --json` to see registered meshes.
+- **--remote requested, gh unavailable** (`MeshInfoRemoteGhUnavailableError`, exit 4) → `{ "error": "remote-gh-unavailable", "mesh_name": "<name>", "message": "..." }`. Most common causes: the mesh has no `push_target` (initialized with `--no-push`), or `gh` is not authenticated. Surface the message and suggest dropping `--remote` to fall back to LOCAL mode.
+- **--remote requested, remote mesh.yon missing** (`MeshInfoRemoteMeshYonMissingError`, exit 4) → `{ "error": "remote-mesh-yon-missing", "mesh_name": "<name>", "message": "..." }`. The remote repo exists but `.lyt/mesh.yon` is absent at the repo root — the mesh has not yet been published via `lyt mesh publish`. Surface verbatim and suggest LOCAL mode.
+
+## Phase 3 — Format mesh-overview for handler
+
+Render the mesh summary as a markdown block. The handler-facing layout:
+
+```
+# Mesh: `<mesh-name>` (<local | remote>)
+
+**Metadata:**
+- rid: `<mesh.rid>`
+- push target: `<mesh.pushKind>:<mesh.pushTarget>`     (omit line when pushTarget is null)
+- main vault rid: `<mesh.mainVaultRid>`
+- created: `<mesh.createdAt>`
+- default cadence: `<mesh.defaultVaultUpdateCadence>`  (omit line when null)
+
+**Public description:** (omit entire block when publicMeta is null)
+- description: <publicMeta.description>
+- topics: <publicMeta.topics>                          (omit when undefined)
+- maintainer: <publicMeta.maintainerContact>           (omit when undefined)
+- license: <publicMeta.licenseOverride>                (omit when undefined)
+- homepage: <publicMeta.homepageUrl>                   (omit when undefined)
+- chat: <publicMeta.chatUrl>                           (omit when undefined)
+
+**Home vaults:** (count = homeVaults.length)
+- ★ `<main-vault-name>` (`vault:<vaultRidHex>`)        — main vault, marked ★
+- `<vault-name>` (`vault:<vaultRidHex>`)
+- ...
+
+**Update cadences:** (count = updateCadences.length; omit entire block when length is 0)
+- `<vault-ridHex truncated to 12 chars>…` — <cadenceType> <detail>
+- ...
+```
+
+Synthesis rules:
+
+- **Source line.** Render `(local)` or `(remote)` next to the mesh name based on `source` — handlers seeing the rendered output should know whether they're looking at on-disk SoT or a remote peek.
+- **Main-vault marker.** The home vault whose `vaultRid` equals `mesh.mainVaultRid` is the main vault — render it first with a `★` marker (parity with `lyt mesh list`'s human output per `packages/lyt-vault/src/commands/mesh.ts:333`). Other home vaults follow, sorted alphabetically by `vaultName`. Do not double-render the main vault.
+- **Cadence detail.** For `cadenceType: "cron"`, render the `cron` expression. For `"interval"`, render `every <intervalSeconds>s`. For `"on-demand"`, render `on-demand`. Truncate `vaultRidHex` to the first 12 chars with `…` for readability (parity with `mesh-info.ts:104`).
+- **Optional-field omission.** Treat absent keys in `publicMeta` + `updateCadences[]` as "field not set on this mesh"; omit those lines entirely rather than rendering `undefined` or `null` placeholders.
+- **No edges / subscriptions sections.** `lyt mesh info` surfaces mesh metadata + publicMeta + home vaults + update cadences ONLY — it does not emit mesh-edges (`@MESH_EDGE`) or cross-mesh subscriptions (`@MESH_SUBSCRIPTION`). Those are inspected via other surfaces (`lyt mesh list` exposes per-mesh `subscribed_vaults`; mesh-edges live in `.lyt/mesh.yon` but are not surfaced by this verb). Do NOT invent edge / subscription bullets — the verb does not expose them. Mention `/lyt-pod` as the path to subscription overview if the user asks.
+- **Empty publicMeta.** When `publicMeta === null`, the mesh was initialized without a `@MESH_PUBLIC` block. Omit the entire "Public description" section — do NOT render an empty heading.
+- **Use "mesh" framing throughout.** Never write "federation" or "pod" in this skill's user-facing prose. "Mesh" is the unit of grouping; "pod" is the user's full set of meshes (different scope; that's `/lyt-pod`'s domain).
+- **Remote-mode caveat.** When `source === "remote"`, the data is whatever the remote `.lyt/mesh.yon` currently advertises — it may be stale relative to the mesh's owner's local state if they haven't run `lyt mesh publish` recently. Mention this when the user explicitly asked for `--remote`, so they know what they're looking at.
+
+## Rules
+
+- **MUST pass the mesh name as a separate argv argument**, not template-interpolated into a shell command string. Mesh names are user-controlled at init time; argv-array protects against shell-meta or flag-shaped tokens.
+- **MUST pass `--json`** on every invocation. Human-readable output is not a contract this skill parses.
+- **MUST resolve mesh names via `lyt mesh list --json` before passing them.** The canonical mesh-enumeration verb is `lyt mesh list` per `packages/lyt-vault/src/commands/mesh.ts:277` (`buildMeshListSubcommand` definition; registered at `commands/mesh.ts:32`). Do not guess names.
+- **MUST reject `--`-leading resolved mesh names** before passing them to the positional `<mesh>` argument (G.2 CR-1 flag-injection family defense).
+- **MUST NOT cite `lyt mesh status`** as a verb. It does not exist. The canonical mesh-listing verb is `lyt mesh list`; the canonical single-mesh-inspection verb is `lyt mesh info` (this skill).
+- **MUST NOT modify or write any vault file.** This is a read-only skill (`requires_writable_vault: false`). If the user wants the mesh overview persisted to a Figment, run `/lyt-capture` separately on the formatted output.
+- **MUST NOT pass `--remote` by default.** LOCAL is the default; pass `--remote` only on explicit user signal ("without cloning", "from GitHub", "peek at the published mesh.yon", "remote").
+- **MUST NOT invent edge or subscription bullets.** `lyt mesh info` does not emit them. For pod-wide subscription overview use `/lyt-pod`; for cross-mesh edges, inspect `.lyt/mesh.yon` directly (out of scope for this skill).
+- **MUST NOT shell-compose any verb invocation.** Argv-array always (parity with lyt-sync + lyt-search + lyt-primer-context + lyt-pod).
+
+## Companion skills
+
+- **`/lyt-pod`** — pod-level overview across _all_ the user's meshes and vaults on this machine. Use when the user wants breadth (every mesh, every vault, orphans surfaced) rather than depth into one mesh.
+- **`/lyt-search`** — query _content_ across the pod (or a single mesh / vault) via the tiered-cascade engine. Pair after `/lyt-mesh-explore` when the user has picked a mesh and now wants to look for specific content inside it (`lyt search "<q>" --mesh <name> --json`).
+- **`/lyt-primer-context`** — prime an agent with Lyt-scoped context for a single vault (active arcs, writable status, primer files). Pair after `/lyt-mesh-explore` when the user picks a vault from this mesh's home-vaults list to start working in.
+- **`/lyt-sync`** — pull/commit/push a vault. Run before `/lyt-mesh-explore` if the user has unpublished mesh-config edits and wants the `--remote` path to reflect them.

package/skills/lyt-pattern/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: lyt-pattern
+description: >
+  Manage Lyt patterns from the agent harness — list/install/uninstall/link/unlink/fork/verbs/run via the `lyt pattern *` CLI verb set. Trigger when the user runs /lyt-pattern, or says "list my patterns", "install a pattern", "link this pattern into my vault", "fork this pattern", "run a pattern verb directly". Meta-skill: every other /lyt-* skill calls `lyt pattern run` under the hood; this skill exposes the full management surface.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [manage]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-pattern
+
+Manage Lyt patterns: install, link/unlink, fork for customization, list available verbs, and run verbs directly.
+
+## When to invoke
+
+- `/lyt-pattern list` — show installed patterns
+- `/lyt-pattern verbs <name>` — show a pattern's verbs
+- `/lyt-pattern install --from <local-dir>` — install a custom pattern
+- `/lyt-pattern link <name> --vault <v>` — symlink into a vault
+- `/lyt-pattern fork <name> --as <new>` — customize without modifying the master
+- `/lyt-pattern run <pattern> <verb> ...` — direct verb invocation (the other /lyt-\* skills are thin wrappers; this is the escape hatch)
+
+## When NOT to invoke
+
+For the common write-a-Figment-of-type-X flow, use the dedicated skill:
+
+- `/lyt-plan`, `/lyt-progress`, `/lyt-result`, `/lyt-retro`, `/lyt-insight`, `/lyt-handoff` (work-management)
+- `/lyt-capture`, `/lyt-recall` (knowledge-capture)
+- `/lyt-decision` (decision-log)
+
+Use `/lyt-pattern` for pattern management itself OR for verbs that don't yet have a dedicated skill wrapper (e.g., `project-lifecycle/project-init`, `project-lifecycle/checkpoint`, `decision-log/rationale`).
+
+## The verb surface
+
+```bash
+lyt pattern list [--vault <name>] [--json]
+lyt pattern install --from <local-dir> [--as <name>] [--force]
+lyt pattern uninstall <name> [--force]
+lyt pattern link <name> --vault <vault-name>
+lyt pattern unlink <name> --vault <vault-name>
+lyt pattern fork <source> --as <name>
+lyt pattern verbs <name> [--json]
+lyt pattern run <pattern> <verb> --vault <v> [--project <p>] [--slug <s>] [--vars k=v...]
+```
+
+## Symlink + fork mechanics
+
+Patterns live at `~/lyt/patterns/<name>/` (per-machine, per-user, like the registry). `pattern link` creates `<vault>/Patterns/<name>` as a junction symlink to the master. Symlinks are gitignored from vault repos — `lyt vault adopt` and `lyt vault join` auto-rebuild them per-machine.
+
+To customize without touching the master, use `pattern fork`:
+
+```bash
+lyt pattern fork work-management --as wm-custom
+# edit ~/lyt/patterns/wm-custom/
+lyt pattern unlink work-management --vault <v>
+lyt pattern link wm-custom --vault <v>
+```
+
+## Version migration (v1 caveat)
+
+Newer pattern versions replace the master at `~/lyt/patterns/<name>/`. Files already written from the old template are NOT migrated; the new template only affects NEW writes. (A `lyt pattern migrate` verb is post-v1.)
+
+## Verb-name conflicts
+
+If two installed patterns both declare a `plan` verb, address via explicit qualification: `lyt pattern run work-management plan` (not just `lyt pattern run plan`). Skills wrap by pattern convention: `/lyt-plan` ties to work-management; a second pattern with `plan` would generate as `/lyt-<pattern2-id>-plan`.
+
+## Companion skills
+
+All `/lyt-*` skills above are pattern-verb wrappers that this meta-skill manages.

package/skills/lyt-plan/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: lyt-plan
+description: >
+  Write a pre-action plan as a Lyt Figment. Trigger when the user runs /lyt-plan, or says "plan this", "write a plan", "design before coding", "let's plan first". Wraps `lyt pattern run work-management plan` under the hood. Writes to <vault>/Projects/<project>/work/<date>-plan-<slug>.md with frontmatter (date, slug, project, owner).
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-plan
+
+Capture a pre-action plan as a structured Work-Management artifact in a Lyt vault. Plans answer: what are you about to do, why, how, and what does success look like.
+
+## When to invoke
+
+When the user runs `/lyt-plan`, or says something like:
+
+- "let's plan this out"
+- "design before coding"
+- "what's the plan"
+- "write a plan for X"
+
+## Phase 1 — Resolve vault + project + slug
+
+1. **Vault resolution:** `--vault <name>` arg → `$LYT_ACTIVE_VAULT` env → cwd-based detection via `lyt vault info --by-path <cwd>` → default `<handle>/main`.
+2. **Project:** `--project <name>` arg → infer from current directory name → ask the user.
+3. **Slug:** ask the user, or generate from the plan's title (lowercase kebab-case, ≤7 words).
+
+## Phase 2 — Run the verb
+
+Invoke the CLI:
+
+```
+lyt pattern run work-management plan --vault <vault> --project <project> --slug <slug>
+```
+
+The CLI fills frontmatter (`date`, `slug`, `project`, `owner`) and writes to the resolved path: `<vault>/Projects/<project>/work/<date>-plan-<slug>.md`.
+
+If the file already exists, the CLI returns `ALREADY-EXISTS` and the path; do not overwrite. Append a `-2` slug or pick a different slug.
+
+## Phase 3 — Fill in the body
+
+After the file is created, edit it to fill in:
+
+- **Goal** — one-paragraph statement of intent
+- **Background** — context, references, prior decisions
+- **Approach** — steps, sequence, who/what does each
+- **Risks + open questions**
+- **Success criteria**
+- **Estimate**
+
+Use Obsidian-flavored markdown. Use `[[wikilinks]]` to cross-reference prior plans, results, or thoughts.
+
+## Companion skills
+
+- `/lyt-progress` — mid-session status update on this plan
+- `/lyt-result` — post-action outcome closing this plan
+- `/lyt-retro` — deliberate retrospective after the plan executes