systant/AGENTS.md

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.