contextune: Instructions file for Claude Code

Contextune Development Guide

Project Overview

Contextune is a Claude Code plugin that provides natural language to slash command mapping. It uses a 3-tier detection cascade (keyword → Model2Vec → Semantic Router) to detect user intent and suggest appropriate slash commands.

Core Technology:

• Python 3.10+ with UV for dependency management
• Claude Code plugin architecture (hooks system)
• Machine learning: Model2Vec embeddings + Semantic Router
• Documentation: MkDocs with mkdocstrings

Critical Development Rules

Versioning

Version Increment Rule:

• ALL version changes increment by 0.0.1 (patch level only)
• Current: 0.8.3 → Next: 0.8.4 → After: 0.8.5
• NO major/minor bumps (0.9.0, 1.0.0, etc.)

Files to Update:

1. .claude-plugin/plugin.json - version field
2. .claude-plugin/marketplace.json - version field (marketplace and plugin entry)
3. Update both files in same commit

Example:

// .claude-plugin/plugin.json
{
  "version": "0.8.4"  // Was 0.8.3
}

// .claude-plugin/marketplace.json
{
  "version": "0.8.4",  // Marketplace version
  "plugins": [{
    "version": "0.8.4"  // Plugin version
  }]
}

Package Management - UV Only

ALWAYS use UV for Python operations:

# Run scripts
uv run script.py

# Run with dependencies
uv run --with pytest pytest

# Add dependencies
uv add package-name

# Add dev dependencies  
uv add --dev package-name

# Sync environment
uv sync

# Run module
uv run -m pytest

NEVER use:

• pip install - use uv add
• python script.py - use uv run script.py
• poetry or conda - UV only

UV Script Format (PEP 723)

All standalone scripts MUST use inline script metadata:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "model2vec>=0.3.0",
#     "numpy>=1.24.0"
# ]
# ///

# Script code here

Why: UV automatically creates ephemeral venvs with correct dependencies. This is how Claude Code hooks work.