# 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.

## metrics-specialist

Use this agent when working on system metric collection.

**Responsibilities:**
- Understand Linux /proc and /sys interfaces
- Know cross-platform metric collection strategies
- Ensure metrics are properly typed and documented
- Validate metric units and normalization

**Context:** Systant collects CPU, memory, disk, and network metrics. Metrics should be normalized (percentages 0-100, bytes for sizes) and include metadata for Home Assistant discovery.

## 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}/{metric_type}`. Command topics use `systant/{hostname}/command/{action}`.

## events-specialist

Use this agent when working on the event/command system.

**Responsibilities:**
- Design secure command execution with allowlists
- Implement event handlers and action dispatching
- Ensure proper input validation and sanitization
- Handle timeouts and error reporting
- Consider security implications of remote command execution

**Context:** Systant listens for MQTT commands and executes configured actions. Security is paramount - all commands must be validated against an allowlist, inputs sanitized, and execution sandboxed where possible.

## 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.