Plans

# Lore Skill Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a `ushell`-style Claude Code skill, packaged as a shareable plugin, that teaches people to use and learn Lore (Epic's content-addressed VCS) and accurately drives its CLI and all four language SDKs.

**Architecture:** A lean `SKILL.md` router plus a `reference/` tree (concepts, setup, cli, troubleshooting, and a per-language `sdk/` folder). Every command/API claim is grounded in real sources captured in Phase 1 — live `lore --help` from a Docker container, generated SDK types introspected after a container build, the cloned SDK repos, and `epicgames.github.io/lore`. The "don't invent" discipline the skill preaches is applied to the author.

**Tech Stack:** Markdown skill + Claude Code plugin manifests (`plugin.json`, `marketplace.json`); Docker (Linux container) for grounding; `git`, `gh`, `pip`/`uv`, `cargo` (only if a prebuilt CLI binary is unavailable).

**Spec:** `docs/superpowers/specs/2026-06-18-lore-skill-design.md`

---

## File Structure

| Path | Responsibility |
|---|---|
| `.claude-plugin/plugin.json` | Plugin manifest (name, version, description, author) |
| `.claude-plugin/marketplace.json` | Marketplace entry so others can install |
| `README.md` | What the plugin is + install instructions |
| `skills/lore/SKILL.md` | The router: triggers, iron rules, detection gate, invocation, quick-reference tables, progressive-disclosure pointers, anti-patterns |
| `skills/lore/reference/concepts.md` | "Learn Lore": architecture, content-addressing/Merkle, offline/online, hydration/sparse, glossary |
| `skills/lore/reference/setup.md` | CLI install, repo init/clone, local-vs-server, auth, source build |
| `skills/lore/reference/cli.md` | Full CLI command/flag reference (the core surface) |
| `skills/lore/reference/troubleshooting.md` | CLI + SDK failure diagnosis |
| `skills/lore/reference/sdk/model.md` | Universal globals/args/callback/event/lifecycle model |
| `skills/lore/reference/sdk/python.md` | Python SDK (`lore-vcs`) install + worked example |
| `skills/lore/reference/sdk/javascript.md` | JS SDK (`lore-js`) install + worked example |
| `skills/lore/reference/sdk/dotnet.md` | C# SDK (`lore-dotnet`) install + worked example |
| `skills/lore/reference/sdk/go.md` | Go SDK (`lore-go`) install + worked example |
| `_grounding/` | Captured raw source-of-truth (CLI help dumps, type dumps, scrape notes, version manifest). Gitignored. Not shipped. |
| `_reference-lore-*/` | Cloned upstream SDK repos. Gitignored. Not shipped. |

**Grounding-before-writing rule:** No content task (Phases 2–7) may be started until Phase 1 has produced the `_grounding/` file that task depends on. Every command, flag, and API name written into a reference file MUST be traceable to a line in `_grounding/`. If it isn't there, mark it `<!-- UNVERIFIED -->` in the prose rather than inventing it.

---

## Phase 0: Plugin scaffold

### Task 0.1: Confirm plugin manifest schema

**Files:** none (research task)

- [ ] **Step 1: Look up the current plugin + marketplace manifest schema**

Dispatch the `claude-code-guide` agent (or read current docs) with: "What are the exact required and optional fields for a Claude Code plugin `plugin.json` and a `marketplace.json`? Where must each file live, and how does a skill folder get discovered inside a plugin?"

Expected: a confirmed field list for both files and the directory layout (skills auto-discovered under `skills/<name>/SKILL.md`).

- [ ] **Step 2: Record the answer**

Write the confirmed schema to `_grounding/plugin-schema.md` so later tasks quote it verbatim.

Run: `Test-Path _grounding/plugin-schema.md`
Expected: `True`

- [ ] **Step 3: Commit**

```powershell
git add _grounding/plugin-schema.md 2>$null; git commit -q -m "docs: capture plugin manifest schema"
```
(Note: `_grounding/` is gitignored by default — force-add this one provenance file, or keep the schema note in `docs/` instead. Decide in Step 2; if keeping gitignored, skip this commit.)

### Task 0.2: Scaffold plugin files

