Initial commit

commands/auto.md

@@ -0,0 +1,93 @@
+---
+description: Toggle or set automatic reference tracking on/off
+argument-hint: [on|off]
+allowed-tools: Bash, Write
+---
+
+# auto - Control auto-tracking on/off
+
+Toggle or explicitly set automatic reference tracking state.
+
+## Usage
+
+```bash
+/track:auto          # Toggle between enabled/disabled
+/track:auto on       # Explicitly enable
+/track:auto off      # Explicitly disable
+```
+
+## What it does
+
+1. **Check current status:**
+   - Looks for `./.claude/.ref-autotrack` marker file
+   - If exists → auto-tracking is enabled
+   - If missing → auto-tracking is disabled
+
+2. **Update state:**
+   - **No argument** → toggle current state
+   - **Argument "on"** → enable (create marker if missing)
+   - **Argument "off"** → disable (delete marker if exists)
+
+3. **When enabling:**
+   - Creates `./.claude/.ref-autotrack` with explanatory content:
+     ```
+     # Auto-tracking marker for ref-tracker plugin
+     # Presence = enabled | Absence = disabled
+     # Managed by: /track:auto command
+     # See: /track:help for details
+     ```
+
+4. **When disabling:**
+   - Deletes `./.claude/.ref-autotrack` marker file
+
+5. **Show new status:**
+   - Reports whether auto-tracking is now enabled or disabled
+   - Shows what will be tracked based on current config
+   - Explains how to change verbosity settings
+
+## Output examples
+
+**When enabling:**
+```
+✓ Auto-tracking enabled
+
+The ref-tracker skill will now automatically track:
+- Research sources (WebSearch/WebFetch) → CLAUDE_SOURCES.md
+- Major prompts and outcomes → CLAUDE_PROMPTS.md
+
+Current verbosity settings:
+- Prompts: major (only significant academic/development work)
+- Sources: all (every search operation)
+
+Use /track:config to adjust verbosity settings.
+```
+
+**When disabling:**
+```
+✓ Auto-tracking disabled
+
+The ref-tracker skill will no longer automatically track.
+
+You can still manually track using:
+- /track:update - Scan recent history
+
+To re-enable: /track:auto on
+```
+
+**When toggling:**
+```
+✓ Auto-tracking toggled: OFF → ON
+
+[Shows enabled message above]
+```
+
+## Prerequisites
+
+Run `/track:init` first to create `.claude/` directory structure.
+
+## Notes
+
+- State changes do not affect existing tracked data
+- Manual tracking via `/track:update` works regardless of state
+- Configuration in `.claude/.ref-config` persists across state changes
+- Marker file includes explanatory content for other Claude sessions

commands/config.md

