235 lines
9.1 KiB
Markdown
235 lines
9.1 KiB
Markdown
# 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 <role>", 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):
|
||
|
||
```md
|
||
# 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.
|
||
```
|