**Files:**
- Create: `.claude-plugin/plugin.json`
- Create: `.claude-plugin/marketplace.json`
- Create: `skills/lore/reference/sdk/` (directory)
- Modify: `.gitignore` (add `_grounding/`)

- [ ] **Step 1: Add `_grounding/` to `.gitignore`**

Append to `.gitignore`:
```
_grounding/
```

- [ ] **Step 2: Write `plugin.json`** using the schema from Task 0.1. Minimal example (adjust field names to the confirmed schema):

```json
{
  "name": "lore",
  "version": "0.1.0",
  "description": "Use and learn Lore (Epic's content-addressed VCS): CLI, setup, concepts, and all language SDKs.",
  "author": { "name": "Aaron" }
}
```

- [ ] **Step 3: Write `marketplace.json`** per the confirmed schema, listing this single plugin.

- [ ] **Step 4: Create the directory tree**

```powershell
New-Item -ItemType Directory -Force skills/lore/reference/sdk | Out-Null
```

- [ ] **Step 5: Verify JSON parses**

Run: `Get-Content .claude-plugin/plugin.json -Raw | ConvertFrom-Json; Get-Content .claude-plugin/marketplace.json -Raw | ConvertFrom-Json`
Expected: no parse error.

- [ ] **Step 6: Commit**

```powershell
git add .claude-plugin .gitignore; git commit -q -m "feat: scaffold lore plugin manifests"
```

---

## Phase 1: Grounding capture

> All output lands in `_grounding/`. This phase produces source-of-truth; it writes no skill content.

### Task 1.1: Clone the remaining SDK repos

**Files:** Create `_reference-lore-js/`, `_reference-lore-dotnet/`, `_reference-lore-go/`

- [ ] **Step 1: Clone all three (shallow)**

```powershell
git clone --depth 1 https://github.com/EpicGames/lore-js.git _reference-lore-js
git clone --depth 1 https://github.com/EpicGames/lore-dotnet.git _reference-lore-dotnet
git clone --depth 1 https://github.com/EpicGames/lore-go.git _reference-lore-go
```

- [ ] **Step 2: Record each repo's pinned commit for the version stamp**

```powershell
foreach ($r in 'python','js','dotnet','go') { "$r=$(git -C _reference-lore-$r rev-parse HEAD)" } | Set-Content _grounding/sdk-commits.txt
Get-Content _grounding/sdk-commits.txt
```
Expected: four `name=<sha>` lines.

- [ ] **Step 3: Survey each repo's examples + README**

For each repo, read its `README` and any `examples/` directory; note the install command, the import/entry symbol, and the worked-example operation sequence into `_grounding/sdk-<lang>.md`.

Run: `Get-ChildItem _grounding/sdk-*.md | Select-Object Name`
Expected: `sdk-python.md`, `sdk-js.md`, `sdk-dotnet.md`, `sdk-go.md`.

### Task 1.2: Determine the Lore CLI install path for Linux

**Files:** Create `_grounding/cli-install.md`

- [ ] **Step 1: Inspect the Lore releases for a prebuilt Linux CLI binary**

```powershell
gh release view --repo EpicGames/lore --json tagName,assets --jq '{tag:.tagName, assets:[.assets[].name]}'
```
Expected: latest tag + asset filenames. Identify any Linux x86_64 CLI asset.

- [ ] **Step 2: Record the chosen install method**

Write to `_grounding/cli-install.md` ONE of:
- **Path A (preferred):** the exact download URL + extract steps for the Linux release binary.
- **Path B (fallback):** `cargo build --release` from `https://github.com/EpicGames/lore` (note build time + that the container needs the Rust toolchain).

Expected: `_grounding/cli-install.md` states which path was chosen and why.

### Task 1.3: Capture live CLI help from a Docker container

**Files:** Create `_grounding/cli-help/` (one file per command)

- [ ] **Step 1: Stand up the container and install the CLI** using the method from Task 1.2.

Path A example:
```powershell
docker run -d --name lore-grounding -w /work ubuntu:24.04 sleep infinity
docker exec lore-grounding bash -lc "apt-get update && apt-get install -y curl ca-certificates"
docker exec lore-grounding bash -lc "<download+extract the Linux lore binary into /usr/local/bin>"
docker exec lore-grounding bash -lc "lore --version"
```
Expected: `lore --version` prints a version. Record it:
```powershell
docker exec lore-grounding bash -lc "lore --version" | Set-Content _grounding/lore-version.txt
```

