VersionGuard Quick Start Guides

Agent-Specific 5-Minute Guides

Get started with VersionGuard in 5 minutes, tailored to your role.

IRIS Quick Start
NEXUS Quick Start
BOLT Quick Start
FORGE Quick Start
CLIO Quick Start
PORTER Quick Start
Common Commands

IRIS Quick Start

Your Role: Desktop Development Specialist

Why VersionGuard Matters to You: You requested this tool after losing 2 hours to Socket.IO v4/v5 incompatibility. Never again.

Step 1: Setup (1 minute)

# Clone to your tools directory
cd C:\Users\logan\OneDrive\Documents\AutoProjects
# VersionGuard is already here!

Step 2: Pre-Session Check (2 minutes)

Before starting ANY development session:

# Check your project
cd path/to/your/project
python "C:\Users\logan\OneDrive\Documents\AutoProjects\VersionGuard\versionguard.py" scan .

Step 3: Interpret Results (1 minute)

COMPATIBLE     → Proceed with development
WARNING        → Review warnings, then proceed carefully
INCOMPATIBLE   → STOP! Resolve issues first, notify FORGE

Step 4: Create Alias (1 minute)

Add to your PowerShell profile:

function versionguard { python "C:\Users\logan\OneDrive\Documents\AutoProjects\VersionGuard\versionguard.py" $args }

Now just use:

versionguard scan .

IRIS Workflow Summary

1. Receive development task
2. Run: versionguard scan ./project
3. If INCOMPATIBLE → Stop, notify via Synapse
4. If OK → Start development

NEXUS Quick Start

Your Role: VS Code Agent

Why VersionGuard Matters to You: Catch dependency issues before they manifest as confusing runtime errors.

Step 1: Add VS Code Task

Create .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Check Version Compatibility",
            "type": "shell",
            "command": "python",
            "args": [
                "C:\\Users\\logan\\OneDrive\\Documents\\AutoProjects\\VersionGuard\\versionguard.py",
                "scan",
                "${workspaceFolder}"
            ],
            "group": "build",
            "presentation": {
                "reveal": "always"
            }
        }
    ]
}

Step 2: Run Task

Press Ctrl+Shift+P → "Tasks: Run Task" → "Check Version Compatibility"

Step 3: Add to Launch Configuration

In launch.json, add preLaunchTask:

{
    "name": "Debug with Version Check",
    "type": "node",
    "request": "launch",
    "preLaunchTask": "Check Version Compatibility"
}

NEXUS Workflow Summary

1. Open project in VS Code
2. Run version check task (Ctrl+Shift+B if configured)
3. Review output panel
4. Proceed with development

BOLT Quick Start

Your Role: Executor Agent

Why VersionGuard Matters to You: Prevent failed builds due to version incompatibilities.

Step 1: Add to Build Script

#!/bin/bash
# build.sh

echo "=== Version Compatibility Check ==="
python versionguard.py scan . --json -o .versionguard.json

if grep -q '"status": "incompatible"' .versionguard.json; then
    echo "BUILD BLOCKED: Version incompatibilities!"
    python versionguard.py scan .
    exit 1
fi

echo "Version check passed"
rm .versionguard.json

# Continue with build...
npm install
npm run build

Step 2: GitHub Actions Integration

# .github/workflows/build.yml
jobs:
  build:
    steps:
      - name: Version Check
        run: |
          python versionguard.py scan . --json -o report.json
          if grep -q '"incompatible"' report.json; then exit 1; fi

Step 3: Report Artifacts

      - name: Upload Version Report
        uses: actions/upload-artifact@v3
        with:
          name: version-report
          path: report.json
        if: always()

BOLT Workflow Summary

1. Build triggered
2. Run version check first
3. If INCOMPATIBLE → Fail build immediately
4. If OK → Continue pipeline

FORGE Quick Start

Your Role: Orchestrator #1

Why VersionGuard Matters to You: Validate task environments before assigning work to agents.

Step 1: Pre-Task Validation

from pathlib import Path
from versionguard import VersionGuard, CompatibilityStatus

def validate_before_assignment(task: dict) -> bool:
    """Check project compatibility before assigning task."""
    project = task.get("project_path")
    
    if project:
        guard = VersionGuard(Path(project))
        guard.scan_project()
        guard.check_compatibility()
        report = guard.generate_report()
        
        if report.status == CompatibilityStatus.INCOMPATIBLE:
            # Log blocker
            print(f"[FORGE] Task blocked: {report.summary}")
            return False
    
    return True

