Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

title: Vapora Tracking System - Quick Start Guide date: 2025-11-10 status: READY type: tracking-quickstart

🚀 Vapora Tracking System - Quick Start Guide

⏱️ Time to get running: 5-10 minutes

This guide walks you through installing and getting started with the Vapora tracking system component in the simplest way possible.

Note: This guide is for the tracking system only. For complete Vapora project setup, see QUICKSTART.md.

📋 Prerequisites

You need:

  • ✅ Rust 1.70+ (install from https://rustup.rs)
  • ✅ Cargo (comes with Rust)
  • ✅ Git
  • ✅ 500MB free disk space
  • ✅ Bash or Zsh shell

Check if you have everything:

rustc --version    # Should show Rust 1.70+
cargo --version    # Should show Cargo 1.70+
which git          # Should show /usr/bin/git or similar

🎯 5-Minute Quick Start

Step 1: Build the Tracking System

# Build the tracking crate
cargo build -p vapora-tracking

# Or with backend integration
cargo build -p vapora-backend

Expected output:

    Finished `dev` profile [unoptimized + debuginfo] target(s) in X.XXs

Step 3: Run Tests

# Verify everything works
cargo test -p vapora-tracking --lib

# Should show: test result: ok. 20 passed

Step 4: Start Using It

Option A: Using Slash Commands (Easiest)

# In Claude Code, use the commands:
/log-change "Fixed bug in parser" --impact backend --files 3
/add-todo "Refactor database" --priority H --estimate M
/track-status --project vapora --limit 10

Option B: Using Scripts (Manual Sync)

# Start the tracking service
./scripts/start-tracking-service.nu --verbose

# In another terminal, sync projects (replace with your development directory)
./scripts/sync-tracking.nu --projects-dir ~ --verbose

# Check status
/track-status

Option C: Using API (Integration)

# Query the API
curl http://localhost:3000/api/v1/tracking/summary
curl http://localhost:3000/api/v1/tracking/entries?limit=10

✅ Verify Installation

After building, verify everything works:

Test 1: Build Success

cargo build -p vapora-tracking 2>&1 | tail -3
# Should show: Finished `dev` profile [unoptimized + debuginfo]

Test 2: Tests Pass

cargo test -p vapora-tracking --lib 2>&1 | grep "test result"
# Should show: test result: ok. 20 passed; 0 failed

Test 3: Clippy Clean

cargo clippy -p vapora-tracking --lib 2>&1 | grep "warning:" | wc -l
# Should show: 1 (profile warning only, which is expected)

Test 4: Commands Available

ls ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
# Should show all 3 commands

Test 5: Skill Available

ls ~/.claude/skills/tracking.md
# Should show the file exists

If all 5 tests pass: ✅ Installation Complete!

🎬 First Time Usage

Scenario 1: Log Your First Change

Using Slash Command (Easiest):

/log-change "Implemented user authentication" \
  --impact backend \
  --files 5

What happens:

  1. ✅ Change is logged to database
  2. ✅ Timestamp added automatically
  3. ✅ Can be queried with /track-status

Scenario 2: Create Your First TODO

Using Slash Command:

/add-todo "Review code changes" \
  --priority H \
  --estimate M \
  --due 2025-11-15

What happens:

  1. ✅ TODO created in database
  2. ✅ Can be tracked with /track-status
  3. ✅ Shows up in exports

Scenario 3: Check Your Status

Using Slash Command:

/track-status --limit 5

Output:

✅ Summary
Total entries: 3
Changes: 1
TODOs: 2

🔄 Changes
[2025-11-10T14:30:00Z] - Implemented user authentication
Impact: backend | Breaking: no | Files: 5

📋 TODOs
[HIGH] Review code changes (Medium) - Due: 2025-11-15
[HIGH] Write documentation (Small) - Due: 2025-11-12

📚 Next Steps After Installation

Short Term (Today)

  1. ✅ Log 2-3 changes you've made
  2. ✅ Create 2-3 TODOs for upcoming work
  3. ✅ Run /track-status to see results

Medium Term (This Week)

  1. 📝 Set up daily tracking in your workflow
  2. 🔄 Sync multiple projects with sync-tracking.nu
  3. 📊 Export your tracking data with export-tracking.nu

Long Term (Ongoing)

  1. 📈 Monitor project progress via /track-status
  2. 🎯 Use for sprint planning and retrospectives
  3. 📉 Generate reports from exported data
  4. 🔗 Integrate with other Vapora services

🆘 Need More Help?

QuestionAnswer Location
How do I use the tracking system?TRACKING_SYSTEM_STATUS.md (How to use section)
What are all the features?crates/vapora-tracking/README.md (Features section)
How do I deploy it?crates/vapora-tracking/INTEGRATION.md (Deployment section)
How do I fix an issue?SETUP_TRACKING.md (Troubleshooting section)
What's the architecture?TRACKING_DOCUMENTATION_INDEX.md

⚡ Super Quick Reference

# Build
cargo build -p vapora-tracking

# Test
cargo test -p vapora-tracking --lib

# Use commands
/log-change "Summary" --impact backend
/add-todo "Task" --priority H --estimate M
/track-status --limit 10

# Use scripts
./scripts/sync-tracking.nu --verbose
./scripts/export-tracking.nu json --output report
./scripts/start-tracking-service.nu

# Query API
curl http://localhost:3000/api/v1/tracking/summary

✅ Installation Checklist

  • Rust 1.75+ installed
  • Vapora repo available
  • cargo build -p vapora-tracking succeeds
  • cargo test -p vapora-tracking --lib shows 20 passed
  • Slash commands copied to ~/.claude/commands/
  • Skill copied to ~/.claude/skills/
  • /log-change command works
  • /track-status shows results

All checked? ✅ You're ready to go!

For complete Vapora project setup: See QUICKSTART.md

For tracking system deep dive: See SETUP_TRACKING.md