- [ ] **Step 2: Capture top-level help**

```powershell
docker exec lore-grounding bash -lc "lore --help" | Set-Content _grounding/cli-help/_root.txt
```
Expected: a help listing of subcommands.

- [ ] **Step 3: Capture help for every subcommand**

Parse the subcommand names out of `_root.txt`, then for each run `lore <sub> --help` (and one level of nested subcommands where they exist), saving to `_grounding/cli-help/<sub>.txt`.

Run: `Get-ChildItem _grounding/cli-help | Measure-Object | % Count`
Expected: more than 1 file (root + every subcommand).

- [ ] **Step 4: Exercise the documented quickstart inside the container** (init → create file → stage → commit) to confirm the real verb names and output, and capture a transcript to `_grounding/cli-quickstart.txt`.

Expected: a successful local commit; transcript saved.

### Task 1.4: Introspect generated SDK types (Python) in the container

**Files:** Create `_grounding/python-types.txt`

- [ ] **Step 1: Build `lore-python` against the container's Lore lib** following its README (`uv venv`, set `LORE_BUILD_PATH`, `find_lorelib.py`, `generator/generate.py`, `uv pip install -e .`).

- [ ] **Step 2: Dump the generated types/args surface**

```powershell
docker exec lore-grounding bash -lc "cd /work/lore-python && python -c 'import lore.types.args as a, lore.types.enums as e; import inspect; print(\"ARGS:\"); [print(n) for n in dir(a) if not n.startswith(chr(95))]; print(\"ENUMS:\"); [print(n) for n in dir(e) if not n.startswith(chr(95))]'" | Set-Content _grounding/python-types.txt
```
Expected: lists of `Lore*Args` classes and `Lore*` enums.

- [ ] **Step 3: For each operation used in the worked example, dump its Args fields** into `_grounding/python-types.txt` so `sdk/python.md` and `sdk/model.md` cite real field names (not guesses).

### Task 1.5: Scrape the official docs

**Files:** Create `_grounding/docs-*.md`

- [ ] **Step 1: Fetch and summarize concept/architecture pages** from `epicgames.github.io/lore` (explanation + system-design) → `_grounding/docs-concepts.md`.

- [ ] **Step 2: Fetch how-to install + deploy-local-server + auth pages** → `_grounding/docs-setup.md`.

- [ ] **Step 3: Fetch the CLI reference page(s)** → `_grounding/docs-cli.md`. Cross-check against `_grounding/cli-help/`; note any discrepancy (live capture wins).

Run: `Get-ChildItem _grounding/docs-*.md | Select-Object Name`
Expected: `docs-concepts.md`, `docs-setup.md`, `docs-cli.md`.

- [ ] **Step 4: Assemble the version manifest** combining `lore-version.txt` + `sdk-commits.txt` into `_grounding/version-stamp.md` (used verbatim in `SKILL.md`).

---

## Phase 2: SKILL.md (router)

### Task 2.1: Write `skills/lore/SKILL.md`

**Files:** Create `skills/lore/SKILL.md`

- [ ] **Step 1: Write the frontmatter + intro + Iron rules + Detection gate** following the spec §5 anatomy. Frontmatter `name: lore`; description lists the trigger conditions from spec §5.

- [ ] **Step 2: Write the Invocation & return-codes section** — CLI invocation notes + the SDK `op(globals, args).callback(handler).wait()` lifecycle (`log_configure` / `global_callback` / `shutdown`). Source the lifecycle from `_grounding/sdk-python.md` + `_grounding/python-types.txt`.

- [ ] **Step 3: Write the two Quick-reference tables.** CLI verbs come ONLY from `_grounding/cli-help/`; SDK operations ONLY from `_grounding/python-types.txt`. Do not assume CLI verb names equal SDK op names.

- [ ] **Step 4: Write concept-clarifications, "Load reference when…" pointers, Anti-patterns, and the version stamp** (paste `_grounding/version-stamp.md`).

