vijay_admin/sentryagent-idp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(governance): add CTO session completion protocol, TBC charter, and process governance OpenSpec change

Browse Source 
- CLAUDE.md + README.md: new CTO Session Completion Protocol (authorized/done vocabulary, end-of-session summary requirement)
- docs/engineering/08-workflow.md: Section 8 — CTO Session Completion Protocol
- scripts/start-cto.sh: startup protocol updated to read PRD.md first
- openspec/changes/process-governance-handoff-gap/: full OpenSpec change record (proposal, design, specs, tasks)
- TBC/charter.md: Technical & Business Consultant charter
- TBC/minutes/TBC-MIN-001-2026-04-07.md: inaugural TBC meeting minutes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
2026-04-07 08:41:12 +00:00
parent 7441c9f298
commit 4e3b989629
12 changed files with 539 additions and 912 deletions
Download Patch File Download Diff File Expand all files Collapse all files

947
README.md
View File

@@ -6,9 +6,11 @@
**Git Repository**: https://git.sentryagent.ai/
**AI Partner**: Anthropic (Claude — All Development, Implementation & Deployment)
**Standards**: AGNTCY (Linux Foundation), OpenAPI 3.0, OAuth 2.0, OIDC
**Document Role**: Product Requirements Document (PRD) — this file is the single source of truth for all product requirements, scope, and standards
**Document Role**: Project orientation, team charter, and Claude session protocol
**Last Updated**: 2026-03-28
**Status**: ? Active — Phase 1 MVP
**Status**: ✅ Active — Phase 1 MVP
> **Product Requirements**: All scope, standards, and technical requirements are in **[PRD.md](./PRD.md)**
---
@@ -45,14 +47,15 @@ development, implementation, and deployment activities.
When a new Claude session is started, Claude **MUST**:
1. **Read this README.md** in full before any action
2. **Adopt the Virtual Engineering Team roles** as defined in Section 4
3. **Enforce all standards** defined in Section 6 without exception
4. **Resume from last known state** (check git.sentryagent.ai for latest commits)
5. **Report status** to CEO before proceeding
6. **Never deviate** from the technology stack defined in Section 7
7. **Never skip** OpenSpec documentation for any new endpoint or service
8. **Always provide complete files** — no partial code, no placeholders
1. **Read [PRD.md](./PRD.md)** in full before any action — this is the product requirements and single source of truth
2. **Read this README.md** for team charter and session protocol
3. **Adopt the Virtual Engineering Team roles** as defined in Section 4
4. **Enforce all standards** defined in PRD.md Section 6 without exception
5. **Resume from last known state** (check git.sentryagent.ai for latest commits)
6. **Report status** to CEO before proceeding
7. **Never deviate** from the technology stack defined in PRD.md Section 7
8. **Never skip** OpenSpec documentation for any new endpoint or service
9. **Always provide complete files** — no partial code, no placeholders
### 2.3 Claude Communication Protocol
@@ -75,12 +78,12 @@ A **free, open-source Agent Identity Provider** that provides:
| Feature | Description | AGNTCY Alignment |
|---------|-------------|-----------------|
| **Agent Registry** | Unique, immutable agent IDs | ? First-class non-human identity |
| **Authentication** | OAuth 2.0 Client Credentials | ? Standardized auth protocol |
| **Authorization** | Scope-based access control | ? Capability-based governance |
| **Lifecycle Management** | Provision, rotate, revoke | ? Full agent lifecycle |
| **Audit Logs** | Immutable, compliance-ready | ? Accountability & governance |
| **Developer SDK** | Node.js (Phase 1) | ? Developer-first experience |
| **Agent Registry** | Unique, immutable agent IDs | ✅ First-class non-human identity |
| **Authentication** | OAuth 2.0 Client Credentials | ✅ Standardized auth protocol |
| **Authorization** | Scope-based access control | ✅ Capability-based governance |
| **Lifecycle Management** | Provision, rotate, revoke | ✅ Full agent lifecycle |
| **Audit Logs** | Immutable, compliance-ready | ✅ Accountability & governance |
| **Developer SDK** | Node.js (Phase 1) | ✅ Developer-first experience |
### 3.2 Target Users
@@ -141,17 +144,27 @@ CEO (Human — SentryAgent.ai Founder)
- Coordinate Virtual Architect, Principal Developer, and QA Engineer
- Report weekly progress to CEO
- Escalate scope changes and blockers to CEO immediately
- **Post a completion confirmation to `#vpe-cto-approvals` after every CEO-authorized action** (include outcome + commit hash)
- **Post an end-of-session summary before closing** any session with completed, pending, or in-progress work
**Claude Session Startup (CTO Role)**:
```
1. Read README.md (this file) in full
2. Check git.sentryagent.ai for latest commits
3. Identify current phase and sprint
4. Report status to CEO
5. Confirm today's priorities
6. Begin work
1. Read PRD.md in full
2. Read README.md (this file) for team charter
3. Check git.sentryagent.ai for latest commits
4. Identify current phase and sprint
5. Report status to CEO
6. Confirm today's priorities
7. Begin work
8. Before closing: post end-of-session summary to #vpe-cto-approvals
(Completed / Pending — authorized but not executed / Requires CEO action)
```
**Session Completion Protocol**:
- "Authorized" = CEO approved. Action not yet executed.
- "Committed / Completed / Deployed" = Action executed with evidence (commit hash, test results).
- Never close a session with an authorized-but-unexecuted action without noting it in the end-of-session summary.
### 4.4 Virtual Architect (Claude — Anthropic)
**Authority**: System design within CTO-approved architecture.
@@ -218,892 +231,8 @@ CEO (Human — SentryAgent.ai Founder)
---
## 5. Project Scope
## 5. Product Requirements
### 5.1 Phase 1: MVP (Weeks 1–8)
All product requirements, scope, engineering standards, technology stack, quality gates, and success metrics are defined in the standalone PRD:
**Objective**: Prove the concept. Ship a production-ready AgentIdP.
#### In Scope ?
| Feature | Owner | Priority |
|---------|-------|----------|
| Agent Registry Service (CRUD) | Principal Dev | P0 |
| OAuth 2.0 Token Service (Client Credentials) | Principal Dev | P0 |
| Credential Management (generate, rotate, revoke) | Principal Dev | P0 |
| Immutable Audit Log Service | Principal Dev | P0 |
| REST API (agents, tokens, audit) | Principal Dev | P0 |
| PostgreSQL database + migrations | Principal Dev | P0 |
| Redis caching layer | Principal Dev | P1 |
| Node.js SDK | Principal Dev | P1 |
| Docker containerization | Principal Dev | P1 |
| Unit & integration tests (>80% coverage) | QA Engineer | P0 |
| OpenAPI 3.0 documentation | Architect | P0 |
| Docker Compose (local dev) | Principal Dev | P1 |
| Deployment guide | Architect | P1 |
| AGNTCY alignment documentation | Architect | P1 |
#### Out of Scope ? (Phase 2+)
| Feature | Phase |
|---------|-------|
| HashiCorp Vault integration | Phase 2 |
| Multi-region deployment | Phase 2 |
| Advanced policy engine (OPA) | Phase 2 |
| Web dashboard UI | Phase 2 |
| Python/Go/Java/Rust SDKs | Phase 2 |
| Prometheus + Grafana monitoring | Phase 2 |
| AGNTCY federation support | Phase 3 |
| W3C DID support | Phase 3 |
| Agent marketplace | Phase 3 |
| SOC 2 certification | Phase 3 |
### 5.2 Phase 2: Production-Ready (Weeks 9–20)
- HashiCorp Vault for secret management
- Multi-language SDKs (Python, Go, Java)
- Advanced policy engine (OPA integration)
- Web dashboard UI (React + TypeScript)
- Prometheus + Grafana monitoring
- Multi-region deployment (US, EU, APAC)
- SOC 2 Type II certification process
### 5.3 Phase 3: Ecosystem & Standards (Weeks 21–36)
- AGNTCY federation support
- W3C Decentralized Identifiers (DIDs)
- Agent marketplace
- Advanced compliance reporting
- Enterprise tier features
---
## 6. Engineering Standards (Non-Negotiable)
### 6.1 DRY — Don't Repeat Yourself
**Rule**: Zero code duplication. Every piece of logic exists in exactly one place.
**Implementation**:
| Pattern | Location | Purpose |
|---------|----------|---------|
| Type definitions | `src/types/index.ts` | Single source of truth |
| Crypto utilities | `src/utils/crypto.ts` | All crypto operations |
| JWT utilities | `src/utils/jwt.ts` | All JWT operations |
| Validation logic | `src/utils/validators.ts` | All input validation |
| Error classes | `src/utils/errors.ts` | All custom errors |
| DB queries | `src/services/` | All database access |
| HTTP middleware | `src/middleware/` | All cross-cutting concerns |
**Enforcement**:
- Virtual CTO reviews every PR for duplication
- ESLint rules flag repeated patterns
- No copy-paste code — ever
### 6.2 SOLID Principles
**S — Single Responsibility**:
- `AgentService`: Agent CRUD only — nothing else
- `OAuth2Service`: Token issuance only — nothing else
- `CredentialService`: Credential management only — nothing else
- `AuditService`: Audit logging only — nothing else
**O — Open/Closed**:
- All services implement interfaces
- New features extend, never modify existing code
- Plugin architecture for credential backends
**L — Liskov Substitution**:
- All service implementations are interchangeable
- Consistent error handling across all services
- Uniform response shapes across all endpoints
**I — Interface Segregation**:
- Separate read/write interfaces where applicable
- Minimal, focused interfaces — no fat interfaces
- Controllers depend on service interfaces, not implementations
**D — Dependency Inversion**:
- All dependencies injected via constructor
- Services depend on abstractions (interfaces)
- No direct instantiation of dependencies in business logic
### 6.3 OpenSpec Standards (Mandatory)
**Rule**: Every API endpoint MUST have an OpenAPI 3.0 specification
BEFORE implementation begins. No exceptions.
**Process**:
```
1. Virtual Architect writes OpenAPI spec
2. CEO reviews and approves
3. Virtual Principal Developer implements
4. Virtual QA Engineer verifies spec matches implementation
5. Swagger UI auto-generated from spec
```
**OpenAPI Spec Location**: `docs/openapi.yaml`
**Required for every endpoint**:
- Summary and description
- Request body schema (with validation rules)
- Response schemas (all status codes)
- Error response schemas
- Authentication requirements
- Example requests and responses
### 6.4 TypeScript Strict Mode (Mandatory)
**Rule**: TypeScript strict mode is always enabled. No `any` types. Ever.
```json
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictBindCallApply": true,
"strictPropertyInitialization": true,
"noImplicitThis": true,
"alwaysStrict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true
}
}
```
### 6.5 Code Documentation Standards
**JSDoc required for**:
- All public classes
- All public methods
- All interfaces
- All complex logic blocks
**Example**:
```typescript
/**
* Creates a new AI agent identity in the SentryAgent.ai registry.
* Assigns a unique immutable ID and provisions credentials.
*
* @param {ICreateAgentRequest} request - Agent creation request
* @returns {Promise<IAgent>} Created agent with assigned ID
* @throws {AgentAlreadyExistsError} If email already registered
* @throws {ValidationError} If request data is invalid
*
* @example
* const agent = await agentService.createAgent({
* email: 'screener-001@sentryagent.ai',
* agentType: 'screener',
* version: 'v1.0.0',
* capabilities: ['resume:read'],
* owner: 'helloworld-team',
* deploymentEnv: 'production'
* });
*/
async createAgent(request: ICreateAgentRequest): Promise<IAgent>
```
### 6.6 Error Handling Standards
**Rule**: All errors are explicit, typed, and handled. No silent failures.
```typescript
// Custom error hierarchy
class SentryAgentError extends Error {}
class ValidationError extends SentryAgentError {}
class AgentNotFoundError extends SentryAgentError {}
class AgentAlreadyExistsError extends SentryAgentError {}
class CredentialError extends SentryAgentError {}
class AuthenticationError extends SentryAgentError {}
class AuthorizationError extends SentryAgentError {}
class RateLimitError extends SentryAgentError {}
```
**All errors include**:
- Error code (machine-readable)
- Error message (human-readable)
- HTTP status code
- Stack trace (development only)
### 6.7 Git Standards
**Repository**: `https://git.sentryagent.ai/`
**Branch Strategy** (Git Flow):
- `main`: Production-ready code only
- `develop`: Integration branch for Phase work
- `feature/*`: Individual features (e.g., `feature/agent-registry`)
- `bugfix/*`: Bug fixes (e.g., `bugfix/token-validation`)
- `release/*`: Release preparation (e.g., `release/v1.0.0`)
**Commit Standards** (Conventional Commits):
```
feat(agent): implement agent registry CRUD
fix(oauth2): correct token expiration calculation
docs(api): update OpenAPI spec for /agents endpoint
test(credential): add rotation edge case tests
chore(deps): upgrade TypeScript to 5.3.3
```
**Pull Request Standards**:
- [ ] Feature branch created from `develop`
- [ ] OpenAPI spec updated (if API change)
- [ ] Unit tests added (>80% coverage)
- [ ] Integration tests added
- [ ] JSDoc comments added
- [ ] No code duplication (DRY check)
- [ ] SOLID principles followed
- [ ] Performance acceptable (<200ms)
- [ ] Security review passed
- [ ] Virtual CTO approval required
- [ ] Virtual QA Engineer sign-off required
- [ ] Merge to `develop` (squash commits)
- [ ] Delete feature branch
---
## 7. Technology Stack
### 7.1 Runtime & Language
| Component | Version | Rationale |
|-----------|---------|-----------|
| Node.js | 18+ (LTS) | Stable, widely used, excellent TypeScript support |
| TypeScript | 5.3+ | Strict mode, type safety, no `any` types |
| npm | 9+ | Standard package manager |
### 7.2 Web Framework & Middleware
| Component | Version | Purpose |
|-----------|---------|---------|
| Express.js | 4.18+ | Lightweight, battle-tested web framework |
| helmet | 7.1+ | Security headers (HSTS, CSP, etc.) |
| cors | 2.8+ | CORS handling |
| morgan | 1.10+ | HTTP request logging |
| pino | 8.17+ | Structured JSON logging |
| pino-http | 8.6+ | Express integration for Pino |
### 7.3 Database & Caching
| Component | Version | Purpose |
|-----------|---------|---------|
| PostgreSQL | 14+ | Primary database (ACID, reliability) |
| pg | 8.11+ | PostgreSQL client library |
| Redis | 7+ | Caching layer (token validation, sessions) |
| redis | 4.6+ | Redis client library |
### 7.4 Authentication & Security
| Component | Version | Purpose |
|-----------|---------|---------|
| jsonwebtoken | 9.1+ | JWT signing and verification |
| bcryptjs | 2.4+ | Password/secret hashing (10 salt rounds) |
| uuid | 9.0+ | Unique ID generation |
| crypto (Node.js built-in) | N/A | Cryptographic operations |
| dotenv | 16.3+ | Environment variable management |
### 7.5 Testing
| Component | Version | Purpose |
|-----------|---------|---------|
| Jest | 29.7+ | Unit and integration testing |
| @types/jest | 29.5+ | TypeScript types for Jest |
| ts-jest | 29.1+ | Jest + TypeScript integration |
| supertest | 6.3+ | HTTP endpoint testing |
| @testing-library/node | Latest | Node.js testing utilities |
### 7.6 Code Quality & Linting
| Component | Version | Purpose |
|-----------|---------|---------|
| ESLint | 8.56+ | Code linting and style |
| @typescript-eslint/parser | 6.17+ | TypeScript parsing for ESLint |
| @typescript-eslint/eslint-plugin | 6.17+ | TypeScript-specific rules |
| Prettier | 3.1+ | Code formatting |
### 7.7 Documentation & API
| Component | Version | Purpose |
|-----------|---------|---------|
| swagger-ui-express | 4.6+ | Interactive API documentation |
| joi | 17.11+ | Schema validation |
### 7.8 Deployment & Containerization
| Component | Version | Purpose |
|-----------|---------|---------|
| Docker | 24+ | Container runtime |
| Docker Compose | 2.20+ | Local development orchestration |
| Alpine Linux | 3.18 | Minimal base image |
### 7.9 Validation & Schema
| Component | Version | Purpose |
|-----------|---------|---------|
| Joi | 17.11+ | Request/response schema validation |
---
## 8. Project Structure (DRY Compliance)
```
sentryagent-idp/
+-- src/
¦ +-- config/
¦ ¦ +-- env.ts # Environment variables
¦ ¦ +-- database.ts # PostgreSQL connection pool
¦ ¦ +-- redis.ts # Redis client
¦ ¦ +-- logger.ts # Pino logger configuration
¦ ¦
¦ +-- types/
¦ ¦ +-- index.ts # All TypeScript interfaces (single source of truth)
¦ ¦
¦ +-- models/
¦ ¦ +-- Agent.ts # Agent entity
¦ ¦ +-- Credential.ts # Credential entity
¦ ¦ +-- AuditLog.ts # Audit log entity
¦ ¦ +-- Token.ts # Token entity
¦ ¦
¦ +-- services/
¦ ¦ +-- AgentService.ts # Agent CRUD (no duplication)
¦ ¦ +-- OAuth2Service.ts # Token issuance (no duplication)
¦ ¦ +-- CredentialService.ts # Credential management (no duplication)
¦ ¦ +-- AuditService.ts # Audit logging (no duplication)
¦ ¦ +-- TokenService.ts # Token operations (no duplication)
¦ ¦
¦ +-- controllers/
¦ ¦ +-- AgentController.ts # Agent endpoints
¦ ¦ +-- OAuth2Controller.ts # OAuth 2.0 endpoints
¦ ¦ +-- HealthController.ts # Health check endpoint
¦ ¦
¦ +-- middleware/
¦ ¦ +-- authentication.ts # Bearer token validation
¦ ¦ +-- authorization.ts # Scope-based access control
¦ ¦ +-- errorHandler.ts # Global error handling
¦ ¦ +-- logging.ts # Request/response logging
¦ ¦ +-- validation.ts # Request validation
¦ ¦ +-- rateLimit.ts # Rate limiting
¦ ¦
¦ +-- utils/
¦ ¦ +-- crypto.ts # Crypto utilities (hashing, secrets)
¦ ¦ +-- jwt.ts # JWT utilities (sign, verify)
¦ ¦ +-- validators.ts # Input validation (reusable)
¦ ¦ +-- errors.ts # Custom error classes
¦ ¦ +-- helpers.ts # General utilities
¦ ¦
¦ +-- routes/
¦ ¦ +-- agents.ts # Agent routes
¦ ¦ +-- oauth2.ts # OAuth 2.0 routes
¦ ¦ +-- health.ts # Health routes
¦ ¦
¦ +-- migrations/
¦ ¦ +-- 001_create_agents_table.sql
¦ ¦ +-- 002_create_credentials_table.sql
¦ ¦ +-- 003_create_audit_logs_table.sql
¦ ¦
¦ +-- app.ts # Express app setup
¦ +-- server.ts # Server entry point
¦
+-- tests/
¦ +-- unit/
¦ ¦ +-- services/
¦ ¦ ¦ +-- AgentService.test.ts
¦ ¦ ¦ +-- OAuth2Service.test.ts
¦ ¦ ¦ +-- CredentialService.test.ts
¦ ¦ ¦ +-- AuditService.test.ts
¦ ¦ +-- utils/
¦ ¦ +-- crypto.test.ts
¦ ¦ +-- jwt.test.ts
¦ ¦ +-- validators.test.ts
¦ ¦
¦ +-- integration/
¦ ¦ +-- api/
¦ ¦ ¦ +-- agents.test.ts
¦ ¦ ¦ +-- oauth2.test.ts
¦ ¦ ¦ +-- health.test.ts
¦ ¦ +-- database/
¦ ¦ +-- migrations.test.ts
¦ ¦
¦ +-- fixtures/
¦ +-- agents.json
¦ +-- credentials.json
¦ +-- auditLogs.json
¦
+-- docs/
¦ +-- README.md # This file
¦ +-- architecture.md # Architecture Decision Records
¦ +-- openapi.yaml # OpenAPI 3.0 specification
¦ +-- deployment.md # Deployment guide
¦ +-- agntcy-alignment.md # AGNTCY compliance documentation
¦ +-- api-guide.md # API usage guide
¦ +-- contributing.md # Contribution guidelines
¦
+-- docker-compose.yml # Local development stack
+-- Dockerfile # Production image
+-- .dockerignore # Docker build exclusions
+-- .env.example # Environment template
+-- .env.test # Test environment
+-- .gitignore # Git exclusions
+-- .eslintrc.js # ESLint configuration
+-- .prettierrc.json # Prettier configuration
+-- tsconfig.json # TypeScript configuration
+-- jest.config.js # Jest configuration
+-- package.json # Dependencies and scripts
+-- package-lock.json # Locked dependencies
+-- CHANGELOG.md # Version history
+-- LICENSE # Open source license (MIT)
+-- README.md # Project README
```
**DRY Principles Applied**:
- ? Single `types/index.ts` for all interfaces (no duplication)
- ? Shared `utils/` for crypto, JWT, validation (no duplication)
- ? Centralized error handling in middleware (no duplication)
- ? Reusable service layer (no business logic in controllers)
- ? Configuration centralized in `config/` (no duplication)
- ? Database queries isolated in services (no duplication)
---
## 9. Development Workflow
### 9.1 Feature Development Process
**Step 1: Specification (Virtual Architect)**
- Write Architecture Decision Record (ADR)
- Define OpenAPI 3.0 specification
- Specify database schema
- List test cases
- CEO approves specification
**Step 2: Implementation (Virtual Principal Developer)**
- Create feature branch: `git checkout -b feature/agent-registry`
- Implement per specification
- Follow DRY and SOLID principles
- Add JSDoc comments
- Create unit tests (>80% coverage)
- Push to `git.sentryagent.ai`
**Step 3: Code Review (Virtual CTO)**
- Check compliance with standards
- Verify DRY principles
- Review test coverage
- Verify SOLID principles
- Approve or request changes
**Step 4: Testing (Virtual QA Engineer)**
- Run integration tests
- Test edge cases
- Verify AGNTCY alignment
- Verify OpenAPI spec matches implementation
- Sign off on quality
**Step 5: Deployment (Virtual CTO)**
- Merge to `develop` branch (squash commits)
- Delete feature branch
- Deploy to staging
- Deploy to production
### 9.2 Git Workflow
```bash
# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/agent-registry
# Make changes, commit with conventional commits
git add src/services/AgentService.ts
git commit -m "feat(agent): implement agent registry CRUD"
# Push to repository
git push origin feature/agent-registry
# Create pull request on git.sentryagent.ai
# Virtual CTO reviews and approves
# Virtual QA Engineer signs off
# Merge to develop (squash commits)
git checkout develop
git pull origin develop
git merge --squash feature/agent-registry
git commit -m "feat(agent): implement agent registry CRUD"
git push origin develop
# Delete feature branch
git branch -d feature/agent-registry
git push origin --delete feature/agent-registry
```
### 9.3 Code Review Checklist
Before any code is merged to `develop`, verify:
- [ ] TypeScript strict mode: `tsc --strict` passes
- [ ] No `any` types used
- [ ] No code duplication (DRY check)
- [ ] SOLID principles applied
- [ ] Unit tests included (>80% coverage)
- [ ] Integration tests included
- [ ] JSDoc comments present
- [ ] Error handling implemented
- [ ] No OWASP Top 10 vulnerabilities
- [ ] Performance acceptable (<200ms)
- [ ] Database migrations included
- [ ] OpenAPI specification updated
- [ ] Conventional commit message used
- [ ] Virtual CTO approval obtained
- [ ] Virtual QA Engineer sign-off obtained
---
## 10. OpenSpec Compliance
### 10.1 OpenAPI 3.0 Specification
**Location**: `docs/openapi.yaml`
**Mandatory for every endpoint**:
- Summary and description
- Request body schema (with validation rules)
- Response schemas (all status codes)
- Error response schemas
- Authentication requirements
- Example requests and responses
**Example OpenAPI Spec**:
```yaml
openapi: 3.0.0
info:
title: SentryAgent.ai Agent Identity Provider
version: 1.0.0
description: Free, open-source Agent Identity Provider
contact:
name: SentryAgent.ai
url: https://sentryagent.ai
servers:
- url: https://api.sentryagent.ai
description: Production
- url: http://localhost:3000
description: Development
paths:
/agents:
post:
summary: Create a new AI agent
operationId: createAgent
tags:
- Agents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentRequest'
responses:
'201':
description: Agent created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Agent already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Agent:
type: object
required:
- id
- email
- agentType
- version
- capabilities
- owner
- deploymentEnv
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique agent identifier
email:
type: string
format: email
description: Agent email (agent-type-001@sentryagent.ai)
agentType:
type: string
description: AGNTCY agent type
version:
type: string
description: Semantic version
capabilities:
type: array
items:
type: string
description: Agent capabilities
owner:
type: string
description: Developer or team name
deploymentEnv:
type: string
enum: [development, staging, production]
status:
type: string
enum: [active, suspended, revoked, archived]
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Error code
message:
type: string
description: Error message
details:
type: object
description: Additional error details
```
### 10.2 AGNTCY Alignment
**Agent Identity Model** (AGNTCY-compliant):
```typescript
interface IAgent {
id: string; // Unique agent ID (UUID) — immutable
email: string; // agent-type-001@sentryagent.ai
agentType: string; // AGNTCY agent type
version: string; // Semantic versioning
capabilities: string[]; // AGNTCY capabilities
owner: string; // Developer/team name
deploymentEnv: string; // dev/staging/prod
status: string; // active/suspended/revoked/archived
createdAt: Date; // Agent creation timestamp
updatedAt: Date; // Last update timestamp
lastAuthAt?: Date; // Last authentication timestamp
metadata?: Record<string, unknown>; // AGNTCY metadata
}
```
**Audit Compliance**:
- ? Immutable audit logs (no deletion, no modification)
- ? All agent actions logged (creation, auth, revocation)
- ? Timestamps in ISO 8601 format
- ? Tamper-proof storage (PostgreSQL with constraints)
- ? Retention policy (90 days free tier, configurable)
**Policy Enforcement**:
- ? Least privilege by default
- ? Capability-based access control
- ? Revocation at scale
- ? Credential rotation on schedule
---
## 11. Quality Gates & Metrics
### 11.1 Code Quality Standards
| Metric | Target | Tool | Enforcement |
|--------|--------|------|-------------|
| Test Coverage | >80% | Jest/nyc | Fail PR if <80% |
| TypeScript Strict | 100% | tsc --strict | Fail build if violations |
| Linting | 0 errors | ESLint | Fail PR if errors |
| Code Duplication | <5% | Manual review | CTO rejects if >5% |
| Security Scan | 0 high/critical | npm audit | Fail build if vulnerabilities |
### 11.2 Performance Standards
| Metric | Target | Measurement | Enforcement |
|--------|--------|-------------|-------------|
| Token Issuance | <100ms | Benchmark test | Fail if >100ms |
| API Response | <200ms | Integration test | Fail if >200ms |
| Database Query | <50ms | Query profiling | Fail if >50ms |
| Cache Hit Rate | >90% | Redis monitoring | Monitor weekly |
### 11.3 Reliability Standards
| Metric | Target | Measurement |
|--------|--------|-------------|
| Uptime | 99.5% (Phase 2) | Monitoring dashboard |
| Error Rate | <0.1% | Error tracking |
| Recovery Time | <5 minutes | Runbook testing |
---
## 12. Deployment & Operations
### 12.1 Local Development Setup
```bash
# Clone repository
git clone https://git.sentryagent.ai/sentryagent-idp.git
cd sentryagent-idp
# Install dependencies
npm install
# Setup environment
cp .env.example .env
# Edit .env with local values
# Start services (PostgreSQL, Redis)
docker-compose up -d
# Run database migrations
npm run migrate
# Start development server
npm run dev
# Server runs on http://localhost:3000
# Swagger UI: http://localhost:3000/api-docs
```
### 12.2 Docker Deployment
```bash
# Build image
docker build -t sentryagent-idp:1.0.0 .
# Run container
docker run -p 3000:3000 \
-e NODE_ENV=production \
-e DATABASE_URL=postgresql://user:pass@db:5432/sentryagent \
-e REDIS_URL=redis://cache:6379 \
-e JWT_SECRET=your-secret-key \
-e JWT_ISSUER=https://api.sentryagent.ai \
sentryagent-idp:1.0.0
```
### 12.3 Docker Compose (Local Development)
```yaml
version: '3.9'
services:
app:
build: .
ports:
- "3000:3000"
environment:
NODE_ENV: development
DATABASE_URL: postgresql://sentryagent:sentryagent@postgres:5432/sentryagent_idp
REDIS_URL: redis://redis:6379
JWT_SECRET: dev-secret-key-change-in-production
depends_on:
- postgres
- redis
volumes:
- ./src:/app/src
command: npm run dev
postgres:
image: postgres:15-alpine
environment:
POSTGRES_USER: sentryagent
POSTGRES_PASSWORD: sentryagent
POSTGRES_DB: sentryagent_idp
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:
```
### 12.4 Production Deployment Checklist
- [ ] Environment variables configured securely
- [ ] Database backups enabled (daily)
- [ ] SSL/TLS certificates installed
- [ ] Rate limiting configured
- [ ] Monitoring alerts set up
- [ ] Logging aggregation enabled
- [ ] Disaster recovery plan documented
- [ ] Security audit completed
- [ ] Load balancer configured
- [ ] CDN configured (if applicable)
- [ ] Health check endpoints verified
- [ ] Rollback procedure documented
---
## 13. Risk Management
### 13.1 Technical Risks
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|-----------|
| Database performance degradation | Medium | High | Connection pooling, caching, indexing |
| Token validation latency | Low | Medium | Redis cache, JWT caching |
| Credential compromise | Low | Critical | Encryption, audit logs, rotation, monitoring |
| API rate limiting bypass | Low | Medium | Token bucket algorithm, monitoring |
| Data loss | Very Low | Critical | Daily backups, replication, disaster recovery |
### 13.2 Mitigation Strategies
- **Code Review**: Catch issues early (Virtual CTO)
- **Testing**: >80% coverage (Virtual QA Engineer)
- **Monitoring**: Real-time alerts (Phase 2)
- **Documentation**: Clear runbooks for operations
- **Backups**: Daily database snapshots
- **Security**: Regular audits and penetration testing
---
## 14. Success Metrics & KPIs
### 14.1 Phase 1 MVP Success Criteria
**Technical**:
- ? All features implemented and tested
- ? >80% test coverage
- ? Zero critical security issues
- ? API response time <200ms
- ? Token issuance <100ms
- ? AGNTCY compliance verified
**Adoption**:
- ? 50+ agents registered in first month
- ? 10+ developers using the service
- ? Positive feedback on ease of use
-
> **[PRD.md](./PRD.md)** — Product Requirements Document (single source of truth for all requirements)