feat: add spectracleanse-engineering Claude plugin (9 skills, 2 agents, 6 docs)

spectracleanse-engineering/.claude-plugin/plugin.json

@@ -0,0 +1,60 @@
+{
+  "name": "spectracleanse-engineering",
+  "description": "SpectraCleanse-specific engineering plugin. Covers code review, Render deploy readiness, auth/billing debugging, media-processing pipeline safety, incident response, technical documentation, testing strategy, and founder operating reviews. All skills are calibrated to the SpectraCleanse stack: React + Vite frontend, Node.js/Express backend, SQLite (better-sqlite3), ExifTool (exiftool-vendored), Google Gemini (gemini-2.5-flash), Stripe checkout, and Render/Hyperlift deployment.",
+  "skills": [
+    {
+      "name": "spectracleanse-code-review",
+      "path": "skills/spectracleanse-code-review/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-architecture",
+      "path": "skills/spectracleanse-architecture/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-deploy-readiness",
+      "path": "skills/spectracleanse-deploy-readiness/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-processing-pipeline",
+      "path": "skills/spectracleanse-processing-pipeline/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-auth-billing",
+      "path": "skills/spectracleanse-auth-billing/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-incident-response",
+      "path": "skills/spectracleanse-incident-response/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-documentation",
+      "path": "skills/spectracleanse-documentation/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-testing-strategy",
+      "path": "skills/spectracleanse-testing-strategy/SKILL.md"
+    },
+    {
+      "name": "spectracleanse-founder-operating-review",
+      "path": "skills/spectracleanse-founder-operating-review/SKILL.md"
+    }
+  ],
+  "agents": [
+    {
+      "name": "spectracleanse-repo-researcher",
+      "path": "agents/spectracleanse-repo-researcher.md"
+    },
+    {
+      "name": "spectracleanse-incident-commander",
+      "path": "agents/spectracleanse-incident-commander.md"
+    }
+  ],
+  "docs": [
+    "docs/product-context.md",
+    "docs/render-deploy-checklist.md",
+    "docs/mcp-roadmap.md",
+    "docs/supported-formats-and-processing-boundaries.md",
+    "docs/env-and-secrets-reference.md",
+    "docs/plugin-validation.md"
+  ]
+}

spectracleanse-engineering/.mcp.json.example

@@ -0,0 +1,58 @@
+{
+  "_comment": "SpectraCleanse Engineering Plugin – MCP configuration example. Copy to .mcp.json and fill in real values. NEVER commit .mcp.json to version control.",
+
+  "mcpServers": {
+
+    "github": {
+      "_status": "planned",
+      "_description": "GitHub MCP for repo context, PRs, issues, and commit history. Install from https://github.com/github/github-mcp-server",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "REPLACE_WITH_YOUR_GITHUB_PAT"
+      }
+    },
+
+    "sentry": {
+      "_status": "planned – configure if/when Sentry is added to SpectraCleanse",
+      "_description": "Sentry MCP for production error context during incident response.",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sentry"],
+      "env": {
+        "SENTRY_AUTH_TOKEN": "REPLACE_WITH_YOUR_SENTRY_TOKEN",
+        "SENTRY_ORG": "REPLACE_WITH_YOUR_ORG_SLUG",
+        "SENTRY_PROJECT": "spectracleanse"
+      }
+    },
+
+    "playwright": {
+      "_status": "planned – for UI smoke test automation",
+      "_description": "Playwright MCP for browser-based smoke tests: upload flow, auth, checkout modal, download.",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"],
+      "env": {
+        "PLAYWRIGHT_BASE_URL": "https://spectracleanse.com"
+      }
+    },
+
+    "spectracleanse-admin": {
+      "_status": "planned – does not exist yet; see docs/mcp-roadmap.md for spec",
+      "_description": "Future SpectraCleanse Admin MCP. Exposes deploy health, env validation, smoke checks, usage stats, and release notes generation. To be built as a remote MCP server backed by the Render deployment.",
+      "url": "REPLACE_WITH_SPECTRACLEANSE_ADMIN_MCP_URL",
+      "headers": {
+        "Authorization": "Bearer REPLACE_WITH_ADMIN_MCP_SECRET"
+      },
+      "_tools": [
+        "get_deploy_health",
+        "validate_env",
+        "run_smoke_checks",
+        "list_recent_processing_failures",
+        "get_checkout_failures",
+        "get_usage_and_plan_stats",
+        "list_supported_formats",
+        "draft_release_notes_from_commits"
+      ]
+    }
+
+  }
+}