- [ ] **Step 5: Verify frontmatter parses and required keys exist**

Run:
```powershell
$t = Get-Content skills/lore/SKILL.md -Raw
if ($t -match '(?s)^---(.*?)---') { $matches[1] } else { 'NO FRONTMATTER' }
```
Expected: frontmatter block containing `name:` and `description:`.

- [ ] **Step 6: Verify every CLI verb in the Quick reference exists in a grounding capture**

Run:
```powershell
# Extract `lore <verb>` mentions from SKILL.md and confirm each appears in cli-help captures
Select-String -Path skills/lore/SKILL.md -Pattern 'lore [a-z][a-z-]+' -AllMatches |
  ForEach-Object { $_.Matches.Value } | Sort-Object -Unique |
  ForEach-Object { $v = ($_ -split ' ')[1]; $hit = Select-String -Path _grounding/cli-help/* -Pattern "\b$v\b" -Quiet; "$_ => grounded=$hit" }
```
Expected: every line ends `grounded=True`. Any `False` → fix the table or mark `<!-- UNVERIFIED -->`.

- [ ] **Step 7: Commit**

```powershell
git add skills/lore/SKILL.md; git commit -q -m "feat: add lore SKILL.md router"
```

---

## Phase 3-6: Single-file reference pages

Each task: write the page grounded in its `_grounding/` source, verify links/claims, commit. Same rhythm — shown in full per task (no "similar to" cross-refs).

### Task 3.1: `reference/concepts.md`

**Files:** Create `skills/lore/reference/concepts.md`

- [ ] **Step 1: Write the page** — mental model, content-addressing/Merkle, immutable revision chain, offline-vs-online, on-demand hydration & sparse workspaces, a short note that all SDKs bind one C ABI, and a glossary. Source: `_grounding/docs-concepts.md`.

- [ ] **Step 2: Verify no unverified invented terms** — every Lore-specific term should trace to `_grounding/docs-concepts.md`.

Run: `Test-Path skills/lore/reference/concepts.md`
Expected: `True`.

- [ ] **Step 3: Commit**

```powershell
git add skills/lore/reference/concepts.md; git commit -q -m "docs: add lore concepts reference"
```

### Task 4.1: `reference/setup.md`

**Files:** Create `skills/lore/reference/setup.md`

- [ ] **Step 1: Write the page** — CLI install (Linux/Windows/macOS per `_grounding/cli-install.md` + `_grounding/docs-setup.md`), `lore init`/clone (verbs from `_grounding/cli-help/`), local-vs-online/server mode, `lore auth`, and the from-source build (`LORE_BUILD_PATH`, binding generation) from `lore-python/README`.

- [ ] **Step 2: Verify every command appears in grounding**

Run:
```powershell
Select-String -Path skills/lore/reference/setup.md -Pattern '`lore [a-z]' -AllMatches | Measure-Object | % Count
```
Expected: > 0, and each verb cross-checks against `_grounding/cli-help/` (spot-check failures → mark unverified).

- [ ] **Step 3: Commit**

```powershell
git add skills/lore/reference/setup.md; git commit -q -m "docs: add lore setup reference"
```

### Task 5.1: `reference/cli.md`

**Files:** Create `skills/lore/reference/cli.md`

- [ ] **Step 1: Write the full CLI reference** — one section per subcommand, each with its synopsis + flags taken VERBATIM from the matching `_grounding/cli-help/<sub>.txt`. Group by workflow (status/stage/commit, branch/switch, push/sync, hydrate/sparse).

- [ ] **Step 2: Verify coverage — every captured subcommand has a section**

Run:
```powershell
Get-ChildItem _grounding/cli-help -Filter *.txt | Where-Object { $_.BaseName -ne '_root' } |
  ForEach-Object { $cmd = $_.BaseName; $hit = Select-String -Path skills/lore/reference/cli.md -Pattern "\b$cmd\b" -Quiet; "$cmd => documented=$hit" }
