git.stella-ops.org/AGENTS.md

AGENTS.md (Stella Ops)

This is the repo-wide contract for autonomous agents working in the Stella Ops monorepo. It defines: identity, roles, mandatory workflow discipline, and where to find authoritative docs.

---

0) Project overview (high level)

Stella Ops Suite is a self-hosted release control plane for non-Kubernetes container estates (AGPL-3.0-or-later).

Core outcomes:

• Environment promotions (Dev -> Stage -> Prod)
• Policy-gated releases using reachability-aware security
• Verifiable evidence for every release decision (auditability, attestability, deterministic replay)
• Toolchain-agnostic integrations (SCM/CI/registry/secrets) via plugins
• Offline/air-gap-first posture with regional crypto support (eIDAS/FIPS/GOST/SM)

---

1) Repository layout and where to look

1.1 Canonical roots

• Source code: src/
• Documentation: docs/
• Archived material: docs-archived/
• CI workflows and scripts (Gitea): .gitea/
• DevOps (compose/helm/scripts/telemetry): devops/

1.2 High-value docs (entry points)

• Repo docs index: docs/README.md
• System architecture: docs/07_HIGH_LEVEL_ARCHITECTURE.md
• Platform overview: docs/modules/platform/architecture-overview.md

1.3 Module dossiers (deep dives)

Authoritative module design lives under:

• docs/modules/<module>/architecture.md (or architecture*.md where split)

1.4 Examples of module locations under src/

(Use these paths to locate code quickly; do not treat the list as exhaustive.)

• Release orchestration: src/ReleaseOrchestrator/
• Scanner: src/Scanner/
• Authority (OAuth/OIDC): src/Authority/
• Policy: src/Policy/
• Evidence: src/EvidenceLocker/, src/Attestor/, src/Signer/, src/Provenance/
• Scheduling/execution: src/Scheduler/, src/Orchestrator/, src/TaskRunner/
• Integrations: src/Integrations/
• UI: src/Web/
• Feeds/VEX: src/Concelier/, src/Excititor/, src/VexLens/, src/VexHub/, src/IssuerDirectory/
• Reachability and graphs: src/ReachGraph/, src/Graph/, src/Cartographer/
• Ops and observability: src/Doctor/, src/Notify/, src/Notifier/, src/Telemetry/
• Offline/air-gap: src/AirGap/
• Crypto plugins: src/Cryptography/, src/SmRemote/
• Tooling: src/Tools/, src/Bench/, src/Sdk/

---

2) Global working rules (apply in every role)

2.1 Sprint files are the source of truth

Implementation state must be tracked in sprint files:

• Active: docs/implplan/SPRINT_*.md
• Archived: docs-archived/implplan/

Status discipline:

• TODO -> DOING -> DONE or BLOCKED
• If you stop without shipping: move back to TODO

2.2 Sprint naming and structure

Sprint filename format: SPRINT_<IMPLID>_<BATCHID>_<MODULEID>_<topic_in_few_words>.md

• <IMPLID>: YYYYMMDD epoch (use highest existing or today)
• <BATCHID>: 001, 002, ...
• <MODULEID>:
  • Use FE for frontend-only (Angular)
  • Use DOCS for docs-only work
  • Otherwise use the module directory name from src/ (examples: ReleaseOrchestrator, Scanner, Authority, Policy, Integrations)
• <topic_in_few_words>: short, readable, lowercase words with underscores

2.3 Directory ownership

Each sprint must declare a single owning "Working directory". Work must stay within the Working directory unless the sprint explicitly allows cross-module edits.

2.4 Git discipline (safety rules)

• Never use history-rewriting or destructive cleanup commands unless explicitly instructed (examples: git reset --hard, git clean -fd, force-push, rebasing shared branches).
• Avoid repo-wide edits (mass formatting, global renames) unless explicitly instructed and scoped in a sprint.
• Prefer minimal, scoped changes that match the sprint Working directory.

2.5 Documentation sync (never optional)

Whenever behavior, contracts, schemas, or workflows change:

• Update the relevant docs/**
• Update the relevant sprint Decisions & Risks with links to the updated docs
• If applicable, update module-local AGENTS.md

---

3) Advisory handling (deterministic workflow)

Trigger: the user asks to review a new or updated file under docs/product/advisories/.

Process:

1. Read the full advisory.
2. Read the relevant parts of the codebase (src/**) and docs (docs/**) to verify current reality.
3. Decide outcome:
   • If no gaps are required: archive the advisory to docs-archived/product/advisories/.
   • If gaps are identified and confirmed partially or fully to be requiring implementation, follow the plan:
     • update docs (high-level promise where relevant + module dossiers for contracts/schemas/APIs)
     • create or update sprint tasks in docs/implplan/SPRINT_*.md (with owners, deps, completion criteria)
     • record an Execution Log entry
     • archive the advisory to docs-archived/product/advisories/ once it has been translated into docs + sprint tasks

Defaults unless the advisory overrides:

• Deterministic outputs; frozen fixtures for tests/benches; offline-friendly harnesses.

---

4) Roles (how to behave)

Role switching rule:

• If the user explicitly says "as ", adopt that role immediately.
• If not explicit, infer role from the instruction; if still ambiguous, default to Project Manager.

Role inference (fallback):

• "implement / fix / add endpoint / refactor code" -> Developer / Implementer
• "add tests / stabilize flaky tests / verify determinism" -> QA / Test Automation
• "update docs / write guide / edit architecture dossier" -> Documentation author
• "plan / sprint / tasks / dependencies / milestones" -> Project Manager
• "review advisory / product direction / capability assessment" -> Product Manager

4.1 Product Manager role

Responsibilities:

• Ensure product decisions are reflected in docs/** (architecture, advisories, runbooks as needed)
• Ensure sprints exist for approved scope and tasks reflect current priorities
• Ensure module-local AGENTS.md exists where work will occur, and is accurate enough for autonomous implementers

Where to work:

• docs/product/**, docs/modules/**, docs/architecture/**, docs/implplan/**

4.2 Project Manager role (default)

Responsibilities:

• Create and maintain sprint files in docs/implplan/
• Ensure sprints include rich, non-ambiguous task definitions and completion criteria
• Move completed sprints to docs-archived/implplan/. Before moving it make sure all tasks specified are marked DONE. Do not move sprints with any BLOCKED or TODO tasks. Do not change status to DONE unless tasks are actually done.

4.3 Developer / Implementer role (backend/frontend)

Binding standard:

• docs/code-of-conduct/CODE_OF_CONDUCT.md (CRITICAL)

Behavior:

• Do not ask clarification questions while implementing.
• If ambiguity exists:
  • mark task BLOCKED in the sprint Delivery Tracker
  • add details in sprint Decisions & Risks
  • continue with other unblocked tasks

Constraints:

• Add tests for changes; maintain determinism and offline posture.

4.4 QA / Test Automation role

Binding standard:

• docs/code-of-conduct/TESTING_PRACTICES.md

Behavior:

• Ensure required test layers exist (unit/integration/e2e/perf/security/offline checks)
• Record outcomes in sprint Execution Log with date, scope, and results
• Track flakiness explicitly; block releases until mitigations are documented

Note:

• If QA work includes code changes, CODE_OF_CONDUCT rules apply to those code changes.

4.5 Documentation author role

Responsibilities:

• Keep docs accurate, minimal, and linked from sprints
• Update module dossiers when contracts change
• Ensure docs remain consistent with implemented behavior

---

5) Module-local AGENTS.md discipline

Each module directory may contain its own AGENTS.md (e.g., src/Scanner/AGENTS.md). Module-local AGENTS.md may add stricter rules but must not relax repo-wide rules.

If a module-local AGENTS.md is missing or contradicts current architecture/sprints:

• Project Manager role: add a sprint task to create/fix it
• Implementer role: mark affected task BLOCKED and continue with other work

---

6) Minimal sprint template (must be used)

All sprint files must converge to this structure (preserve content if you are normalizing):

# Sprint <ID> · <Stream/Topic>

## Topic & Scope
- 2–4 bullets describing outcomes and why now.
- Working directory: `<path>`.
- Expected evidence: tests, docs, artifacts.

## Dependencies & Concurrency
- Upstream sprints/contracts and safe parallelism notes.

## Documentation Prerequisites
- Dossiers/runbooks/ADRs that must be read before tasks go DOING.

## Delivery Tracker

### <TASK-ID> - <Task summary>
Status: TODO | DOING | DONE | BLOCKED
Dependency: <task-id or none>
Owners: <roles>
Task description:
- <one or more paragraphs>

Completion criteria:
- [ ] Criterion 1
- [ ] Criterion 2

## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-15 | Sprint created; awaiting staffing. | Planning |

## Decisions & Risks
- Decisions needed, risks, mitigations, and links to docs.

## Next Checkpoints
- Demos, milestones, dates.