| name | discovering-spells |
| description | Use when browsing what spells are available - bundled seeds, your personal library, or both. Filter by kind, audience, or update status. |
| kind | workflow |
| audience | anyone |
| ai-tools | any |
| complexity | simple |
| time | under 2 min |
| version | 1.0.0 |
| source | bundled |
Discovering Spells
What this does
Lists spells available in the current session: bundled seeds, the user's personal library, and (optionally) updates available for overrides.
Output is grouped, scannable, and ranked by relevance to the user's recent context.
When to use
- User invoked
/list-spells
- User asks "what skills do I have?" or "what spells exist?"
- User wants to see updates to their overrides
What you bring (Inputs)
- (Optional) Filter flags:
--kind, --audience, --mine, --bundled, --updates
- (Optional) Recent context (used for ranking; auto-extracted)
What you get (Output)
A grouped list of matching spells, each shown as: name — description (kind / audience / version).
How it works (Steps)
This is a workflow.
Stages
Stage 1: Resolve sources
Default sources: bundled spells/ + $WIZARD_HOME. If --mine, only personal. If --bundled, only bundled.
Stage 2: Apply filters
Apply each flag in turn. Filter by kind, audience, etc. as the user specified.
Stage 3: Detect overrides and updates
For each personal spell, check if a bundled spell with the same name exists.
If yes and the bundled version is newer than the personal version, mark the entry with (update available: bundled vX.Y.Z).
If --updates flag is set, only show entries where an update is available.
Stage 4: Rank by relevance
Rank by:
- Update available (top, if
--updates)
- Recently invoked
- Trigger keyword overlap with recent user messages
- Alphabetical within group
Stage 5: Group and print
Group by kind, then by audience. Print:
Discipline (3)
- verifying-before-citing — Use when about to state a factual claim... (researcher / 1.0.0)
- decisions-need-an-alternative — Use when making a choice... (anyone / 1.0.0) [update available: 1.1.0]
...
Workflow (5)
...
Show counts in headers. If a group is empty, omit it.
Stage 6: Print actions
End with one-liner suggestions:
- "Run a spell:
/cast-spell <name>"
- "Build a new one:
/build-spell"
- "Update one:
/refine-spell <name> (or take bundled: /refine-spell <name> --take-bundled)"
Checkpoints
- After Stage 1: source list resolved
- After Stage 2: filtered set generated
- After Stage 3: overrides + updates marked
- After Stage 4: ranked
- After Stage 5: printed grouped
- After Stage 6: actions printed
Loop-back conditions
Return to Stage 2 when the user adds or changes a filter mid-list.
Quality bar
The list is good enough when:
- Every spell in the source set that matches filters is shown
- Overrides and updates are correctly marked
- Output fits on one screen for typical filter results (under 30 entries)
Variations
- Search mode:
--query "<term>" filters by description contains
- JSON mode:
--json for tooling integration
- Single-line mode:
--brief shows just name — description
Example
/list-spells --kind discipline --audience anyone
Discipline / anyone (4):
- verifying-before-citing — Use when about to state a factual claim... (1.0.0)
- decisions-need-an-alternative — Use when making a decision... (1.0.0)
- verifying-before-shipping — Use when about to declare done... (1.0.0)
- using-wizard — boot skill (1.0.0)
Try: /cast-spell verifying-before-citing
Build a new one: /build-spell
