236 lines
9.0 KiB
Markdown
236 lines
9.0 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 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 <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
|
||
- 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):
|
||
|
||
```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.
|
||
```
|