Here’s a condensed **“Stella Ops Developer Guidelines”** based on the official engineering docs and dev guides.

---

## 0. Where to start

* **Dev docs index:** The main entrypoint is `Development Guides & Tooling` (docs/technical/development/README.md). It links to coding standards, test strategy, performance workbook, plug‑in SDK, examples, and more. ([Gitea: Git with a cup of tea][1])
* **If a term is unfamiliar:** Check the one‑page *Glossary of Terms* first. ([Stella Ops][2])
* **Big picture:** Stella Ops is an SBOM‑first, offline‑ready container security platform; a lot of design decisions (determinism, signatures, policy DSL, SBOM delta scans) flow from that. ([Stella Ops][3])

---

## 1. Core engineering principles

From **Coding Standards & Contributor Guide**: ([Gitea: Git with a cup of tea][4])

1. **SOLID first** – especially interface & dependency inversion.
2. **100‑line file rule** – if a file grows >100 physical lines, split or refactor.
3. **Contracts vs runtime** – public DTOs and interfaces live in lightweight `*.Contracts` projects; implementations live in sibling runtime projects.
4. **Single composition root** – DI wiring happens in `StellaOps.Web/Program.cs` and each plug‑in’s `IoCConfigurator`. Nothing else creates a service provider.
5. **No service locator** – constructor injection only; no global `ServiceProvider` or static service lookups.
6. **Fail‑fast startup** – validate configuration *before* the web host starts listening.
7. **Hot‑load compatibility** – avoid static singletons that would survive plug‑in unload; don’t manually load assemblies outside the built‑in loader.

These all serve the product goals of **deterministic, offline, explainable security decisions**. ([Stella Ops][3])

---

## 2. Repository layout & layering

From the repo layout section: ([Gitea: Git with a cup of tea][4])

* **Top‑level structure (simplified):**

  ```text
  src/
    backend/
      StellaOps.Web/            # ASP.NET host + composition root
      StellaOps.Common/         # logging, helpers
      StellaOps.Contracts/      # DTO + interface contracts
      … more runtime projects
    plugins-sdk/                # plug‑in templates & abstractions
    frontend/                   # Angular workspace
  tests/                        # mirrors src 1‑to‑1
  ```

* **Rules:**

  * No “Module” folders or nested solution hierarchies.
  * Tests mirror `src/` structure 1:1; **no test code in production projects**.
  * New features follow *feature folder* layout (e.g., `Scan/ScanService.cs`, `Scan/ScanController.cs`).

---

## 3. Naming, style & language usage

Key conventions: ([Gitea: Git with a cup of tea][4])

* **Namespaces:** file‑scoped, `StellaOps.*`.
* **Interfaces:** `I` prefix (`IScannerRunner`).
* **Classes/records:** PascalCase (`ScanRequest`, `TrivyRunner`).
* **Private fields:** `camelCase` (no leading `_`).
* **Constants:** `SCREAMING_SNAKE_CASE`.
* **Async methods:** end with `Async`.
* **Usings:** outside namespace, sorted, no wildcard imports.
* **File length:** keep ≤100 lines including `using` and braces (enforced by tooling).

C# feature usage: ([Gitea: Git with a cup of tea][4])

* Nullable reference types **on**.
* Use `record` for immutable DTOs.
* Prefer pattern matching over long `switch` cascades.
* `Span`/`Memory` only when you’ve measured that you need them.
* Use `await foreach` instead of manual iterator loops.

Formatting & analysis:

* `dotnet format` must be clean; StyleCop + security analyzers + CodeQL run in CI and are treated as gates. ([Gitea: Git with a cup of tea][4])

---

## 4. Dependency injection, async & concurrency

DI policy (core + plug‑ins): ([Gitea: Git with a cup of tea][4])

* Exactly **one composition root** per process (`StellaOps.Web/Program.cs`).
* Plug‑ins contribute through:

  * `[ServiceBinding]` attributes for simple bindings, or
  * An `IoCConfigurator : IDependencyInjectionRoutine` for advanced setups.
* Default lifetime is **scoped**. Use singletons only for truly stateless, thread‑safe helpers.
* Never use a service locator or manually build nested service providers except in tests.

Async & threading: ([Gitea: Git with a cup of tea][4])

* All I/O is async; avoid `.Result` / `.Wait()`.
* Library code uses `ConfigureAwait(false)`.
* Control concurrency with channels or `Parallel.ForEachAsync`, not ad‑hoc `Task.Run` loops.

---

## 5. Tests, tooling & quality gates

The **Automated Test‑Suite Overview** spells out all CI layers and budgets. ([Gitea: Git with a cup of tea][5])