spectracleanse-engineering/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog – spectracleanse-engineering plugin
+
+All changes to this plugin are documented here.
+
+## [Unreleased]
+
+### Added
+- Created SpectraCleanse-specific engineering plugin scaffold (`spectracleanse-engineering/`)
+- Plugin manifest (`.claude-plugin/plugin.json`) with 9 skills, 2 agents, 6 docs registered
+- `spectracleanse-code-review` skill: upload/MIME/ExifTool/Gemini/auth/CORS/Stripe-aware code review
+- `spectracleanse-architecture` skill: Render-constrained architecture decision framework
+- `spectracleanse-deploy-readiness` skill: Render/Hyperlift pre-deploy checklist with env gate and smoke tests
+- `spectracleanse-processing-pipeline` skill: format matrix, trust boundaries, ExifTool and browser-side cleanse review
+- `spectracleanse-auth-billing` skill: JWT, /api/me, 402 upgrade, Stripe checkout, plan-desync debugging
+- `spectracleanse-incident-response` skill: incident classes mapped to SpectraCleanse failure modes
+- `spectracleanse-documentation` skill: accurate doc generation with current-vs-planned distinction
+- `spectracleanse-testing-strategy` skill: test surface audit starting from current zero-test state
+- `spectracleanse-founder-operating-review` skill: solo-founder shipping review replacing generic standups
+- `spectracleanse-repo-researcher` agent: read-only repo exploration with citation discipline
+- `spectracleanse-incident-commander` agent: production triage with hypothesis ranking
+- `docs/product-context.md`: full stack reference with risk model and known assumptions
+- `docs/render-deploy-checklist.md`: Render/Hyperlift-specific deploy checklist
+- `docs/mcp-roadmap.md`: 3-phase MCP integration plan with Admin MCP tool spec
+- `docs/supported-formats-and-processing-boundaries.md`: format matrix with verification instructions
+- `docs/env-and-secrets-reference.md`: all env vars with types, roles, and Render notes
+- `docs/plugin-validation.md`: local install and manual validation checklist
+- `.mcp.json.example`: safe placeholder MCP config (no real secrets)
+- `README.md`: plugin overview, stack reference, install instructions
+- Documented VITE_API_URL vs VITE_BACKEND_URL discrepancy between app.tsx and .env.example
+- Documented Node 18 in ci.yml vs Node 20.20.2 in .nvmrc — noted as known conflict
+
+### Notes
+- Initial version created from live repo inspection (May 2026)
+- All stack facts verified from: `package.json`, `server.js`, `server/cleansePolicy.js`,
+  `server/processor.js`, `app.tsx`, `.env.example`, `.nvmrc`, `.github/workflows/ci.yml`,
+  `docs/manual-qa-checklist.md`, `PIPELINE.md`, `deploy.md`

spectracleanse-engineering/README.md

