git.stella-ops.org/src/Tools/AGENTS.md

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.