Workspace Monitor Dev

Workspace Monitor Development

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Adding new features to workspace-monitor
• Fixing bugs in the core system
• Adding support for new IDEs
• Modifying database schema
• Updating CLI commands
• Working on web dashboard
• Integrating with Windsurf or OpenCode
• Setting up development environment

Architecture

1. Development Environment Setup

# Install UV if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/gauravahujame/workspace-monitor.git
cd workspace-monitor
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev,web]"

2. Run Tests

source .venv/bin/activate
pytest

3. Add CLI Command

Add to src/workspace_monitor/cli.py:

@cli.command()
@click.option('--option', default='value', help='Description')
def mycommand(option):
    """Command description."""
    pass

4. Add API Endpoint

Add to src/workspace_monitor/web/server.py:

@app.get("/api/endpoint")
def endpoint():
    return {"data": "response"}

5. Modify Database Schema

# 1. Update initialize_schema() in core.py
# 2. Add migration logic if needed
# 3. Document changes in AGENTS.md
# 4. Ensure backward compatibility

6. Add IDE Support

To add support for a new IDE (e.g., Cursor):

# 1. Create adapter in src/workspace_monitor/ide_adapters/
# 2. Implement IDEAdapter interface
# 3. Write to same SQLite database for unified tracking
# 4. Update docs/IDE_INTEGRATION_ANALYSIS.md
# 5. Add installation instructions to README.md

7. Code Quality Checks

# Format with black
black src/

# Lint with ruff
ruff src/

# Type check with mypy
mypy src/workspace_monitor

8. Platform-Specific Testing

# macOS
export PLATFORM="darwin"
# Test data directory: ~/Library/Application Support/workspace-monitor/

# Linux
export PLATFORM="linux"
# Test data directory: ~/.workspace-monitor/

9. Debug Hook Issues

# Check Windsurf hooks
cat ~/.codeium/windsurf/hooks.json

# Test hook processor
~/.workspace-monitor/venv/bin/python -m workspace_monitor.hooks.processor

# Check logs
cat ~/.workspace-monitor/hook_errors.log  # Linux
cat ~/Library/Application\ Support/workspace-monitor/hook_errors.log  # macOS

10. Release Preparation

# 1. Run all tests
pytest

# 2. Check type hints
mypy src/workspace_monitor

# 3. Format code
black src/

# 4. Lint
ruff src/

# 5. Update version in pyproject.toml

# 6. Update CHANGELOG.md

# 7. Test one-click installer
./install.sh

# 8. Test Windsurf hooks

# 9. Test OpenCode plugin (if changed)

Reference

• Database Schema - Complete table definitions and relationships
• Code Patterns - Common patterns for database queries, git analysis, hooks
• IDE Integration Guide - How to add support for new IDEs
• Architecture - Detailed system architecture

Project docs: AGENTS.md, README.md

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Source: gauravahujame/workspace-monitor — distributed by TomeVault.