@@ -0,0 +1,114 @@
+---
+description: View or update tracking verbosity configuration
+argument-hint: [prompts=all|major|off] [sources=all|off]
+allowed-tools: Bash, Read, Write
+---
+
+# config - View or update verbosity settings
+
+View or update tracking verbosity configuration.
+
+## Usage
+
+**View current settings:**
+```bash
+/track:config
+```
+
+**Update settings:**
+```bash
+/track:config prompts=all
+/track:config sources=off
+/track:config prompts=major sources=all
+```
+
+## What it does
+
+1. **With no arguments** - Shows current configuration:
+   - Reads `./.claude/.ref-config`
+   - Displays PROMPTS_VERBOSITY and SOURCES_VERBOSITY
+   - Explains what each setting means
+   - Shows example entries for each level
+
+2. **With arguments** - Updates configuration:
+   - Parses `key=value` pairs
+   - Updates `./.claude/.ref-config`
+   - Validates setting values
+   - Shows new configuration
+
+## Configuration options
+
+### PROMPTS_VERBOSITY
+
+Controls what prompts are tracked to `CLAUDE_PROMPTS.md`:
+
+- **`major`** (default) - Only significant multi-step academic/development work
+  - Example: "Implement authentication system", "Debug complex algorithm"
+  - Best for: Academic research, project documentation
+
+- **`all`** - Track every user request
+  - Example: "What is X?", "Explain Y", "Fix typo in file.txt"
+  - Best for: Complete session logs, detailed auditing
+
+- **`minimal`** - Only explicitly user-requested tracking
+  - Only tracks when user says "track this" or similar
+  - Best for: Selective manual curation
+
+- **`off`** - Disable prompt tracking completely
+  - No entries added to CLAUDE_PROMPTS.md
+  - Best for: Source-only tracking
+
+### SOURCES_VERBOSITY
+
+Controls what sources are tracked to `CLAUDE_SOURCES.md`:
+
+- **`all`** (default) - Track all WebSearch/WebFetch operations
+  - Every search logged automatically
+  - Best for: Complete research audit trail
+
+- **`off`** - Disable source tracking completely
+  - No entries added to CLAUDE_SOURCES.md
+  - Best for: Prompt-only tracking
+
+## Example output
+
+**Viewing config:**
+```
+Current tracking configuration (./.claude/.ref-config):
+
+PROMPTS_VERBOSITY=major
+  Tracks: Only significant multi-step academic/development work
+  Example: "Implement user authentication", "Debug performance issue"
+
+SOURCES_VERBOSITY=all
+  Tracks: All WebSearch/WebFetch operations
+  Example: Every search for documentation, APIs, or concepts
+
+To change settings:
+  /track:config prompts=all
+  /track:config sources=off
+  /track:config prompts=minimal sources=all
+```
+
+**Updating config:**
+```
+✓ Configuration updated
+
+PROMPTS_VERBOSITY: major → all
+SOURCES_VERBOSITY: all (unchanged)
+
+New behavior:
+- Every user request will be tracked to CLAUDE_PROMPTS.md
+- All searches continue to be tracked to CLAUDE_SOURCES.md
+```
+
+## Prerequisites
+
+Run `/track:init` first to create `.claude/.ref-config`.
+
+## Notes
+
+- Changes take effect immediately
+- Existing tracked data is not affected
+- Works regardless of auto-tracking status (on/off)
+- Invalid values are rejected with error message

commands/help.md

