stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
7cfb683a52ea19cb49686d6e2e95380513708909
git.stella-ops.org/docs/AGENTS.md
StellaOps Bot dfab8a29c3 docs re-org, audit fixes, build fixes
2026-01-05 09:35:33 +02:00

2.3 KiB
Raw Blame History

AGENTS · Documentation Working Directory

Scope & Roles

  • Working directory: docs/ (includes docs/assets/** fixtures and docs/api/console/samples/**).
  • Roles: Documentation author (primary), QA/fixtures reviewer, module SMEs (Console/UI, Advisory AI, Policy/Airgap) for accuracy checks.
  • Only documentation and fixture assets live here; code changes belong to module repos and must be coordinated via the owning sprint.

Required Reading (treat as read before DOING)

  • docs/README.md and docs/ARCHITECTURE_REFERENCE.md.
  • Module dossiers relevant to the document being edited (e.g., docs/modules/advisory-ai/architecture.md, docs/modules/ui/architecture.md, docs/modules/airgap/architecture.md, docs/modules/platform/architecture-overview.md).
  • Active sprint file: docs/implplan/SPRINT_0301_0001_0001_docs_md_i.md (Docs Tasks Md.I).

Working Agreements

  • Determinism: Keep fixtures and captures reproducible. Store payload JSON alongside SVG/PNG captures; record sha256 hashes in the doc and verify with sha256sum before publishing.
  • Offline posture: Use sealed/fixture data only; no external fonts/CDNs or live calls in regeneration scripts. Capture timestamps in UTC.
  • Status discipline: Update task status in the sprint Delivery Tracker (TODO → DOING → DONE/BLOCKED) and log changes in the sprint Execution Log.
  • Cross-links: When documentation applies a design/advisory change, update the relevant module doc and link it from the sprint’s Decisions & Risks.
  • Testing: For regeneration scripts, keep them self-contained (stdlib-only) and record expected hashes so QA can diff outputs deterministically.

Boundaries

  • Do not edit source code outside docs/ without an explicit sprint note.
  • Asset placement: use docs/assets/<area>/ for captures and docs/api/<area>/samples/ for JSON fixtures. Name captures yyyyMMdd-HHmmss-<view>-<build>.<ext> in UTC.

Escalation / Blockers

  • Missing fixtures or conflicting contracts → mark the task BLOCKED in the sprint file, describe the needed artifact or contract in Decisions & Risks, then continue with other unblocked work.
  • If new advisories land, run the advisory-sync workflow: update high-level docs, deep area docs, add sprint tasks, and carry code samples into fixtures/tests immediately.