@@ -0,0 +1,105 @@
+# SpectraCleanse Engineering Plugin
+
+A Claude plugin built specifically for engineering work on [SpectraCleanse](https://spectracleanse.com) — the AI-provenance-marker cleansing and SEO metadata injection tool for audio and video files.
+
+This plugin is **not** a generic engineering assistant. Every skill, checklist, and doc in here is calibrated to the actual SpectraCleanse repo: its stack, endpoints, deployment model, risk surfaces, and founder workflow.
+
+---
+
+## What this plugin helps with
+
+| Skill | When to use it |
+|---|---|
+| `spectracleanse-code-review` | Reviewing changes to server.js, app.tsx, cleansePolicy.js, processor.js |
+| `spectracleanse-architecture` | Making architectural decisions: storage, auth upgrades, queue, API split |
+| `spectracleanse-deploy-readiness` | Pre-deploy gate checks for Render/Hyperlift releases |
+| `spectracleanse-processing-pipeline` | Reviewing or designing file-processing and ExifTool behavior |
+| `spectracleanse-auth-billing` | Debugging JWT, /api/me, 402 upgrade flow, Stripe checkout |
+| `spectracleanse-incident-response` | Production triage: broken deploy, CORS failure, Gemini outage |
+| `spectracleanse-documentation` | Writing accurate README, env, API, or user-facing docs |
+| `spectracleanse-testing-strategy` | Designing smoke tests, CI gates, and integration test fixtures |
+| `spectracleanse-founder-operating-review` | Solo-founder shipping review: what shipped, risks, next move |
+
+---
+
+## What this plugin does NOT do
+
+- It does not auto-deploy to Render or Hyperlift.
+- It does not store or handle real API keys, secrets, or webhook secrets.
+- It does not claim format support without verifying from `server/cleansePolicy.js`.
+- It does not execute live Stripe or Gemini calls.
+- It does not replace the manual QA checklist in `docs/manual-qa-checklist.md`.
+
+---
+
+## Stack reference (confirmed from repo)
+
+- **Frontend**: React 18 + Vite 4, TypeScript 5, Tailwind CSS 3, `lucide-react`
+- **Backend**: Node.js 20.20.2, Express 4, `server.js` as entrypoint
+- **Database**: SQLite via `better-sqlite3` 9, WAL mode, tables: `users`, `jobs`
+- **Media processing**: `exiftool-vendored` 28, `music-metadata` 11, `browser-id3-writer` (browser-side MP3)
+- **AI**: Google Gemini `gemini-2.5-flash` via REST (`/api/generate-seo`)
+- **Billing**: Stripe 16, subscription checkout, webhook at `/api/stripe-webhook`
+- **Auth**: email/password + bcrypt, JWT 7-day expiry, Bearer token
+- **Frontend env var**: `VITE_API_URL` (used in `app.tsx`) — note: `.env.example` lists `VITE_BACKEND_URL` but the frontend reads `VITE_API_URL`
+- **Deployment**: Render / Spaceship Hyperlift (both documented); Docker support present
+
+---
+
+## Installation / local testing
+
+See `docs/plugin-validation.md` for full instructions.
+
+Quick start:
+```bash
+# From repo root, point Claude at this plugin directory
+claude --plugin-dir ./spectracleanse-engineering
+```
+
+Or reference it in your `.claude/settings.json`:
+```json
+{
+  "pluginDirs": ["./spectracleanse-engineering"]
+}
+```
+
+---
+
+## Agents
+
+- **spectracleanse-repo-researcher** — read-only repo exploration; finds actual files, endpoints, env vars before any claim is made
+- **spectracleanse-incident-commander** — production triage; ranks hypotheses, separates facts from guesses, focuses on user impact first
+
+---
+
+## MCP roadmap
+
+See `docs/mcp-roadmap.md`. Short version:
+1. Remote SpectraCleanse Admin MCP (deploy health, env validation, smoke checks, usage stats)
+2. GitHub MCP (issues, PRs, commit context)
+3. Sentry MCP (if/when error monitoring is configured)
+4. Playwright MCP (UI smoke tests)
+
+---
+
+## Safety / security notes
+
+- No real secrets are stored in this plugin. `.mcp.json.example` uses placeholders only.
+- Never commit a real `.mcp.json` (containing live tokens) to version control.
+- All documented endpoints and env vars are verified from the repo. If the repo changes, update this plugin.
+- Skills marked `conservative` will not suggest auto-running risky operations.
+
+---
+
+## Keeping this plugin current
+
+When you make significant changes to SpectraCleanse, update:
+
+| Change | Update |
+|---|---|
+| New API endpoint | `docs/product-context.md`, `spectracleanse-code-review/SKILL.md` |
+| New env var | `docs/env-and-secrets-reference.md`, `spectracleanse-deploy-readiness/SKILL.md` |
+| Format support change | `docs/supported-formats-and-processing-boundaries.md`, `spectracleanse-processing-pipeline/SKILL.md` |
+| New plan tier | `spectracleanse-auth-billing/SKILL.md`, `docs/product-context.md` |
+| New deployment platform | `docs/render-deploy-checklist.md`, `spectracleanse-deploy-readiness/SKILL.md` |
+| Gemini model change | `spectracleanse-processing-pipeline/SKILL.md`, `docs/product-context.md` |

spectracleanse-engineering/agents/spectracleanse-incident-commander.md

@@ -0,0 +1,93 @@
+# spectracleanse-incident-commander
+
+## Role
+Production triage agent for SpectraCleanse incidents. Ranks hypotheses, separates confirmed facts from guesses, focuses on user impact and containment first, then root cause. Does not pretend to have checked a live service unless a tool confirmed it.
+
+## Behavior rules
+- Start with user impact, not root cause. Answer "who is affected and what can't they do?" before "why is this happening?"
+- Rank hypotheses by likelihood, not by familiarity. The most familiar-sounding cause is not always the most likely.
+- Clearly distinguish: `[CONFIRMED]` (directly observed via tool, log, or response) vs. `[HYPOTHESIS]` (inferred, not yet verified).
+- Propose containment actions before investigation deep-dives. Rollback beats debugging.
+- Never say "the DB is fine" or "Stripe is configured" without evidence from an actual check.
+- If no live tooling is connected, say so and ask for log output, curl responses, or Render/Hyperlift dashboard screenshots.
+- After an incident is resolved, produce a prevention item — one checklist or monitoring addition that would catch this earlier next time.
+
+## Incident severity model
+
+| Severity | Criteria | Time to respond |
+|---|---|---|
+| P0 | All users blocked (site down, auth broken, no uploads possible) | Immediate |
+| P1 | Core feature down for some users (processing failures, Stripe checkout broken) | Within 1 hour |
+| P2 | Degraded experience (Gemini SEO unavailable, slow processing) | Within 4 hours |
+| P3 | Minor issue (incorrect error message, cosmetic bug) | Next working session |
+
+## Fast triage checklist
+
+Before forming any hypothesis, run:
+
+1. `curl -sf https://api.spectracleanse.com/api/health`
+   - `{"status":"ok"}` → backend running; issue is route-specific or env-specific
+   - Timeout / 502 / 504 → backend not running; check Render/Hyperlift deploy status
+   - `{"error":"API route not found"}` or HTML → something is wrong with the routing setup
+
+2. Check Render/Hyperlift deployment logs for FATAL lines:
+   - `FATAL: missing required environment variable: JWT_SECRET` → server exited at startup; all requests fail
+   - `FATAL: Stripe is not fully configured in production.` → Stripe env vars missing
+   - `FATAL: set FRONTEND_URL or ALLOWED_ORIGINS for production CORS configuration.` → CORS config missing; server exited
+
+3. Check browser console / network tab:
+   - CORS error → `FRONTEND_URL` or `ALLOWED_ORIGINS` misconfiguration
+   - 401 on all requests → JWT_SECRET rotated or requireAuth regression
+   - Requests going to `undefined` or `localhost:3001` in production → `VITE_API_URL` missing from build env
+
+## Containment actions by class
+
+| Class | Containment |
+|---|---|
+| Broken deploy | Rollback to previous deploy SHA in Render/Hyperlift |
+| JWT_SECRET rotated | All users must re-login; cannot revert without reverting the secret |
+| CORS misconfiguration | Correct `FRONTEND_URL` env var, restart/redeploy service |
+| Stripe env missing | Add missing env vars, redeploy (server exits if Stripe vars missing in prod) |
+| Gemini outage | Communicate that AI metadata generation is temporarily unavailable; processing still works |
+| DB on ephemeral disk | If data was lost: restore from backup; add persistent disk; critical P0 |
+| ExifTool failure spike | Check if a new file format is being uploaded that ExifTool cannot process |
+| VITE_API_URL missing | Trigger a rebuild with `VITE_API_URL` set in build environment |
+
+## Output format
+
+```
+## Incident title
+[Short, specific: "SpectraCleanse: [class] – [date/time if known]"]
+
+## Severity
+[P0 / P1 / P2 / P3 and reason]
+
+## User impact
+[CONFIRMED or HYPOTHESIS: who is affected, what they cannot do]
+
+## Timeline
+[Time first noticed, last known-good state, events since]
+
+## Known facts [CONFIRMED]
+[Only things directly observed: API response, log line, env var value, Stripe event]
+
+## Hypotheses [UNCONFIRMED — ranked by likelihood]
+[1. Most likely cause with reasoning
+ 2. Next most likely
+ ...]
+
+## Immediate containment
+[What to do right now — before root cause is confirmed]
+
+## Investigation steps
+[Ordered: what to check next, with expected output for each step]
+
+## Fix
+[Specific code or config change, once root cause is confirmed]
+
+## Verification
+[How to confirm the fix worked]
+
+## Prevention items
+[One or two additions to the deploy checklist, monitoring, or test suite]
+```