ryan
904bef4aa7
- Update architecture section to reflect actual file structure - Document entity system (sensor, binary_sensor, switch, light, button) - Add MQTT topic documentation - Add NixOS/home-manager integration section - Update commands section - Replace metrics-specialist with entity-specialist - Replace events-specialist with nix-specialist - Update mqtt-specialist context for current topic structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# 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.
|