sentryagent-idp/openspec/changes/archive/2026-04-02-engineering-docs/proposal.md at 7441c9f298f1074b870577d41f1966225f0acdbd

Files

SentryAgent.ai Developer f1fbe0e29a chore(openspec): archive all completed changes, sync 14 new specs to library

Archived 4 completed OpenSpec changes (2026-04-02):
- phase-3-enterprise (100/100 tasks) — 6 Phase 3 capabilities synced
- devops-documentation (48/48 tasks) — 3 new + 1 merged capability
- bedroom-developer-docs (33/33 tasks) — 4 new capabilities synced
- engineering-docs (superseded by 2026-03-29 archive) — no tasks

Main spec library grows from 21 → 35 capabilities (+14 new):
federation, multi-tenancy, oidc, soc2, w3c-dids, webhooks,
database, operations, system-overview, api-reference, core-concepts,
developer-guides, quick-start + deployment (merged additive requirements)

Active changes: 0 — project board is clear for Phase 4 planning.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-02 03:50:47 +00:00

3.5 KiB

Raw Blame History

Why

SentryAgent.ai is growing and hiring engineers with BSc Computer Science and one year of industrial experience. There are currently no internal engineering documents that explain how the system works from the top down — new engineers have no structured path from product vision to running code, and no reference for how to contribute correctly. This gap slows onboarding, increases mistakes, and risks divergence from our architecture and standards.

What Changes

New docs/engineering/ directory added to the repository as the canonical engineering knowledge base
Top-down documentation suite covering all layers of the system: company vision → architecture → codebase → services → workflows → operations
Annotated code walkthroughs for the three most critical system flows (token issuance, agent registration, credential rotation)
Development environment setup guide targeting < 30 minutes from clone to running local stack
Engineering workflow guide covering the full OpenSpec → Architect → Developer → QA → merge cycle
Service deep-dive documents for all 8 core services/components
SDK integration guide covering all four language SDKs
Testing strategy and quality gate reference
Deployment and operations reference covering Docker, Terraform, and monitoring

Capabilities

New Capabilities

engineering-overview: Company mission, product vision, system purpose, and how the engineering team operates — the entry point for all new hires
architecture-guide: System architecture including component diagram, data flow diagrams, deployment topology, and technology stack rationale (ADRs)
codebase-structure: Annotated directory map explaining every top-level directory and key file, what lives where and why
service-deep-dives: Per-service documentation for AgentService, OAuth2Service, CredentialService, AuditService, VaultClient, OPA policy engine, Web Dashboard, and Prometheus/Grafana monitoring
code-walkthroughs: Step-by-step annotated traces of the three critical flows: token issuance end-to-end, agent registration end-to-end, credential rotation end-to-end
dev-environment-setup: Local development environment setup — prerequisites, clone, configure, Docker Compose up, smoke test — targeting < 30 minutes
engineering-workflow: How to contribute — OpenSpec spec-first workflow, branching strategy, PR standards, quality gates, and the role of each virtual engineering team member
testing-strategy: Test framework, test types (unit vs integration), coverage gates, how to run tests, and how to write new tests following project conventions
deployment-operations: Docker build and run, Terraform multi-region deployment, environment configuration, Prometheus/Grafana monitoring, and operational runbooks
sdk-guide: Integration guide for Node.js, Python, Go, and Java SDKs — installation, authentication, all major operations, error handling

Modified Capabilities

(none — this change adds documentation only; no existing spec-level behavior changes)

Impact

Repository: New docs/engineering/ directory (~15 documents, ~10,000 lines of markdown)
No code changes: Documentation only — zero impact on src/, tests/, sdk/, or infrastructure
Dependencies: None — no new packages required
APIs: No API changes
Existing docs: docs/developers/ (bedroom developer guide) and docs/devops/ (operations) remain unchanged; this is an additive engineering-internal knowledge base

3.5 KiB Raw Blame History

Why