@@ -0,0 +1,211 @@
+---
+description: Display comprehensive help for the ref-tracker system
+disable-model-invocation: true
+---
+
+# help - Reference tracking system help
+
+Comprehensive help for the ref-tracker system.
+
+## Overview
+
+The ref-tracker system automatically tracks research sources and major prompts for academic work and project documentation.
+
+**Two tracking files:**
+- `CLAUDE_SOURCES.md` - Research sources (WebSearch, WebFetch, documentation)
+- `CLAUDE_PROMPTS.md` - Major prompts and outcomes
+
+**Key features:**
+- Automatic tracking when enabled
+- Configurable verbosity
+- Manual retroactive scanning
+- Attribution system ([User] vs [Claude])
+
+## Commands
+
+### `/track:init` - Initialize tracking
+Set up tracking files and configuration for the current project.
+
+Creates:
+- `CLAUDE_SOURCES.md` (empty)
+- `CLAUDE_PROMPTS.md` (with header)
+- `.claude/.ref-autotrack` (enables auto-tracking)
+- `.claude/.ref-config` (verbosity settings)
+
+**Run this first** before using other tracking commands.
+
+---
+
+### `/track:update` - Retroactive scan
+Scan last 20 messages and add missing tracking entries.
+
+Works even when auto-tracking is disabled (manual override).
+Respects verbosity configuration.
+
+**Use when:** You want to capture recent work retroactively.
+
+---
+
+### `/track:auto` - Toggle auto-tracking
+Enable or disable automatic tracking.
+
+**Enabled:** ref-tracker skill automatically logs sources and prompts
+**Disabled:** Manual tracking only via `/track:update`
+
+**Use when:** You want to pause/resume automatic tracking.
+
+---
+
+### `/track:config` - Manage verbosity
+View or update tracking verbosity settings.
+
+**View:** `/track:config`
+**Update:** `/track:config prompts=all sources=off`
+
+**Use when:** You want to control what gets tracked.
+
+---
+
+### `/track:help` - Show this help
+Display comprehensive documentation.
+
+## File Formats
+
+### CLAUDE_SOURCES.md
+
+**Format:** Pure KV file (no headers, one line per entry)
+
+**Pattern:** `[Attribution] Tool("query"): result`
+
+**Examples:**
+```
+[User] WebSearch("PostgreSQL foreign keys tutorial"): https://postgresql.org/docs/current/ddl-constraints.html
+[Claude] WebFetch("https://go.dev/doc/", "embed.FS usage"): Use embed.FS to embed static files at compile time
+[Claude] Grep("CORS middleware", "*.go"): Found in api/routes.go:23-45
+```
+
+**Attribution:**
+- **[User]** - User explicitly requested ("search the web for...")
+- **[Claude]** - Claude autonomously searched for missing information
+
+---
+
+### CLAUDE_PROMPTS.md
+
+**Format:** Two-line entries with blank separator
+
+**Pattern:**
+```
+Prompt: "user request"
+Outcome: what was accomplished
+
+```
+
+**Example:**
+```markdown
+# CLAUDE_PROMPTS.md
+
+This file tracks significant prompts and development decisions.
+
+---
+
+Prompt: "Implement user authentication with JWT"
+Outcome: Created auth middleware, login/logout endpoints, JWT token generation and verification, integrated with database user model
+
+Prompt: "Debug slow database queries"
+Outcome: Added query logging, identified N+1 problem in user posts endpoint, implemented eager loading, reduced query time from 2.3s to 0.15s
+
+```
+
+---
+
+## Verbosity Settings
+
+Located in `./.claude/.ref-config`:
+
+### PROMPTS_VERBOSITY
+
+- **`major`** (default) - Significant multi-step academic/development work
+- **`all`** - Every user request
+- **`minimal`** - Only explicit user requests to track
+- **`off`** - Disable prompt tracking
+
+### SOURCES_VERBOSITY
+
+- **`all`** (default) - Track all WebSearch/WebFetch operations
+- **`off`** - Disable source tracking
+
+## Academic Workflow Example
+
+**1. Setup (once per project):**
+```bash
+/track:init
+```
+
+**2. Work session:**
+- Auto-tracking captures all searches and major work
+- Sources logged to CLAUDE_SOURCES.md
+- Prompts logged to CLAUDE_PROMPTS.md
+
+**3. Review tracked data:**
+- Open CLAUDE_SOURCES.md - see all research sources
+- Open CLAUDE_PROMPTS.md - see work completed
+- Use for citations, bibliography, project documentation
+
+**4. Adjust if needed:**
+```bash
+/track:config prompts=minimal    # Less verbose
+/track:auto                       # Pause tracking
+```
+
+**5. Export for paper:**
+- CLAUDE_SOURCES.md entries become citations
+- CLAUDE_PROMPTS.md becomes methodology section
+- Clear audit trail of research process
+
+## Tips
+
+**For research papers:**
+- Keep `prompts=major` and `sources=all`
+- Review CLAUDE_SOURCES.md for bibliography
+- Use prompts for methodology section
+
+**For development projects:**
+- Use `prompts=all` for complete audit
+- CLAUDE_PROMPTS.md documents decisions
+- Useful for project retrospectives
+
+**For focused work:**
+- Use `/track:auto` to toggle off
+- Manual `/track:update` when needed
+- Reduces noise during exploration
+
+## File Locations
+
+- Tracking files: Project root (`./CLAUDE_SOURCES.md`, `./CLAUDE_PROMPTS.md`)
+- Configuration: `./.claude/.ref-config`
+- Auto-tracking marker: `./.claude/.ref-autotrack`
+
+## Common Issues
+
+**"No tracking files found"**
+→ Run `/track:init` first
+
+**"Too verbose"**
+→ Use `/track:config prompts=minimal`
+
+**"Missing recent searches"**
+→ Run `/track:update` to scan history
+
+**"Want to pause tracking"**
+→ Use `/track:auto` to toggle off
+
+## Related
+
+- **ref-tracker skill** - Automatic tracking when enabled
+- **Global CLAUDE.md** - Documents the system in detail
+- **Project CLAUDE.md** - Can contain project-specific notes
+
+---
+
+For more help, consult plugin README or global ~/.claude/CLAUDE.md documentation.

commands/init.md

