Lazy Plugin Loading (Upcoming v1.1)

99% token reduction for non-SpecWeave work through conditional plugin activation.

Status

This feature is planned for v1.1. The specification is complete and approved. Track progress in increment 0171.

The Problem

Currently, SpecWeave installs all 24 plugins (~251 skills) at startup, consuming ~60,000 tokens even when you're doing non-SpecWeave work. This creates several issues:

Problem	Impact
Context bloat	Only 108 of 251 skills (43%) are shown due to token limits
Wasted tokens	~60,000 tokens consumed even when SpecWeave isn't needed
Slower startup	All plugins loaded regardless of user intent
Reduced quality	Important skills get truncated from context

Evidence: <!-- Showing 108 of 251 skills due to token limits --> appears in system prompts.

The Solution

A lazy loading architecture that:

1. Installs only a lightweight router skill (~500 tokens) by default
2. Detects SpecWeave intent from user prompts using keyword matching
3. Hot-reloads full plugins only when needed (leveraging Claude Code 2.1.0+ features)
4. Uses context forking for heavy skills to isolate their context
5. Provides migration path for existing installations

Token Savings

Scenario	Current	After v1.1	Savings
Non-SpecWeave work	~60,000 tokens	~500 tokens	99%
SpecWeave work	~60,000 tokens	~60,000 (loaded on demand)	0%
Mixed session	~60,000 tokens	~30,000 avg	50%

How It Works

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                     LAZY LOADING ARCHITECTURE                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐     ┌──────────────────────────────────────┐ │
│  │  Router Skill    │     │  Skills Cache                         │ │
│  │  (~500 tokens)   │     │  ~/.specweave/skills-cache/           │ │
│  │                  │     │                                        │ │
│  │  - Keyword       │────▶│  ├── specweave/                       │ │
│  │    detection     │     │  │   ├── increment/                   │ │
│  │  - Install       │     │  │   ├── architect/                   │ │
│  │    trigger       │     │  │   └── ... (50+ skills)             │ │
│  │  - State track   │     │  ├── specweave-github/                │ │
│  └──────────────────┘     │  ├── specweave-jira/                  │ │
│           │               │  └── ... (24 plugins)                  │ │
│           │               └──────────────────────────────────────┘ │
│           │                              │                          │
│           ▼                              ▼                          │
│  ┌──────────────────┐     ┌──────────────────────────────────────┐ │
│  │  Active Skills   │◀────│  Hot-Reload Copy                      │ │
│  │  ~/.claude/      │     │  (on detection)                       │ │
│  │  skills/         │     │                                        │ │
│  │                  │     │  cp -r cache/* ~/.claude/skills/      │ │
│  │  Loaded on       │     │  → Activates immediately              │ │
│  │  demand only     │     │  → No restart needed                  │ │
│  └──────────────────┘     └──────────────────────────────────────┘ │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Keyword Detection

The router skill detects SpecWeave intent using these keywords:

Commands:

• /sw:, specweave, increment

Files:

• spec.md, tasks.md, plan.md, metadata.json

Concepts:

• living docs, living documentation
• feature planning, sprint planning
• acceptance criteria, user story

Workflow:

• backlog, kanban, scrum

Integrations:

• jira sync, github sync, ado sync

Advanced:

• auto mode, parallel auto, tdd mode

Detection is case-insensitive and takes under 50ms.

Claude Code Features Used

Feature	Version	How We Use It
Skill Hot-Reload	2.1.0	Skills in ~/.claude/skills/ activate immediately without restart
Context Forking	2.1.0	context: fork runs heavy skills in isolated sub-agent
Setup Hook	2.1.10	Runs on --init for conditional plugin setup
MCP list_changed	2.1.0	Alternative: MCP server can dynamically update tools
Nested Discovery	2.1.0	Auto-discovers skills from .claude/skills/ subdirectories

User Experience

For New Users

After v1.1, specweave init will:

1. Install only the router skill (~500 tokens)
2. Cache full plugins at ~/.specweave/skills-cache/
3. Inform user about lazy loading behavior
4. Full install option: specweave init --full

For Existing Users

Lazy loading is now enabled by default. To force a full refresh:

specweave refresh-plugins --force

Manual Control

Power users can manually manage plugin loading using the vskill CLI:

# Install plugins using vskill (RECOMMENDED)
vskill add specweave --plugin sw              # Core Skill Fabric
vskill install --repo anton-abyzov/vskill --plugin frontend  # Frontend development
vskill add specweave --plugin sw-github       # GitHub integration
vskill add specweave --plugin sw-jira         # JIRA integration

# List installed plugins
vskill list

# Remove a plugin
vskill remove testing

Available plugins:

Short Name	Install Command	Description
sw	vskill add specweave --plugin sw	Core SpecWeave functionality
sw-router	vskill add specweave --plugin sw-router	Agent routing
sw-github	vskill add specweave --plugin sw-github	GitHub integration
sw-jira	vskill add specweave --plugin sw-jira	JIRA integration
sw-ado	vskill add specweave --plugin sw-ado	Azure DevOps integration
frontend	vskill install --repo anton-abyzov/vskill --plugin frontend	Frontend development
backend	vskill install --repo anton-abyzov/vskill --plugin backend	Backend development
infra	vskill install --repo anton-abyzov/vskill --plugin infra	Infrastructure/DevOps
ml	vskill install --repo anton-abyzov/vskill --plugin ml	Machine learning
testing	vskill install --repo anton-abyzov/vskill --plugin testing	Testing/QA

Context Forking for Heavy Skills

Skills larger than 200 lines will use context: fork in their frontmatter:

---
name: pm
description: Product Manager expertise...
context: fork
model: opus
---

This runs the skill in an isolated sub-agent, preventing context bloat in the main conversation. Results return to the main conversation when the forked skill completes.

Skills that will use forking:

• PM Agent
• Architect Agent
• QA Lead Agent
• Tech Lead Agent
• TDD Orchestrator
• And 10+ more heavy skills

State Tracking

Loading state is tracked at ~/.specweave/state/plugins-loaded.json:

{
  "version": "1.0.0",
  "lazyMode": true,
  "loadedAt": "2026-01-18T12:00:00Z",
  "loadedPlugins": [
    {
      "name": "sw",
      "loadedAt": "2026-01-18T12:00:00Z",
      "trigger": "User mentioned 'increment'",
      "skillCount": 50
    }
  ],
  "cachedPlugins": ["sw", "sw-github", "sw-jira", ...],
  "analytics": {
    "totalLoads": 42,
    "avgLoadTimeMs": 850,
    "tokensSaved": 2500000
  }
}

Graceful Degradation

If hot-reload fails:

1. Clear error message shown to user
2. "Restart Claude Code" option offered
3. Failure logged to ~/.specweave/logs/lazy-loading.log
4. Retry mechanism attempts up to 3 times
5. Fallback: vskill add specweave --plugin sw

Cross-Platform Support

macOS/Linux: Bash scripts (default)

Windows: PowerShell alternative with:

• Auto-detection of available shell
• Long path support (>260 chars)
• Same functionality as Bash version

Related Features

• MCP Tool Search - Current built-in Claude Code feature for tool deferred loading
• Context Forking - Claude Code 2.1.0+ feature for isolated sub-agents
• Token Efficiency - Current progressive disclosure approach

Timeline

• Planning: Complete (January 2026)
• Implementation: Planned for v1.1
• Target: 12-20 days development time

Feedback

Have suggestions for the lazy loading feature? Open an issue or join our Discord.