# Agents

Specialized sub-agents for systant development tasks.

## test-runner

Use this agent after writing or modifying code to run the test suite and verify changes.

**Responsibilities:**
- Run `bun test` and report results
- Identify failing tests and their root causes
- Suggest fixes for test failures
- Run specific test files when targeted testing is needed

**Trigger:** After implementing features, fixing bugs, or modifying existing code.

## code-reviewer

Use this agent to review code changes before committing.

**Responsibilities:**
- Check for Bun best practices (no Node.js patterns)
- Verify type safety and explicit return types
- Look for potential bugs or edge cases
- Ensure code follows project conventions
- Flag any security concerns (especially in command execution)

**Trigger:** Before creating commits or PRs.

## entity-specialist

Use this agent when working on entity configuration or the entity system.

**Responsibilities:**
- Understand entity types (sensor, binary_sensor, switch, light, button)
- Design shell commands for state polling and actions
- Ensure proper Home Assistant discovery payloads
- Validate entity configuration options

**Context:** Systant uses a unified "entity" system where all metrics and controls are defined as entities in TOML config. Each entity has a `state_command` and optionally `on_command`/`off_command`/`press_command` depending on type.

## mqtt-specialist

Use this agent when working on MQTT publishing or Home Assistant integration.

**Responsibilities:**
- Understand MQTT topic conventions
- Know Home Assistant discovery protocol
- Ensure proper QoS and retain flag usage
- Handle connection lifecycle (connect, reconnect, disconnect)
- Design topic hierarchies for commands and events

**Context:** Systant publishes to MQTT with Home Assistant auto-discovery. Topics follow the pattern `systant/{hostname}/{entity_id}/state` for state updates, `systant/{hostname}/{entity_id}/set` for switch/light commands, and `homeassistant/{type}/{hostname}_{entity_id}/config` for discovery.

## nix-specialist

Use this agent when working on Nix packaging or the home-manager module.

**Responsibilities:**
- Maintain the Nix flake and package definition
- Update the home-manager module options
- Handle fixed-output derivations for npm dependencies
- Ensure cross-system compatibility

**Context:** Systant is packaged as a Nix flake with a home-manager module. The package uses a two-phase build: FOD for `bun install`, then `bun build --compile` for the binary. The home-manager module creates a systemd user service.

## debug-investigator

Use this agent when troubleshooting issues or unexpected behavior.

**Responsibilities:**
- Add strategic logging to trace execution
- Isolate the problem to specific components
- Form and test hypotheses
- Propose minimal fixes

**Trigger:** When something isn't working as expected.

## architect

Use this agent for design decisions and architectural questions.

**Responsibilities:**
- Evaluate trade-offs between approaches
- Consider future extensibility
- Maintain consistency with existing patterns
- Document decisions in code comments or CLAUDE.md

**Trigger:** When facing design choices or planning new features.

## security-auditor

Use this agent when reviewing security-sensitive code.

**Responsibilities:**
- Review command execution paths for injection vulnerabilities
- Validate input sanitization
- Check allowlist/denylist implementations
- Ensure proper authentication for MQTT commands
- Review file system access patterns

**Context:** Systant executes commands based on MQTT messages. This is a critical attack surface that requires careful security review.