sentryagent-idp/openspec/changes/archive/2026-03-29-engineering-docs/tasks.md

1. Setup

• 1.1 Create docs/engineering/ directory
• 1.2 Create docs/engineering/README.md index with numbered document list, reading order guidance, and one-line description of each document

2. Company and Product Overview (01-overview.md)

• 2.1 Write company mission and SentryAgent.ai product purpose section
• 2.2 Write AGNTCY alignment explanation — what AGNTCY is, why it matters, what "first-class agent identity" means
• 2.3 Write product features summary table covering all capabilities (agent registry, OAuth 2.0, credentials, audit, SDKs, dashboard, OPA, monitoring)
• 2.4 Write Phase roadmap section (Phase 1 / Phase 2 / Phase 3 scope)
• 2.5 Write Virtual Engineering Team model explanation (CTO → Architect → Developer → QA, Claude as engineering partner)
• 2.6 Write free tier limits table

3. System Architecture (02-architecture.md)

• 3.1 Write component diagram (ASCII or Mermaid) showing all major components and their connections
• 3.2 Write HTTP request lifecycle section — client → router → middleware → controller → service → repository → database → response
• 3.3 Write OAuth 2.0 Client Credentials data flow section
• 3.4 Write multi-region deployment topology section

4. Technology Stack and ADRs (03-tech-stack.md)

• 4.1 Write ADR entry for Node.js 18 — purpose, rationale, alternatives considered
• 4.2 Write ADR entry for TypeScript 5.3 strict mode — purpose, rationale, consequences of violation
• 4.3 Write ADR entry for Express 4.18 — purpose, rationale, alternatives considered
• 4.4 Write ADR entry for PostgreSQL 14 — purpose, what it stores, rationale
• 4.5 Write ADR entry for Redis 7 — purpose, what it stores (vs PostgreSQL), rationale
• 4.6 Write ADR entry for HashiCorp Vault — purpose, opt-in model, rationale
• 4.7 Write ADR entry for OPA — purpose, how it extends OAuth scopes, rationale
• 4.8 Write ADR entry for React 18 + Vite 5 — purpose, rationale
• 4.9 Write ADR entry for Prometheus + Grafana — purpose, rationale
• 4.10 Write ADR entry for Terraform — purpose, multi-region rationale

5. Codebase Structure (04-codebase-structure.md)

• 5.1 Write annotated directory tree covering all top-level directories
• 5.2 Write src/ subdirectory roles section (controllers, services, repositories, middleware, utils, types, routes)
• 5.3 Write "where to add new code" decision guide — mapping feature type to directory
• 5.4 Write key files section (app.ts, server.ts, types/index.ts, utils/errors.ts, docker-compose.yml, tsconfig.json)
• 5.5 Write DRY enforcement section — mapping the single-location principle to the directory structure

6. Service Deep Dives (05-services.md)

• 6.1 Write AgentService deep-dive (purpose, responsibility boundary, public interface, DB schema, error types)
• 6.2 Write OAuth2Service deep-dive (purpose, responsibility boundary, public interface, Redis schema, JWT payload, Vault vs bcrypt path)
• 6.3 Write CredentialService deep-dive (purpose, responsibility boundary, public interface, DB schema, vault_path column explanation)
• 6.4 Write AuditService deep-dive (purpose, responsibility boundary, public interface, DB schema, immutability guarantee, 90-day retention)
• 6.5 Write VaultClient deep-dive (purpose, public methods, opt-in configuration, constant-time comparison rationale)
• 6.6 Write OPA policy engine deep-dive (purpose, policy file locations, how authorization decisions work, how to write and test a new policy)
• 6.7 Write Web Dashboard deep-dive (React structure, authentication flow, main views, local dev instructions)
• 6.8 Write Prometheus/Grafana monitoring deep-dive (metrics endpoint, key metrics, Grafana dashboard, how to add a new metric)

7. Code Walkthroughs (06-walkthroughs.md)

• 7.1 Read source files to identify current line numbers for token issuance flow
• 7.2 Write token issuance walkthrough — POST /oauth2/token → router → middleware → OAuth2Controller → OAuth2Service → CredentialRepository → Vault/bcrypt → Redis → JWT sign → AuditService → 200 response, with file:line references and "why" annotations at each step
• 7.3 Read source files to identify current line numbers for agent registration flow
• 7.4 Write agent registration walkthrough — POST /agents → auth middleware → validation → AgentController → AgentService → validators → AgentRepository → PostgreSQL → AuditService → 201 response, with file:line references and "why" annotations
• 7.5 Read source files to identify current line numbers for credential rotation flow
• 7.6 Write credential rotation walkthrough — POST /agents/:id/credentials/:credId/rotate → auth → CredentialController → CredentialService → revoke old → crypto → Vault/bcrypt → CredentialRepository → token revocation → AuditService → 200 response, with file:line references and "why" annotations
• 7.7 Add "last verified against commit X" header to each walkthrough

