ianshank

Use when: working in packages/jetson_yolo_gcs — adding a detector backend (YOLO/Hailo/ONNX/TensorRT), a tracker backend (Norfair/SORT), GStreamer camera/egress pipeline, the MAVLink LANDING_TARGET bridge, precision-landing safety, or the perception pipeline failure policy.

Use when: running pre-PR checks, performing regression testing, validating ruff linting/formatting, verifying mypy type safety, and checking test coverage before pushing.

Use when: working on the optional NVIDIA Nemotron inference bridge — meshsa.inference, NemotronClient/InferenceService/NemotronConfig, MESHSA_INFERENCE_* env vars, aiohttp session reuse, [AI Insight] feedback-loop filter, or the aioresponses test mocks.

Use when: adding or changing metrics/health export — RouterMetrics, render_prometheus, per-transport counters, the /metrics or /healthz route, HealthConfig fields, or a Grafana golden-signal dashboard.

Use when: touching the supervised two-way command path (Initiative C) — meshsa.command.*, flightctl/run_commander.py, arm/disarm/RTL/set_mode, COMMAND_INT/ACK, force-disarm, operator confirmation, command audit log, or arm preconditions.

Use when: starting a roadmap/initiative feature, new milestone work, a transport/codec/backend that adds behavior, or any change big enough to need a design. Author or update a spec under docs/specs first; code cites the spec by section.

Use when: adding a meshsa codec, changing JSON/Compact/CoT encoding, wire format, codec registry, Envelope serialization, per-transport codec bridge, or decode compatibility.

Use when: adding a meshsa transport, radio driver, Meshtastic path, TAK transport, HaLow/IP link, reconnect logic, transport registry entry, or Transport Protocol implementation.

Audit a package's @abstractmethod and Protocol members for missing call sites — dead abstractions that every subclass implements but nothing invokes. Use before adding a new ABC/Protocol or reviewing a diff that touches one, to catch the F1-class defect (an abstract method spec'd in a docstring that never actually runs).

Run the per-module coverage gate for an AlphaGalerkin package the way CI enforces it. Use before opening a PR to confirm a changed package still meets its --cov-fail-under threshold (branch coverage), matching the gates in .github/workflows/ci.yml and the CLAUDE.md Regression Surface.

Standards for authoring C4 architecture documentation in Mermaid — Context, Container, and Component levels, dynamic views for key flows, and diagram hygiene rules. Use when creating or updating architecture docs — trigger phrases include "C4 diagram", "architecture doc", "document the architecture", "add a component diagram", "system context", or "sequence diagram for this flow".

Prescriptive Python house standards covering Protocol-based dependency injection, Pydantic v2 configuration schemas, asyncio discipline, structlog structured logging, and strict typing/lint gates. Use when writing or reviewing any Python module, class, config, or async code — trigger phrases include "new module", "add a config", "wire a dependency", "add logging", "make this async", "fix mypy errors", or "does this meet standards".

House testing standards covering the test pyramid, per-module coverage gates, Hypothesis property-based testing, subprocess contract tests for CLIs, fixtures, deterministic tests, and marker-gated GPU/external tests. Use when writing tests, adding a module, reviewing test coverage, or deciding what kind of test a change needs — trigger phrases include "add tests", "write a test for", "coverage gate", "is this tested", "test this CLI", or "flaky test".

Add a new PDE operator to AlphaGalerkin end-to-end. Use when introducing a PDE family (e.g. a new elliptic/parabolic/vector operator) so it registers in the operator registry, the PDEType enum, the canonical PDE_TYPE_MAP, and every dependent Literal enum — following the documented checklist so scenarios auto-pick it up.

Run the correct AlphaGalerkin regression-surface test command block for a changed code path. Use after editing solver/evaluator/PDE/scenario/agent/codec code to run exactly the guarding test suites the CLAUDE.md Regression Surface table prescribes, instead of guessing which tests to run.

Scaffold a new spec-driven feature in AlphaGalerkin — creates a specs/<feature>.spec.md from specs/TEMPLATE.spec.md and the mirrored src/ module + tests/ stubs. Use when starting any new PoC scenario, PDE operator, agent type, or module so the spec (data contract + acceptance criteria + MetricThreshold thresholds) is written before the code.

Detect and block architecture drift in CI by comparing a codebase's actual Python import graph against a declared C4 component model. Use this whenever the user wants to enforce architecture in CI/CD, fail builds on undocumented dependencies, keep C4/Mermaid diagrams in sync with code, set up architecture tests or fitness functions, prevent layering violations, or guard/lint/gate their architecture — even if they don't name C4 or Mermaid explicitly. Also use it to bootstrap an architecture manifest from an existing repo or to remediate a failing drift check.

