Update Waystone Inventory Skill

When to Activate

Activate this skill when:

• Adding new <Waystone> components to any Grove package

• Removing waystones from pages

• The waystone-inventory CI check fails

• You want to verify the inventory matches actual codebase usage

• After merging PRs that add/remove waystones

Files Involved

File Purpose

.github/waystone-inventory.json

Source of truth for waystone placements

libs/engine/src/lib/ui/components/ui/waystone/Waystone.svelte

Component source

docs/specs/waystone-spec.md

Waystone system specification

Inventory Structure

The inventory tracks waystones by slug, with each slug containing its instances:

{ "waystones": { "total": 15, "breakdown": { "engine": 15, "login": 0, "landing": 0 }, "bySlugs": 10 }, "slugs": [ { "slug": "what-is-rings", "usageCount": 2, "instances": [ { "file": "libs/engine/src/routes/arbor/analytics/+page.svelte", "label": "Learn about Rings", "placement": "page-header", "size": "sm" } ] } ] }

Placement Types

When adding instances, use the appropriate placement type:

Type Description

page-header

Beside <h1> titles on major pages

section-header

Beside <h2> section titles within pages

feature-card

Inside feature showcase cards

inline-help

Inline with paragraph text for contextual hints

error-context

Within error messages linking to troubleshooting

panel-header

In panel or control headers

auth-context

Near auth-related UI for trust building

Step-by-Step Process

1. Find All Waystone Usages

Search for <Waystone in all Svelte files across ALL packages

rg '<Waystone' --type svelte -l

Get slug and label details

rg '<Waystone' --type svelte -A 3

2. Compare with Inventory

Read current inventory

cat .github/waystone-inventory.json | jq '.waystones.total'

Count actual usages

rg '<Waystone' --type svelte | wc -l

3. Identify Discrepancies

Look for:

• New waystones: <Waystone> tags in code but not in inventory

• Removed waystones: Instances in inventory whose files no longer contain the waystone

• Changed metadata: Slug, label, or placement changed

4. Update Inventory JSON

Edit .github/waystone-inventory.json :

Update counts:

"waystones": { "total": <new total instances>, "breakdown": { "engine": <count in engine>, "login": <count in login>, ... }, "bySlugs": <number of distinct slugs> }

Add/update slug entries — add new slugs to the slugs array, or add instances to existing slugs

Update metadata:

"lastUpdated": "YYYY-MM-DD", "lastAuditedBy": "claude/<context>"

5. Commit Changes

gw git commit --write -m "docs: update waystone inventory

• Add <slug> waystone to <package>
• Update total: X -> Y
• Update package breakdown"

Quick Reference Commands

Count all waystone instances across all packages

rg '<Waystone' apps/ libs/ services/ workers/ --type svelte | wc -l

List all unique slugs in use

rg 'slug="([^"]+)"' apps/ libs/ services/ workers/ --type svelte -o -r '$1' | sort -u

Count instances per directory

for dir in apps libs services workers; do count=$(rg '<Waystone' "$dir" --type svelte 2>/dev/null | wc -l | tr -d ' ') echo "$dir: $count" done

Find waystones with specific placement patterns

rg '<Waystone' apps/ libs/ services/ workers/ --type svelte -B 2 -A 2

Adding a New Waystone (Full Checklist)

When adding a new waystone:

• Add <Waystone> component to the target file with appropriate slug, label, and size

• Ensure the file imports Waystone (from $lib/ui in engine, or @autumnsgrove/lattice/ui in other packages)

• Add the instance to .github/waystone-inventory.json

• If it's a new slug, add a new entry to the slugs array

• If the slug already exists, add an instance to the existing entry

• Update waystones.total count

• Update waystones.breakdown.<package> count

• Update waystones.bySlugs if a new slug was added

• Update lastUpdated and lastAuditedBy

• Verify the KB article exists (or note it needs to be created)

CI Integration

The .github/workflows/waystone-inventory.yml workflow:

• Runs on PRs touching **/*.svelte files

• Counts <Waystone occurrences across all packages

• Compares to inventory total

• Comments on PRs when there's a mismatch

• Creates issues for drift on scheduled runs (Thursdays)

When CI fails, run this skill to fix the mismatch.

Checklist

Before finishing:

• All <Waystone> instances in code have entries in inventory

• All inventory instances still exist in code

• total equals sum of all breakdown values

• bySlugs equals the length of the slugs array

• Each slug's usageCount matches its instances array length

• lastUpdated date is today

• Changes committed with descriptive message