8. Development Environment Setup (07-dev-setup.md)

• 8.1 Write prerequisites section (Node.js 18+, Docker Desktop, Git) with install links
• 8.2 Write repository clone and npm install steps
• 8.3 Write .env setup section (copy .env.example, document every variable)
• 8.4 Write Docker Compose startup steps and service health verification
• 8.5 Write database migration steps
• 8.6 Write smoke test section — curl POST /oauth2/token with seed credentials, expected JWT response
• 8.7 Write troubleshooting section (port conflict, migration failure, Node version mismatch, Docker not running, missing .env vars)
• 8.8 Write "running tests locally" section (npm test, npm run test:coverage, npm run test:integration, single file)
• 8.9 Write web dashboard local dev section (cd dashboard, npm install, npm run dev, port confirmation)

9. Engineering Workflow (08-workflow.md)

• 9.1 Write OpenSpec spec-first workflow overview — the full sequence from CEO approval to merged code
• 9.2 Write OpenSpec CLI commands reference (openspec new change, openspec status, openspec instructions, openspec list)
• 9.3 Write branching strategy section (feature/* from develop, PR → develop, develop → main requires approvals)
• 9.4 Write TypeScript and code standards section (strict mode, no any, DRY, SOLID, JSDoc) with enforcement consequences
• 9.5 Write PR checklist section (TypeScript, ESLint, unit tests, coverage, integration tests, spec updated, docs updated)
• 9.6 Write virtual engineering team roles for contributors section
• 9.7 Write commit message conventions section (Conventional Commits — feat, fix, docs, test, chore, refactor with examples)

10. Testing Strategy (09-testing.md)

• 10.1 Write test types and purposes section (unit vs integration — distinction, when to use each)
• 10.2 Write test framework stack section (Jest 29.7, ts-jest, Supertest 6.3 — role of each)
• 10.3 Write coverage gates section (>80% statements, branches, functions, lines — enforcement)
• 10.4 Write "how to run the test suite" section (npm test, test:coverage, test:integration, single file)
• 10.5 Write unit test writing conventions section with complete real example from codebase (mock setup, describe/it structure, error assertion, mock verification)
• 10.6 Write integration test writing conventions section with complete real example (Supertest app boot, seed data, authenticated request, cleanup)
• 10.7 Write OWASP Top 10 security testing reference section relevant to this codebase

11. Deployment and Operations (10-deployment.md)

• 11.1 Write Docker build and run section (multi-stage build explanation, build command, run command with env vars)
• 11.2 Write complete environment variables reference table (all variables, purpose, required/optional, example value)
• 11.3 Write database migrations section (file location, naming convention, run command, writing new migrations)
• 11.4 Write Terraform multi-region deployment section (modules, regions, terraform plan/apply, resources provisioned)
• 11.5 Write Prometheus and Grafana section (/metrics endpoint, key metrics, Grafana access, adding a new metric)
• 11.6 Write operational runbook section (health check, rotate JWT signing key, revoke all tokens for compromised agent, read audit logs for incident)

12. SDK Guide (11-sdk-guide.md)

• 12.1 Write SDK architecture overview (all four SDKs, identical API surface, consistency standard)
• 12.2 Write Node.js SDK section (install, AgentIdPClient, 4 service clients, TokenManager, AgentIdPError, complete working example)
• 12.3 Write Python SDK section (install, sync + async clients, TokenManager variants, AgentIdPError, complete sync and async examples)
• 12.4 Write Go SDK section (go get, AgentIdPClient, goroutine-safe TokenManager, context.Context usage, AgentIdPError, complete example)
• 12.5 Write Java SDK section (Maven/Gradle snippet, builder pattern, sync + CompletableFuture async, TokenManager, AgentIdPException, complete example)
• 12.6 Write SDK contribution guide (step-by-step checklist for adding a new endpoint to all four SDKs)

13. Final Review and Commit

• 13.1 Review all documents for cross-link accuracy (internal links between documents resolve correctly)
• 13.2 Verify all code examples are complete and runnable (no ellipses, no placeholders)
• 13.3 Verify file:line references in walkthroughs against current source
• 13.4 Verify README.md index links to all 11 documents correctly
• 13.5 Commit docs/engineering/ to develop with message docs: engineering knowledge base for new hires