```
Expected: every line ends `documented=True`.

- [ ] **Step 3: Commit**

```powershell
git add skills/lore/reference/cli.md; git commit -q -m "docs: add lore CLI reference"
```

### Task 6.1: `reference/troubleshooting.md`

**Files:** Create `skills/lore/reference/troubleshooting.md`

- [ ] **Step 1: Write the page** — symptom → cause → fix entries for the failures observed in Phase 1 (CLI non-zero exits, `LORE_BUILD_PATH` unset, missing `shutdown`, offline/online mismatch, auth not run). Each entry cites the real error string where captured in `_grounding/`.

- [ ] **Step 2: Verify** `Test-Path skills/lore/reference/troubleshooting.md` → `True`.

- [ ] **Step 3: Commit**

```powershell
git add skills/lore/reference/troubleshooting.md; git commit -q -m "docs: add lore troubleshooting reference"
```

---

## Phase 7: SDK reference pages

### Task 7.1: `reference/sdk/model.md`

**Files:** Create `skills/lore/reference/sdk/model.md`

- [ ] **Step 1: Write the universal model** — globals-args vs op-args, the `op(globals, args).callback(handler).wait()` pattern, the event/callback system (`LoreEventTag`, event `get_data()`), logging config, and `shutdown`. Use real class/field names from `_grounding/python-types.txt`; present the pattern language-agnostically.

- [ ] **Step 2: Verify class names are real**

Run:
```powershell
Select-String -Path skills/lore/reference/sdk/model.md -Pattern 'Lore[A-Za-z]+' -AllMatches |
  ForEach-Object { $_.Matches.Value } | Sort-Object -Unique |
  ForEach-Object { "$_ => $(Select-String -Path _grounding/python-types.txt -Pattern "\b$_\b" -Quiet)" }
```
Expected: each referenced `Lore*` symbol resolves `True` (or is a deliberately language-neutral term).

- [ ] **Step 3: Commit** `git add skills/lore/reference/sdk/model.md; git commit -q -m "docs: add lore SDK model reference"`

### Task 7.2: `reference/sdk/python.md`

**Files:** Create `skills/lore/reference/sdk/python.md`

- [ ] **Step 1: Write** install (`pip install lore-vcs`), the offline commit-a-file worked example (adapted from `lore-python/examples/example.py`), the online push/clone variant, and a `lore.native` pointer. Code must match `_grounding/sdk-python.md` + `_grounding/python-types.txt`.

- [ ] **Step 2: Verify the worked-example code uses only grounded symbols** (same grep pattern as Task 7.1 Step 2 against `_grounding/python-types.txt`).

- [ ] **Step 3: Commit** `git add skills/lore/reference/sdk/python.md; git commit -q -m "docs: add lore Python SDK reference"`

### Task 7.3: `reference/sdk/javascript.md`

**Files:** Create `skills/lore/reference/sdk/javascript.md`

- [ ] **Step 1: Write** install + worked example for `lore-js`, sourced ONLY from `_grounding/sdk-js.md`. If the repo's example is thin, write what is grounded and mark the rest `<!-- UNVERIFIED: not in lore-js examples -->`.

- [ ] **Step 2: Verify** `Test-Path skills/lore/reference/sdk/javascript.md` → `True`.

- [ ] **Step 3: Commit** `git add skills/lore/reference/sdk/javascript.md; git commit -q -m "docs: add lore JS SDK reference"`

### Task 7.4: `reference/sdk/dotnet.md`

**Files:** Create `skills/lore/reference/sdk/dotnet.md`

- [ ] **Step 1: Write** install + worked example for `lore-dotnet`, sourced ONLY from `_grounding/sdk-dotnet.md`; mark gaps `<!-- UNVERIFIED -->`.

- [ ] **Step 2: Verify** `Test-Path skills/lore/reference/sdk/dotnet.md` → `True`.

- [ ] **Step 3: Commit** `git add skills/lore/reference/sdk/dotnet.md; git commit -q -m "docs: add lore .NET SDK reference"`

### Task 7.5: `reference/sdk/go.md`

**Files:** Create `skills/lore/reference/sdk/go.md`

- [ ] **Step 1: Write** install + worked example for `lore-go`, sourced ONLY from `_grounding/sdk-go.md`; mark gaps `<!-- UNVERIFIED -->`.

- [ ] **Step 2: Verify** `Test-Path skills/lore/reference/sdk/go.md` → `True`.

- [ ] **Step 3: Commit** `git add skills/lore/reference/sdk/go.md; git commit -q -m "docs: add lore Go SDK reference"`

---

## Phase 8: Integration verification & README

### Task 8.1: Verify progressive-disclosure pointers resolve

**Files:** none (verification)

- [ ] **Step 1: Confirm every `reference/...` path mentioned in `SKILL.md` exists on disk**

Run:
```powershell
Select-String -Path skills/lore/SKILL.md -Pattern 'reference/[A-Za-z0-9/_-]+\.md' -AllMatches |
  ForEach-Object { $_.Matches.Value } | Sort-Object -Unique |
  ForEach-Object { "$_ => $(Test-Path "skills/lore/$_")" }
