Spectra

Serena MCP Tools — Semantic code analysis and editing with clangd for C++20 and Python

Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists, where the question should be treated as a graphify query first. Turns any input (code, docs, papers, images, videos) into a persistent knowledge graph with god nodes, community detection, and query/path/explain tools.

Drives a live Spectra instance via the embedded MCP automation server (default http://127.0.0.1:8765/mcp). Use for smoke tests, screenshots, UI commands, figure/series setup, and visual debugging after builds — whenever validating rendering without writing a harness.

Spectra Agent Skill Set

Plan, design, and implement Spectra C++/GLSL/Python changes. Use when breaking down a feature, making architecture decisions before coding, or writing/fixing source in src/, include/spectra/, shaders, tests, or python/.

Spectra git and release workflows: conventional commits, branches, PRs, version bumps, release tags, merge conflicts, changelog. Use for commit, branch, PR, release, version.txt, squash merge, cherry-pick, or git status/diff questions.

Fix or edit Spectra GitHub Actions (.github/workflows). Use for CI failures, new matrix jobs, golden/sanitizer jobs, release.yml, lavapipe/xvfb setup, or masking vs root-cause CI fixes.

Runs Spectra visual QA with spectra_qa_agent --design-review: 57 screenshots, triage P0–P3 in plans/QA_design_review.md, minimal theme/ImGui fixes. Use for UI polish, visual bugs, design review, or screenshot regressions.

Coordinates multi-domain Spectra QA: performance, golden, memory, design, accessibility, API, ROS. Use for full QA sweep, release gate, or routing QA after changes when scope spans multiple areas.

End-to-end Spectra development orchestration: plan → design → implement → build → test → scoped QA. Use for full features, large refactors, or when the user wants the full dev cycle with sub-skill routing.

Router for all Spectra project Cursor skills. Use at the start of any Spectra task to pick the right skill — rendering, Vulkan, Python IPC, CMake, QA agents, simplification, or visual validation. Invoke when unsure which Spectra workflow applies, when onboarding to this repo, or when the user says "use Spectra skills".

Develops Spectra 3D rendering: Axes3D, Series3D, camera, depth, colormaps, Blinn-Phong lighting, and 3D shaders. Use for mesh/surface/point cloud work, 3D visual bugs, camera orbit/pan/zoom, or anything under axes3d/ and *3d shaders.

Registers a new Spectra UI command in the command palette and optional keyboard shortcut with undo support. Use when adding menu actions, palette entries, shortcuts, or execute_command MCP targets in src/ui/commands/.

Creates a new runnable Spectra example in examples/ with CMake target and build wiring. Use when demonstrating a feature, adding a minimal repro, or extending the example gallery.

Adds a new Spectra plot series type end-to-end — core model, shaders, Vulkan pipeline, renderer draw path, and tests. Use for bar charts, heatmaps, contours, or new 2D/3D series in src/core/ and src/render/.

Adds GLSL 450 vertex/fragment shaders to Spectra, SPIR-V compile at configure time, pipeline registration, and renderer draw integration. Use for new visual primitives, SDF line/marker shaders, or 3D lighting in src/gpu/shaders/.

Adds Spectra unit tests, golden image tests, or Google Benchmark cases with correct CMake labels (gpu, golden). Use when adding test coverage, fixing regressions, or creating visual baselines in tests/.

Simplifies Spectra C++ while preserving behavior, Vulkan sync safety, threading, and public APIs. Use for deduplication, flattening control flow, narrowing interfaces, dead-code removal, or when the user asks to simplify or reduce complexity — not for rewrites, renames-only, or swapchain/fence changes.

Works on Spectra data path: decimation (LTTB), filters, transforms, streaming append, CSV load, GPU upload. Use for large datasets, live data, NaN handling, bench_decimation, or src/data/ and series append performance.

Diagnoses Spectra Vulkan rendering failures — validation layers, swapchain OUT_OF_DATE, buffer uploads, pipeline/SPIR-V mismatches, and lavapipe software rendering. Use for GPU errors, blank frames, validation spam, resize glitches, or shader pipeline issues in src/render/vulkan/.

Mandatory visual validation loop for Spectra rendering/UI changes: build, kill old processes, launch app, plot via MCP, screenshot, golden compare. Use for ANY shader, theme, ImGui, or pixel change — even small color tweaks.

Modifies Spectra binary IPC: message types, TLV codec, daemon routing, transport. Use for multi-process mode, REQ_* messages, Python↔C++ codec parity, session graph, or framing/desync bugs in src/ipc/ and src/daemon/.

Extends or debugs the Spectra Python package and IPC client in python/spectra/. Use for plot()/show() easy API, session/transport errors, codec drift vs C++, pyproject, examples, or embedding — whenever Python talks to the backend daemon.

Audits Spectra accessibility: WCAG contrast, colorblind palettes, keyboard nav, high-contrast theme. Use when changing theme colors, legend/series colors, or new interactive UI controls.

Tests Spectra Python API, IPC roundtrips, and C++ easy API contracts. Use when pytest fails, cross_codec breaks, examples crash, or public API compatibility is at risk.

Hunts Spectra CPU/GPU memory leaks with ASan, Valgrind, VMA budget. Use for RSS growth, figure close not freeing GPU memory, or open issue M1 in QA docs.

Runs Spectra stress/fuzz QA with spectra_qa_agent, triages qa_report, reproduces seed crashes, updates plans/QA_results.md. Use for stability, performance regressions, fuzz failures, or long-running QA sessions.

Guards Spectra pixel output via golden tests and unit suite. Use when golden fails, updating baselines, adding golden coverage for new series/UI, or before merge on rendering changes.

QA for spectra-ros: spectra_ros_qa_agent scenarios, ROS UI/dataflow regressions. Use when ROS2 adapter, bag player, or ros panels break under stress.

Audit Spectra for colorblind-safe palettes, WCAG AA contrast ratios, keyboard navigation completeness, and high-contrast theme correctness. Use when adding new UI elements, reviewing theme colors, verifying colorblind palette support, or checking that all interactive controls are reachable via keyboard.

Simplify Spectra codebase while preserving behavior, performance, Vulkan correctness, threading model, and public APIs. Use for reducing duplication, flattening control flow, narrowing interfaces, separating pure logic from side-effects, and removing verified dead code. Do NOT use for architectural rewrites, sweeping renames, formatting-only changes, or modifications to swapchain/fence/semaphore choreography without explicit justification.

Run Spectra visual QA design reviews end-to-end with `spectra_qa_agent`, from screenshot capture to UI/UX bug triage and minimal code fixes. Use when asked to run `--design-review`, inspect screenshot regressions, update `plans/QA_design_review.md`, or apply targeted theme/ImGui/overlay rendering polish tied to QA findings.

Hunt GPU and CPU memory leaks in Spectra using Valgrind, AddressSanitizer, and VMA budget queries. Use when RSS growth exceeds 100MB, when closing figures doesn't free GPU memory, when investigating M1 (open issue), or when profiling heap allocations across QA sessions.

Run Spectra stability and performance QA end-to-end with `spectra_qa_agent`, including deterministic stress/fuzz execution, report triage, crash reproduction, and verification of fixes. Use when asked to run QA scenarios or fuzzing, investigate `qa_report` warnings/errors, reproduce seed-based regressions, or update `plans/QA_results.md` and `plans/QA_update.md`.

Develop, extend, or debug 3D rendering features in Spectra. Use when adding new 3D series types (mesh, surface, point cloud, volume), modifying camera behavior, implementing lighting models, adding colormaps, working on depth buffer or transparency, extending the 3D axes system, or fixing 3D visual artifacts. Covers the full 3D pipeline from data model through math transforms to GPU rendering.

Develop, extend, or debug the Spectra data pipeline — decimation, filtering, transforms, live streaming, CSV loading, and real-time data updates. Use when adding new data sources, optimizing large dataset handling, implementing new filters or transforms (log, FFT, normalization), fixing streaming latency, or extending the decimation engine. Covers the full data path from input through processing to GPU buffer upload.

Extend, debug, or modify the Spectra IPC binary protocol used for multi-process communication. Use when adding new message types, modifying the codec (serialize/deserialize), debugging protocol framing errors, extending the daemon session graph, or working on Python↔Backend message roundtrips. Covers the wire format, TLV payload encoding, transport layer, and daemon routing.

Develop, extend, or debug the Spectra Python API and bindings. Use when adding new Python plotting functions, extending the easy API, fixing Python↔Backend communication, debugging session/transport issues, adding Python examples, or updating the Python package. Covers the Python client library, IPC codec mirror, session management, embedding API, and Qt backend integration.

Test Spectra's Python API, IPC protocol, and C++ easy-API for correctness, backwards compatibility, and crash-safety. Use when adding new Python bindings, debugging IPC message handling, verifying easy-API examples still work, or running the Python test suite.

Guard Spectra against rendering regressions using golden image tests and unit test suite. Use when asked to update golden images, investigate failing golden tests, add new golden baselines for new series types or UI states, or verify that a code change does not break existing pixel-level rendering output.