shopdb-flask/.claude/skills/README.md

# ShopDB Skills

Custom slash commands for common workflows. **13 skills total** - comprehensive automation toolkit.

## Quick Reference by Category

**Development & Testing:**
- `/pre-commit` - Complete pre-commit validation
- `/test-changes` - Quick test suite
- `/docker-rebuild` - Rebuild Docker after changes

**Deployment:**
- `/full-deploy` - Complete air-gap deployment workflow
- `/agent-deploy-full` - Build, deploy, verify C# agent
- `/deploy-frontend` - Deploy Vue to production
- `/merge-wilm` - Merge upstream branch

**Infrastructure:**
- `/vm-snapshot` - Hyper-V snapshot management
- `/production-health` - System health check
- `/migration-check` - Database migration validation
- `/security-scan` - Security vulnerability scan

**Development Tools:**
- `/plugin-new` - Scaffold new plugin
- `/build-agent` - Build C# executables

---

## Development & Testing Skills

### `/pre-commit`  NEW
**Complete pre-commit validation workflow - tests, style checks, build verification, ADR compliance**

**When to use:** Before EVERY commit to wj branch or creating PR.

**What it does:**
- Runs full test suite (pytest -v)
- Checks naming and style conventions
- Builds frontend to catch errors
- Verifies both URLs work (Vite + Flask)
- Scans for hardcoded site data (ADR-015)
- Validates migration linearity (ADR-008)
- Provides pass/fail summary

**Time saved:** 8-16 hrs/year

### `/test-changes`
**Run pytest and frontend build checks before committing (lighter than /pre-commit)**

**When to use:** Quick validation during development.

**What it does:**
- Runs pytest for backend
- Builds frontend to catch errors
- Runs style/naming checker
- Provides targeted test commands

### `/docker-rebuild`  NEW
**Complete Docker rebuild workflow - build frontend, rebuild image, run migrations, verify health**

**When to use:** After merging branches, dependency changes, or Dockerfile modifications.

**What it does:**
- Builds frontend (prebuilt approach)
- Rebuilds Docker image
- Restarts containers cleanly
- Runs database migrations
- Verifies services healthy
- Tests both URLs work

**Time saved:** 8 hrs/year

---

## Deployment Skills

### `/full-deploy`  NEW
**Complete deployment workflow for air-gapped production - saves 50-100 hrs/year from 312 hrs coordination burden**

**When to use:** Deploying to production (wj branch) or ops (dev branch).

**What it does:**
- Pre-deploy validation (tests, health, security, migrations)
- Creates deployment bundle
- Deploys to dev PC first (staging test)
- Generates production deployment runbook
- Guides through production deployment
- Post-deploy validation
- Provides rollback plan if issues

**Time saved:** 50-100 hrs/year (from 312 hrs/year burden)

### `/agent-deploy-full`  NEW
**Complete agent deployment workflow - build, test, deploy to VM, verify endpoint reporting**

**When to use:** Deploying C# agent or tray updates to VM.

**What it does:**
- Builds agent and tray executables
- Tests locally (quick sanity check)
- Deploys to VM via SSH
- Restarts Windows service
- Verifies agent reports to API
- Checks endpoint appears in UI
- Monitors logs for errors

**Time saved:** 3 hrs/year

### `/deploy-frontend`
**Build frontend and deploy to prod server via Y drive**

**When to use:** After making Vue/frontend changes that need to go to production.

**What it does:**
- Runs production build with correct VITE_BASE_PATH
- Copies dist/ to Y: drive
- Provides instructions for IIS restart
- Verifies build output

### `/merge-wilm`
**Merge latest wilm branch commits into wj with proper conflict resolution**

**When to use:** Periodically to bring wilm improvements into wj prod branch.

**What it does:**
- Fetches latest from origin
- Shows commits to be merged
- Handles common conflicts (csproj, routes.py)
- Coordinates agent/tray versions
- Creates merge commit

### `/build-agent`
**Build and publish agent and tray executables to Documents/shopdb-builds folder**

**When to use:** After making changes to agent or tray C# code, before deployment.

**What it does:**
- Compiles both executables
- Creates dated folder in Documents
- Generates VERSION.txt with release notes
- Copies .exe files ready for deployment

---

## Infrastructure Skills

### `/vm-snapshot`  NEW
**Create, restore, list, and manage Hyper-V VM snapshots**

**When to use:** Before risky changes, for baseline snapshots, weekly cleanup.

**What it does:**
- Creates snapshot with descriptive name
- Lists all snapshots with dates and sizes
- Restores to specific snapshot
- Deletes old snapshots (cleanup)
- Verifies VM state after restore

**Time saved:** 78 hrs/year

### `/production-health`  NEW
**Comprehensive health check of running system - services, plugins, database, API response times, logs**

**When to use:** Before/after deployments, daily monitoring, investigating issues.

**What it does:**
- Checks all Docker services running
- Verifies all plugins loaded
- Scans recent logs for errors
- Tests login flow works
- Verifies endpoints reporting
- Checks database connectivity and performance
- Tests API response times
- Validates critical workflows

**Value:** Deployment confidence, early issue detection

### `/migration-check`  NEW
**Deep validation of plugin migrations for ADR-008 compliance - check linearity, dependencies, foreign keys**

**When to use:** Before committing migrations, before production deployment.

**What it does:**
- Verifies each plugin migration chain is linear
- Checks for circular dependencies between plugins
- Validates foreign key references exist
- Tests migrations up AND down
- Verifies PLUGIN_TABLE_OWNERS coordination
- Checks for duplicate version numbers
- Identifies orphaned migrations

**Value:** Prevents critical ADR-008 violations in production

### `/security-scan`  NEW
**Run security checks from Sept 2026 audit - scan for hardcoded credentials, exposed keys, missing authentication**

**When to use:** Before commits, before deployments, after merging external code.

**What it does:**
- Scans for hardcoded credentials and API keys
- Checks for collector keys in committed files
- Verifies certificate validation enabled
- Checks authentication on sensitive endpoints
- Scans for SQL injection vulnerabilities
- Verifies HTTPS enforcement
- Checks for sensitive data in logs
- Validates input sanitization

**Value:** Prevents security regressions from Sept 2026 audit

---

## Development Tools

### `/plugin-new`  NEW
**Scaffold new ShopDB plugin following ADRs - directory structure, BasePlugin boilerplate, migrations, Vue component**

**When to use:** Creating a new plugin.

**What it does:**
- Creates complete plugin directory structure
- Generates BasePlugin subclass with manifest
- Creates SQLAlchemy model (Asset polymorphism)
- Creates Flask API blueprint (CRUD endpoints)
- Initializes Alembic migrations
- Creates Vue frontend component
- Generates tests
- Creates README with checklist
- Adds to PLUGIN_TABLE_OWNERS

**Time saved:** 30-60 min per new plugin

## How Skills Work

Skills are markdown files that provide structured instructions. When you type `/skill-name`, Claude:
1. Loads the skill instructions
2. Follows the steps defined in the skill
3. Adapts to the current situation

Skills save tokens by avoiding repeated explanations of common workflows.

## Tips

- Use skills for repetitive tasks
- Skills preserve context about your environment
- You can still ask Claude to deviate from skill steps if needed
- Skills work best when the workflow is consistent

## Adding New Skills

Create a new `.md` file in `.claude/skills/` with:
```markdown
---
name: skill-name
description: Brief description
---

Instructions for Claude to follow...
```