```
Expected: every line ends `True`. Any `False` → fix the pointer or create the missing file.

- [ ] **Step 2: Confirm no stray `<!-- UNVERIFIED -->` markers remain unintentionally**

Run: `Select-String -Path skills/lore -Pattern 'UNVERIFIED' -Recurse | Select-Object Path,Line`
Expected: review each hit; each must be a deliberate, justified gap (not laziness). Resolve any that can now be grounded.

### Task 8.2: Write `README.md`

**Files:** Create `README.md`

- [ ] **Step 1: Write** what the plugin is, what the skill covers, install instructions (per Task 0.1 marketplace mechanics), and the Lore version/commit stamp it was verified against.

- [ ] **Step 2: Verify links** — every relative link in `README.md` resolves.

Run:
```powershell
Select-String -Path README.md -Pattern '\]\(([^)]+\.md)\)' -AllMatches |
  ForEach-Object { $_.Matches } | ForEach-Object { $p = $_.Groups[1].Value; "$p => $(Test-Path $p)" }
```
Expected: every line ends `True`.

- [ ] **Step 3: Commit** `git add README.md; git commit -q -m "docs: add plugin README"`

### Task 8.3: Final skill-loads sanity check

**Files:** none

- [ ] **Step 1: Validate the whole tree** — frontmatter parses, both manifests parse, all reference files non-empty.

Run:
```powershell
Get-Content .claude-plugin/plugin.json -Raw | ConvertFrom-Json | Out-Null
Get-Content .claude-plugin/marketplace.json -Raw | ConvertFrom-Json | Out-Null
Get-ChildItem skills/lore/reference -Recurse -Filter *.md | Where-Object { $_.Length -eq 0 } | Select-Object FullName
```
Expected: no JSON errors; the empty-file query returns nothing.

- [ ] **Step 2: Clean up the grounding container**

```powershell
docker rm -f lore-grounding
```
Expected: container removed.

- [ ] **Step 3: Final commit** `git add -A; git commit -q -m "chore: finalize lore skill plugin"`

---

## Self-Review (author checklist — completed)

**Spec coverage:** Setup/install → Tasks 4.1, 1.2; Daily VCS ops → 5.1; SDK (4 langs + model) → 7.1–7.5; Diagnosing failures → 6.1; Concepts/"learn" → 3.1; Plugin packaging → 0.1, 0.2, 8.2; Docker CLI grounding → 1.2, 1.3; container SDK introspection → 1.4; version stamp → 1.5/2.1. All spec sections map to a task.

**Placeholder scan:** No "TBD/TODO/handle edge cases" left. The only intentional markers are `<!-- UNVERIFIED -->`, which are a defined grounding mechanism (resolved or justified in Task 8.1), not placeholders.

**Type consistency:** SDK symbol names (`LoreGlobalArgs`, `LoreRepositoryCreateArgs`, `LoreFileStageArgs`, `LoreRevisionCommitArgs`, `LoreBranchPushArgs`, `LoreRepositoryCloneArgs`, `LoreEventTag`, `LoreEventFFI`, `LoreLogConfig`) used consistently across 2.1, 7.1, 7.2 and verified live against `_grounding/python-types.txt` rather than trusted from memory.

**Known dependency:** Phases 2–7 are blocked on Phase 1 grounding files. Phase 1 Task 1.2 (CLI install path) is the critical-path risk; its Path B fallback (`cargo build`) is slower but unblocks everything else.