feature-sparks-plugin

name: feature-sparks-plugin description: Use when modifying sparks plugin, debugging hooks, adding knowledge categories, or understanding how knowledge capture works user-invocable: false

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?

Problem	How Sparks Helps
Debugging the same issue twice	Gotchas captured, auto-loaded next time
"Why did we do it this way?"	Decisions + rationale preserved
New feature, no context	Feature dossiers explain architecture
Onboarding (human or AI)	Patterns and procedures documented
Knowledge siloed in conversations	Extracted into searchable, loadable skills

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`)

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

Find Knowledge (`/find` or `sparks-find` skill)

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

Auto-Apply (SessionStart Hook)

Session starts in project with sparks
Hook reads registry, counts entries
Injects compliance instructions + registry into context
Claude checks registry before searching codebase
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

Category	When to Use
feature	End-to-end feature knowledge (flows, architecture, key files)
gotchas	Hard-won debugging insights, non-obvious pitfalls
patterns	Repeatable solutions used across codebase
decisions	Architectural choices + rationale
procedures	Multi-step processes (deploy, release, migrate)
integration	Third-party APIs, vendor quirks
performance	Optimization learnings, benchmarks
testing	Test strategies, coverage decisions
ux	Design patterns, interaction conventions
strategy	Roadmap decisions, prioritization rationale

Key Architecture Decisions

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

Key Files

File	Purpose
`plugins/sparks/skills/learn/SKILL.md`	Capture workflow - categorize, propose, write, register
`plugins/sparks/skills/learn/references/find-template.md`	Template for generating project find skill
`plugins/sparks/skills/apply/SKILL.md`	Compliance instructions for non-hook agents
`plugins/sparks/hooks/scripts/load-knowledge.py`	SessionStart hook - reads registry, injects context
`plugins/sparks/hooks/scripts/register_spark.py`	Creates/updates registry + regenerates find skill

Common Tasks

Adding a New Category

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

Debugging Hook Issues

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

Testing Learn Flow

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