@@ -0,0 +1,64 @@
+---
+description: Initialize reference tracking for the current project
+allowed-tools: Bash, Write
+---
+
+# init - Initialize reference tracking
+
+Initialize reference and research tracking for the current project.
+
+## What it does
+
+1. **Create tracking files:**
+   - Creates `./CLAUDE_SOURCES.md` (empty, pure KV format)
+   - Creates `./CLAUDE_PROMPTS.md` (with header)
+   - If files exist, leaves them unchanged
+
+2. **Create `.claude/` directory structure:**
+   - Creates `./.claude/` directory if missing
+   - Creates `./.claude/.ref-config` with default settings:
+     ```
+     PROMPTS_VERBOSITY=major
+     SOURCES_VERBOSITY=all
+     ```
+   - **Note:** Does NOT create `.ref-autotrack` marker (use `/track:auto` to enable)
+
+3. **Check skill availability:**
+   - Verifies ref-tracker skill is available
+   - Reports status
+
+4. **Show setup summary:**
+   - Files created/existing
+   - Auto-tracking status (disabled by default)
+   - Config location
+   - Next steps
+
+## Default configuration
+
+After init, tracking is **disabled by default**. Configuration file contains these defaults:
+- **Sources**: Track all WebSearch/WebFetch operations (when enabled)
+- **Prompts**: Track major academic/development work only (when enabled)
+
+Use `/track:auto` to enable auto-tracking.
+
+## Next steps
+
+After running `/track:init`:
+- Use `/track:update` to scan recent history
+- Use `/track:config` to adjust verbosity settings
+- Use `/track:auto` to toggle auto-tracking on/off
+- Use `/track:help` for detailed documentation
+
+## Files created
+
+```
+.claude/
+├── .ref-autotrack          # Marker: auto-tracking enabled
+└── .ref-config             # Verbosity settings
+CLAUDE_SOURCES.md           # Research sources (KV format)
+CLAUDE_PROMPTS.md           # Major prompts and outcomes
+```
+
+## Output
+
+Concise status report showing what was created and current configuration.

commands/update.md

@@ -0,0 +1,62 @@
+---
+description: Scan recent conversation history and add missing tracking entries
+allowed-tools: Read, Write
+---
+
+# update - Retroactive tracking scan
+
+Scan recent conversation history and add missing tracking entries.
+
+## What it does
+
+1. **Review last 20 messages** in this conversation looking for:
+   - WebSearch operations and results
+   - WebFetch operations and results
+   - Grep/Read operations on documentation
+   - Major user requests (features, debugging, refactoring)
+
+2. **Track sources** to `./CLAUDE_SOURCES.md`:
+   - Format: `[User] Tool("query"): result` or `[Claude] Tool("query"): result`
+   - **[User]** if user explicitly requested search ("search the web for...")
+   - **[Claude]** if Claude autonomously searched for missing info
+   - Result is URL or brief concept (1-2 sentences max)
+
+3. **Track prompts** to `./CLAUDE_PROMPTS.md`:
+   - Two-line format:
+     ```
+     Prompt: "user request verbatim or paraphrased"
+     Outcome: what was accomplished in present tense
+
+     ```
+   - Blank line separator after each entry
+   - Only significant work (features, complex tasks, multi-step work)
+   - Respects verbosity setting from `.claude/.ref-config`
+
+4. **Read configuration:**
+   - Checks `./.claude/.ref-config` for verbosity settings
+   - Respects PROMPTS_VERBOSITY (major, all, minimal, off)
+   - Respects SOURCES_VERBOSITY (all, off)
+
+5. **Check prerequisites:**
+   - Verifies tracking files exist
+   - If missing, suggests running `/track:init` first
+
+6. **Show summary:**
+   - Number of sources added
+   - Number of prompts added
+   - Confirmation message
+
+## Usage notes
+
+- Works regardless of auto-tracking status (manual override)
+- Respects verbosity configuration
+- Scans only last 20 messages (not entire conversation)
+- Safe to run multiple times (appends new entries only)
+
+## Prerequisites
+
+Run `/track:init` first to create tracking files and configuration.
+
+## Output
+
+Concise summary showing what was tracked from recent history.