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 normalization (mandatory)

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
• Normalize sprint naming/template when inconsistent (record in Execution Log)
• Move completed sprints to docs-archived/implplan/

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 when 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.