**Test layers (high‑level):**

* Unit tests: xUnit.
* Property‑based tests: FsCheck.
* Integration:

  * API integration with Testcontainers.
  * DB/merge flows using Mongo + Redis.
* Contracts: gRPC breakage checks with Buf.
* Frontend:

  * Unit tests with Jest.
  * E2E tests with Playwright.
  * Lighthouse runs for performance & accessibility.
* Non‑functional:

  * Load tests via k6.
  * Chaos experiments (CPU/OOM) using Docker tooling.
  * Dependency & license scanning.
  * SBOM reproducibility/attestation checks.

**Quality gates (examples):** ([Gitea: Git with a cup of tea][5])

* API unit test line coverage ≥ ~85%.
* API P95 latency ≤ ~120 ms in nightly runs.
* Δ‑SBOM warm scan P95 ≤ ~5 s on reference hardware.
* Lighthouse perf score ≥ ~90, a11y ≥ ~95.

**Local workflows:**

* Use `./scripts/dev-test.sh` for “fast” local runs and `--full` for the entire stack (API, UI, Playwright, Lighthouse, etc.). Needs Docker and modern Node. ([Gitea: Git with a cup of tea][5])
* Some suites use Mongo2Go + an OpenSSL 1.1 shim; others use a helper script to spin up a local `mongod` for deeper debugging. ([Gitea: Git with a cup of tea][5])

---

## 6. Plug‑ins & connectors

The **Plug‑in SDK Guide** is your bible for schedule jobs, scanner adapters, TLS providers, notification channels, etc. ([Gitea: Git with a cup of tea][6])

**Basics:**

* Use `.NET` templates to scaffold:

  ```bash
  dotnet new stellaops-plugin-schedule -n MyPlugin.Schedule --output src
  ```

* At publish time, copy **signed** artefacts to:

  ```text
  src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/
    MyPlugin.dll
    MyPlugin.dll.sig
  ```

* The backend:

  * Verifies the Cosign signature.
  * Enforces `[StellaPluginVersion]` compatibility.
  * Loads plug‑ins in isolated `AssemblyLoadContext`s.

**DI entrypoints:**

* For simple cases, mark implementations with `[ServiceBinding(typeof(IMyContract), ServiceLifetime.Scoped, …)]`.
* For more control, implement `IoCConfigurator : IDependencyInjectionRoutine` and configure services/options in `Register(...)`. ([Gitea: Git with a cup of tea][6])

**Examples:**

* **Schedule job:** implement `IJob.ExecuteAsync`, add `[StellaPluginVersion("X.Y.Z")]`, register cron with `services.AddCronJob<MyJob>("0 15 * * *")`.
* **Scanner adapter:** implement `IScannerRunner` and register via `services.AddScanner<MyAltScanner>("alt")`; document Docker sidecars if needed. ([Gitea: Git with a cup of tea][6])

**Signing & deployment:**

* Publish, sign with Cosign, optionally zip:

  ```bash
  dotnet publish -c Release -p:PublishSingleFile=true -o out
  cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
  ```

* Copy into the backend container (e.g., `/opt/plugins/`) and restart.

* Unsigned DLLs are rejected when `StellaOps:Security:DisableUnsigned=false`. ([Gitea: Git with a cup of tea][6])

**Marketplace:**

* Tag releases like `plugin-vX.Y.Z`, attach the signed ZIP, and submit metadata to the community plug‑in index so it shows up in the UI Marketplace. ([Gitea: Git with a cup of tea][6])

---

## 7. Policy DSL & security decisions

For policy authors and tooling engineers, the **Stella Policy DSL (stella‑dsl@1)** doc is key. ([Stella Ops][7])

**Goals:**

* Deterministic: same inputs → same findings on every machine.
* Declarative: no arbitrary loops, network calls, or clocks.
* Explainable: each decision carries rule, inputs, rationale.
* Offline‑friendly and reachability‑aware (SBOM + advisories + VEX + reachability). ([Stella Ops][7])

**Structure:**

* One `policy` block per `.stella` file, with:

  * `metadata` (description, tags).
  * `profile` blocks (severity, trust, reachability adjustments).
  * `rule` blocks (`when` / `then` logic).
  * Optional `settings`. ([Stella Ops][7])

**Context & built‑ins:**

* Namespaces like `sbom`, `advisory`, `vex`, `env`, `telemetry`, `secret`, `profile.*`, etc. ([Stella Ops][7])
* Helpers such as `normalize_cvss`, `risk_score`, `vex.any`, `vex.latest`, `sbom.any_component`, `exists`, `coalesce`, and secrets‑specific helpers. ([Stella Ops][7])

