# Advisory AI · AGENTS

## Roles
- Backend engineer (.NET 10, C# preview) for `StellaOps.AdvisoryAI*` services and worker.
- Docs engineer for Advisory AI runbooks and user guides in `docs/advisory-ai` and related policy/SBOM docs.
- QA automation engineer for `__Tests/StellaOps.AdvisoryAI.Tests` (unit/golden/property/perf).

## Working Directory
- Primary: `src/AdvisoryAI/**` (WebService, Worker, Hosting, plugins, tests).
- Docs: `docs/advisory-ai/**`, `docs/policy/assistant-parameters.md`, `docs/modules/sbom-service/*` when explicitly touched by sprint tasks.
- Shared libraries allowed only if referenced by Advisory AI projects; otherwise stay in-module.

## Required Reading (treat as read before DOING)
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/advisory-ai/architecture.md`
- Sprint context: `docs/implplan/SPRINT_0111_0001_0001_advisoryai.md`
- Guardrail and ops knobs: `docs/policy/assistant-parameters.md`

## Working Agreements
- Determinism first: stable ordering, seeded randomness, UTC ISO-8601 timestamps, content-addressed caches; no wall-clock timing in tests.
- Offline-friendly: no hardcoded external endpoints; respect BYO trust roots and offline bundles.
- Observability: structured logs with event ids; expose counters and (optional) OTEL traces guarded by config.
- Configuration: prefer `IOptions` + validated options with data annotations; map env vars in docs.
- Security: least privilege, short-lived keys, no embedding secrets; honor guardrail phrases and sanitization paths documented in policy knobs.
- Queue/cache: avoid unbounded growth; make capacities and TTLs configurable; default to conservative limits.

## Testing
- Run `dotnet test src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/StellaOps.AdvisoryAI.Tests.csproj` before marking DONE.
- Add/extend golden/property tests for new behaviors; keep fixtures deterministic (seeded caches, static input data).
- For perf-sensitive paths, keep benchmarks deterministic and skip in CI unless flagged.

## Docs & Change Sync
- When changing behaviors or contracts, update relevant docs under `docs/modules/advisory-ai`, `docs/policy/assistant-parameters.md`, or sprint-linked docs; mirror decisions in sprint **Decisions & Risks**.
- If new advisories/platform decisions occur, notify sprint log and link updated docs.

## Contracts & Dependencies
- SBOM context feed: follow `SBOM-AIAI-31-001` contract (idempotent, extend-only, no versioning).
- DevOps runbook `DEVOPS-AIAI-31-001` governs packaging/on-prem toggles; do not ship manifests without it.
- Console/CLI dependencies remain gating for UI/CLI docs (see sprint tracker).

## Tooling
- Target `net10.0`; use latest Microsoft.* packages compatible with net10.
- NuGet: use `.nuget/packages/` cache; avoid floating versions.
- Linting/analyzers: keep nullable enabled; treat warnings as errors where feasible.