Build, validate, and package reusable evaluation datasets for agent and LLM systems from prompts, traces, tool-call logs, metadata, and expected outcomes. Use this when the user asks to gather eval data, create benchmark datasets, normalize traces, define reusable ground truth, bootstrap eval suites, or produce retrieval, tool-invocation, response, or end-to-end evaluation artifacts.

Benchmark and A/B-test multiple LLMs or systems-under-test on one evaluation dataset. Use this whenever the user wants to compare models side by side, rank candidates by a score, run a multi-model comparison, set up a persistent A/B eval campaign, decide whether a new model is significantly better than a baseline, or produce a comparative HTML/JSON benchmark report.

LLM-as-a-judge evaluations over OpenAI-compatible APIs (including NVIDIA Nemotron & LM Studio). Use whenever evaluating output quality, correctness, or scoring responses using standard rubrics.

Generates or updates C4 architecture documentation as Mermaid diagrams in the host repo (docs/architecture/ by default, or the repo's existing docs location). Produces Level 1 context and Level 2 container diagrams, plus Level 3 components only for the subsystem being changed. Updates existing diagrams in place and flags drift between diagrams and code instead of silently rewriting them.

Runs a security and quality review checklist over a diff or named files in an isolated forked subagent. Covers injection, secrets, authz/authn, error handling, resource leaks, concurrency, compatibility, test coverage, and hardcoded config. Returns severity-ranked findings with file:line and a blocking/non-blocking/clean verdict. Read-only - never edits code or proposes inline fixes.

Instantiates a constraint-programming planning template for a new task, producing a single markdown plan with five sections - objective function, feasible region, permission architecture, feedback loop, and context persistence. All success criteria must be mechanically verifiable (commands, not vibes).

Enforces test-driven development - derive observable behaviors from the requirement, write failing tests first (including edge and negative cases), confirm they fail for the right reason, implement the minimum to pass, refactor green, and report red-to-green evidence. Never weakens assertions to make tests pass.

DEV-SQE session handoff protocol. Captures files changed, tests added, coverage data, and report paths. Updates ledger, summary, and state files. Detects design gaps and creates handoff documents when blocked.

Planning session handoff protocol. Captures task breakdowns, architecture decisions, acceptance criteria, and dependency maps. Updates ledger, summary, and state files. Produces handoff documents to DEV-SQE when tasks are ready for implementation.

Pre-PR session handoff protocol. Validates code quality, runs checks, verifies documentation, and prepares PR artifacts. Updates ledger, summary, and state files.

DEV-SQE session handoff protocol. Captures files changed (committed and uncommitted), tests added, coverage data, and report paths. Updates ledger, summary, and state files. Detects design gaps.

Finalize architecture and lock the spec for development.

Run Wildlife Watcher ruff, mypy, pytest, coverage, and ML pipeline checks through the repo harness. Use for lint, typecheck, regression, quality gate, and pre-merge validation tasks.

Verify that every required Wildlife Watcher directory has an AGENTS.md file. Use for agent customization maintenance, repo hygiene, and hierarchy validation.

Build the Wildlife Watcher camera-node firmware with PlatformIO and inspect the resulting compile output. Use for firmware compile checks, dependency issues, and binary-size review.

Publish synthetic Wildlife Watcher detection payloads to the configured MQTT broker. Use for kiosk smoke tests, UI validation, MQTT topic checks, and display-node debugging without hardware.

Bootstrap a dedicated Wildlife Watcher roadmap worktree for Phase 2 PIR/power or Phase 3 ML work. Use for worktree setup, branch isolation, and phase-scoped experimentation.

Scaffold a new sensor driver with tests and config

Diagnose and fix a GitHub issue

Run linting and type checking, fix violations

Run the test suite with coverage reporting

Validate the spec-driven development specs under specs/*.SPEC.md against the harness spec schema v2. Use when adding or editing a phase spec, or before driving a phase with the harness Ralph loop.

Run the full Strategos-MCTS local quality gate before any commit or push: format check, lint, type check, tests with branch coverage, and a hardcoded-secret grep. Use whenever you are about to push, open a PR, or want CI/local parity.

Produce or refresh the evidence-backed test/coverage baseline in docs/STATUS.md (pass-rate plus per-module branch coverage). Use to re-establish the source of truth after dependency or test changes, and to pick coverage targets.

Debug and verify MouseDroid Jetson Orin Nano hardware deployment. Use for: sensor verification (camera, GPIO, LiDAR, speaker, microphone), Jetson SSH connection, config sync and Docker deployment, smoke testing, and troubleshooting hardware failures. WHEN: setup Jetson, deploy to Jetson, verify sensors, debug hardware on Jetson, Jetson sensor failing, GPIO not working, camera not initializing, LiDAR not detected, speaker not playing, fix Jetson hardware issue, Jetson pinmux, Jetson config overlay, run smoke test.