Sparks Plugin Architecture

Trigger: sparks, /learn, /find, knowledge, registry Confidence: high Created: 2025-01-18 Updated: 2025-01-18 Version: 2

What is Sparks?

Sparks is a knowledge capture and retrieval system for Claude Code projects. It solves the problem of context loss between sessions - when you debug something hard, discover a gotcha, or establish a pattern, that knowledge usually dies with the conversation.

Sparks captures durable knowledge as project-scoped skills that Claude automatically discovers and loads when relevant. Think of it as building institutional memory for your codebase.

Why Use It?

Use Cases

1. Capture Hard-Won Debugging Knowledge

After spending time debugging a tricky issue:

/learn the JWT refresh token was failing because...

Creates a gotcha that loads automatically when someone hits similar symptoms.

2. Document Feature Architecture

After implementing or understanding a feature:

/learn how the auth system works

Creates a feature dossier with flows, key files, and common tasks.

3. Record Architectural Decisions

After making a significant choice:

/learn we chose Redis over Postgres for sessions because...

Preserves the rationale so future you (or teammates) don't reverse it blindly.

4. Find Existing Knowledge

Before diving into unfamiliar code:

/find auth

Searches registry, loads relevant skills into context before you start.

User Flows

Capture Knowledge (/learn)

1. •User invokes /learn with optional topic
2. •Learn skill analyzes conversation for capture-worthy knowledge
3. •Proposes learning with category, triggers, description
4. •On approval: creates skill file + registers in registry + regenerates find skill
5. •Confirmation shown to user

Find Knowledge (/find or sparks-find skill)

1. •User invokes /find {query} or Claude loads sparks-find skill
2. •Registry embedded in skill - no extra file reads
3. •Single match → auto-loads skill into context
4. •Multiple matches → asks user which to load
5. •Knowledge available for current task

Auto-Apply (SessionStart Hook)

1. •Session starts in project with sparks
2. •Hook reads registry, counts entries
3. •Injects compliance instructions + registry into context
4. •Claude checks registry before searching codebase
5. •Matching skills loaded via Skill({skill-name})

Technical Design

Storage Structure (Project-Level)

{{project}}/.claude/skills/
├── sparks-find/
│   ├── SKILL.md                      # Find skill (generated, embedded registry)
│   └── references/
│       └── registry.toon             # Registry source of truth
├── {category}-{slug}/                # Each learning = one skill
│   └── SKILL.md
└── ...

Plugin Structure

plugins/sparks/
├── skills/
│   ├── learn/
│   │   ├── SKILL.md                  # Capture workflow
│   │   └── references/
│   │       └── find-template.md      # Template for project find skill
│   └── apply/
│       └── SKILL.md                  # Compliance (fallback for non-hook agents)
└── hooks/scripts/
    ├── load-knowledge.py             # SessionStart - injects registry
    └── register_spark.py             # Creates registry + find skill

Registry Format

# registry.toon
{skill-name}|{category}|{triggers}|{description}

Example:

feature-auth-flows|feature|auth, login, JWT|Use when implementing or debugging authentication
gotchas-hook-timeout|gotchas|hook, timeout, silent|Use when hooks fail without error output

Categories

Key Architecture Decisions

1. •Project-scoped find skill - generated per-project with embedded registry, not plugin-level
2. •Per-skill storage - each learning is a separate skill file, not inline in registry
3. •user-invocable: false - skills don't clutter /skill list but agent loads via Skill tool
4. •Apply skill retained - fallback compliance for agents without SessionStart hooks
5. •Registry regenerates find skill - register_spark.py keeps find skill in sync

Key Files

Common Tasks

Adding a New Category

1. •Update category table in plugins/sparks/skills/learn/SKILL.md
2. •Add to apply skill categories list
3. •Document when to use it with clear examples

Debugging Hook Issues

1. •Verify registry exists at .claude/skills/sparks-find/references/registry.toon
2. •Test hook output: cd /project && python3 plugins/sparks/hooks/scripts/load-knowledge.py
3. •Check for valid JSON output with systemMessage and additionalContext

Testing Learn Flow

1. •Run /learn in project with a topic
2. •Verify skill created at .claude/skills/{category}-{slug}/SKILL.md
3. •Verify registry updated at .claude/skills/sparks-find/references/registry.toon
4. •Verify find skill regenerated with new entry embedded