# Tools Module - Agent Guidelines

## Module Overview
The Tools module contains small CLI utilities and smoke-check harnesses used for offline and CI validation across the StellaOps platform. These tools should remain deterministic, fast to run, and safe for air-gapped environments.

## Working Directory
- Primary path: `src/Tools/`
- Work only inside the tool subfolder you are modifying unless the sprint explicitly permits cross-module edits.

## Roles Covered
- Backend engineer: .NET 10/C# CLI tools and harnesses.
- QA / automation: deterministic smoke checks and validation tooling.

## Required Reading Before DOING
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- When a tool targets a specific module, read that module's architecture dossier under `docs/modules/<module>/architecture.md`.

## Execution Rules
- Update sprint `Delivery Tracker` status when you start/stop/finish: TODO -> DOING -> DONE/BLOCKED.
- Keep outputs deterministic: stable ordering, UTC ISO-8601 timestamps, fixed seeds where randomness exists.
- Default to offline-safe behavior; avoid network calls unless explicitly documented.

## Coding & CLI Guidelines
- Use `System.CommandLine` or standard `Host` patterns already used in the repo.
- Prefer explicit error reporting with clear exit codes.
- Avoid non-ASCII output unless already present and justified.

## Testing
- Add unit tests for parsing, validation, and determinism-critical logic.
- Place tests under `src/Tools/__Tests/<ToolName>.Tests` when introducing new tests.
- If tests depend on module-specific fixtures, document them in the sprint report.

## Documentation
- Update `docs/implplan/SPRINT_*.md` and relevant module docs when tool behavior changes.