Step 2: Task Queue Integration

When receiving task requests:

def process_task_request(task_request):
    # Validate environment first
    if not validate_before_assignment(task_request):
        # Return task to queue with "BLOCKED" status
        task_request["status"] = "BLOCKED"
        task_request["blocker"] = "version_incompatibility"
        return task_request
    
    # Assign to agent
    assign_to_agent(task_request)

FORGE Workflow Summary

1. Receive task request
2. Validate project with VersionGuard
3. If INCOMPATIBLE → Block task, request resolution
4. If OK → Assign to appropriate agent

CLIO Quick Start

Your Role: Trophy Keeper

Why VersionGuard Matters to You: Track "Clean Stack" achievements and version hygiene.

Step 1: Trophy Check Integration

from pathlib import Path
from versionguard import VersionGuard, CompatibilityStatus

def check_clean_stack(project_path: str) -> dict:
    """Award Clean Stack trophy for compatible projects."""
    guard = VersionGuard(Path(project_path))
    guard.scan_project()
    guard.check_compatibility()
    report = guard.generate_report()
    
    return {
        "trophy": "CLEAN_STACK_TROPHY",
        "awarded": report.status == CompatibilityStatus.COMPATIBLE,
        "points": 25 if report.status == CompatibilityStatus.COMPATIBLE else 0,
        "details": {
            "frontend_deps": len(guard.frontend_deps),
            "backend_deps": len(guard.backend_deps),
            "issues": len(guard.issues)
        }
    }

Step 2: Project Audit

def audit_all_projects(project_dirs: list) -> dict:
    """Generate compatibility report for all projects."""
    results = {}
    
    for project in project_dirs:
        guard = VersionGuard(Path(project))
        guard.scan_project()
        guard.check_compatibility()
        report = guard.generate_report()
        
        results[project] = {
            "status": report.status.value,
            "issues": len(guard.issues)
        }
    
    return results

CLIO Workflow Summary

1. Periodically audit all projects
2. Award Clean Stack trophies
3. Track version hygiene trends
4. Report to team

PORTER Quick Start

Your Role: Mobile Development Specialist

Why VersionGuard Matters to You: Mobile development often involves complex native + JS version requirements.

Step 1: React Native Check

# Check your mobile project
cd your-mobile-app
python versionguard.py scan .

Step 2: Watch for Common Mobile Issues

React Native version vs React version
Native module compatibility
iOS/Android SDK version requirements

Step 3: Pre-Build Check

# Before building
python versionguard.py scan . --json -o .version-check.json
cat .version-check.json | grep status

PORTER Workflow Summary

1. Before any mobile build
2. Run version check
3. Watch for React/React Native mismatches
4. Proceed when clear

Common Commands

Scan Project

# Current directory
python versionguard.py scan .

# Specific path
python versionguard.py scan ./my-project

# With JSON output
python versionguard.py scan . --json -o report.json

Check Specific Packages

# Frontend + Backend combo
python versionguard.py check -f socket.io-client@4.7.2 -b python-socketio@5.8.0

# Multiple frontend packages
python versionguard.py check -f react@18.2.0 -f react-dom@17.0.0

Run Demo

# See the Socket.IO issue that started it all
python versionguard.py demo

Status Meanings

Status	Meaning	Action
`COMPATIBLE`	All clear	Proceed
`WARNING`	Potential issues	Review, then proceed
`INCOMPATIBLE`	Critical issues	STOP, resolve first
`UNKNOWN`	No deps found	Check file paths

Troubleshooting

"No dependencies found"

Make sure you're in the right directory
Check for package.json, requirements.txt, or pyproject.toml
Files in node_modules are ignored

"Command not found"

Use full path:

python "C:\Users\logan\OneDrive\Documents\AutoProjects\VersionGuard\versionguard.py" scan .

Or create an alias (see IRIS Quick Start).

Need Help?

Check EXAMPLES.md for detailed examples
Check README.md for full documentation
Contact ATLAS via SynapseLink

VersionGuard - Pre-validate. Don't waste time.

FilesExpand file tree

QUICK_START_GUIDES.md

Latest commit

History