**Rules of thumb:**

* Always include a clear `because` when you change `status` or `severity`. ([Stella Ops][7])
* Avoid catch‑all suppressions (`when true` + `status := "suppressed"`); the linter will flag them. ([Stella Ops][7])
* Use `stella policy lint/compile/simulate` in CI and locally; test in sealed (offline) mode to ensure no network dependencies. ([Stella Ops][7])

---

## 8. Commits, PRs & docs

From the commit/PR checklist: ([Gitea: Git with a cup of tea][4])

Before opening a PR:

1. Use **Conventional Commit** prefixes (`feat:`, `fix:`, `docs:`, etc.).
2. Run `dotnet format` and `dotnet test`; both must be green.
3. Keep new/changed files within the 100‑line guideline.
4. Update XML‑doc comments for any new public API.
5. If you add/change a public contract:

   * Update the relevant markdown docs.
   * Update JSON schema / API descriptions as needed.
6. Ensure static analyzers and CI jobs relevant to your change are passing.

For new test layers or jobs, also update the test‑suite overview and metrics docs so the CI configuration stays discoverable. ([Gitea: Git with a cup of tea][5])

---

## 9. Licensing & reciprocity

Stella Ops ships under **AGPL‑3.0‑or‑later** with a strong reciprocity clause: ([Stella Ops][8])

* You may run, study, modify, and redistribute it, including as a hosted service.
* If you run a **modified** version for others over a network, you must make that exact source code available to those users.
* Official containers are signed and include SBOMs and attestations; verify them with Cosign as described on the license/security pages. ([Stella Ops][8])

When you build extensions:

* Keep plug‑ins compatible with AGPL expectations around combined works.
* Don’t embed proprietary logic into the core without checking license implications.

---

## 10. If you just want a “first contribution” recipe

A practical path that follows the guidelines:

1. Clone the main repo; skim **Coding Standards**, **Test Suite Overview**, and the **Dev Guides & Tooling** index. ([Gitea: Git with a cup of tea][4])
2. Get `dotnet`, Docker, Node set up; run `./scripts/dev-test.sh` to make sure your environment is healthy. ([Gitea: Git with a cup of tea][5])
3. Pick a small issue (docs, small refactor, or new test), make changes respecting:

   * 100‑line files,
   * DI patterns,
   * naming & style.
4. Add/adjust tests plus any affected docs or JSON schemas.
5. Run tests + formatting locally, push, and open a PR with a conventional title and a short “how I tested this” note.

If you tell me what you’re planning to work on (plug‑in, policy pack, core feature, or UI), I can turn this into a very concrete checklist tailored to that slice of Stella Ops.

[1]: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/src/commit/08b27b8a266c82960c7653797460e1e1d17ecd45/docs/technical/development/README.md "git.stella-ops.org/README.md at 08b27b8a266c82960c7653797460e1e1d17ecd45 - git.stella-ops.org - Gitea: Git with a cup of tea"
[2]: https://stella-ops.org/docs/14_glossary_of_terms/?utm_source=chatgpt.com "Open • Sovereign • Modular container security - Stella Ops"
[3]: https://stella-ops.org/docs/05_SYSTEM_REQUIREMENTS_SPEC/?utm_source=chatgpt.com "system requirements specification - Stella Ops – Open • Sovereign ..."
[4]: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/src/commit/08b27b8a266c82960c7653797460e1e1d17ecd45/docs/18_CODING_STANDARDS.md "git.stella-ops.org/18_CODING_STANDARDS.md at 08b27b8a266c82960c7653797460e1e1d17ecd45 - git.stella-ops.org - Gitea: Git with a cup of tea"
[5]: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/src/commit/08b27b8a266c82960c7653797460e1e1d17ecd45/docs/19_TEST_SUITE_OVERVIEW.md "git.stella-ops.org/19_TEST_SUITE_OVERVIEW.md at 08b27b8a266c82960c7653797460e1e1d17ecd45 - git.stella-ops.org - Gitea: Git with a cup of tea"
[6]: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/src/commit/08b27b8a266c82960c7653797460e1e1d17ecd45/docs/10_PLUGIN_SDK_GUIDE.md "git.stella-ops.org/10_PLUGIN_SDK_GUIDE.md at 08b27b8a266c82960c7653797460e1e1d17ecd45 - git.stella-ops.org - Gitea: Git with a cup of tea"
[7]: https://stella-ops.org/docs/policy/dsl/index.html "Stella Ops – Signed Reachability · Deterministic Replay · Sovereign Crypto"
[8]: https://stella-ops.org/license/?utm_source=chatgpt.com "AGPL‑3.0‑or‑later - Stella Ops"