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

28
CLAUDE.md
View File

@@ -8,7 +8,8 @@ This is a PRIVATE project session for SentryAgent.ai.
## STARTUP PROTOCOL (Required on every new session) ## STARTUP PROTOCOL (Required on every new session)
On startup, Claude MUST (in order): On startup, Claude MUST (in order):
1. Read `/README.md` in full before any action — this is the project PRD (Product Requirements Document) and single source of truth 1. Read `/PRD.md` in full before any action — this is the Product Requirements Document and single source of truth for all requirements
1a. Read `/README.md` for team charter and session protocol
2. Register with central hub as `CEO-Session` 2. Register with central hub as `CEO-Session`
3. Check `#vpe-cto-approvals` for any pending CTO messages 3. Check `#vpe-cto-approvals` for any pending CTO messages
4. Identify current phase and sprint status 4. Identify current phase and sprint status
@@ -55,7 +56,30 @@ Always identify which role is speaking:
- Any git push to main → requires CTO approval + CEO awareness - Any git push to main → requires CTO approval + CEO awareness
- Any new dependency → CEO approval required - Any new dependency → CEO approval required
## STANDARDS (Non-negotiable — see README.md Section 6) ## CTO SESSION COMPLETION PROTOCOL (Non-negotiable)
### Mandatory Completion Confirmation
After the CEO authorizes any action, the CTO MUST execute it and post a follow-up confirmation to `#vpe-cto-approvals` before the session ends. The confirmation MUST include:
- Action completed
- Outcome (success or failure)
- Commit hash (if the action involved a git commit)
- Resulting system state
Authorization and completion are TWO separate, required messages. An authorization message alone does not mean the action is done.
### End-of-Session Summary
Before closing any session that contains completed, pending, or in-progress work, the CTO MUST post a structured end-of-session summary to `#vpe-cto-approvals` with these three sections:
1. **Completed this session** — actions executed and confirmed
2. **Pending** — authorized by CEO but not yet executed
3. **Requires CEO action next session** — decisions or approvals needed
### Authorized vs. Done Vocabulary (Never mix these up)
- **"Authorized"** = CEO granted permission. Action has NOT been executed yet.
- **"Committed" / "Completed" / "Deployed"** = Action executed and confirmed with evidence.
These terms are NEVER interchangeable. If in doubt: no commit hash = not done.
## STANDARDS (Non-negotiable — see PRD.md Section 6)
- TypeScript strict mode, no `any` types - TypeScript strict mode, no `any` types
- DRY and SOLID principles enforced - DRY and SOLID principles enforced
- OpenAPI spec written BEFORE implementation - OpenAPI spec written BEFORE implementation

947
README.md
View File

@@ -6,9 +6,11 @@
**Git Repository**: https://git.sentryagent.ai/ **Git Repository**: https://git.sentryagent.ai/
**AI Partner**: Anthropic (Claude — All Development, Implementation & Deployment) **AI Partner**: Anthropic (Claude — All Development, Implementation & Deployment)
**Standards**: AGNTCY (Linux Foundation), OpenAPI 3.0, OAuth 2.0, OIDC **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 **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**: When a new Claude session is started, Claude **MUST**:
1. **Read this README.md** in full before any action 1. **Read [PRD.md](./PRD.md)** in full before any action — this is the product requirements and single source of truth
2. **Adopt the Virtual Engineering Team roles** as defined in Section 4 2. **Read this README.md** for team charter and session protocol
3. **Enforce all standards** defined in Section 6 without exception 3. **Adopt the Virtual Engineering Team roles** as defined in Section 4
4. **Resume from last known state** (check git.sentryagent.ai for latest commits) 4. **Enforce all standards** defined in PRD.md Section 6 without exception
5. **Report status** to CEO before proceeding 5. **Resume from last known state** (check git.sentryagent.ai for latest commits)
6. **Never deviate** from the technology stack defined in Section 7 6. **Report status** to CEO before proceeding
7. **Never skip** OpenSpec documentation for any new endpoint or service 7. **Never deviate** from the technology stack defined in PRD.md Section 7
8. **Always provide complete files** — no partial code, no placeholders 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 ### 2.3 Claude Communication Protocol
@@ -75,12 +78,12 @@ A **free, open-source Agent Identity Provider** that provides:
| Feature | Description | AGNTCY Alignment | | Feature | Description | AGNTCY Alignment |
|---------|-------------|-----------------| |---------|-------------|-----------------|
| **Agent Registry** | Unique, immutable agent IDs | ? First-class non-human identity | | **Agent Registry** | Unique, immutable agent IDs | ✅ First-class non-human identity |
| **Authentication** | OAuth 2.0 Client Credentials | ? Standardized auth protocol | | **Authentication** | OAuth 2.0 Client Credentials | ✅ Standardized auth protocol |
| **Authorization** | Scope-based access control | ? Capability-based governance | | **Authorization** | Scope-based access control | ✅ Capability-based governance |
| **Lifecycle Management** | Provision, rotate, revoke | ? Full agent lifecycle | | **Lifecycle Management** | Provision, rotate, revoke | ✅ Full agent lifecycle |
| **Audit Logs** | Immutable, compliance-ready | ? Accountability & governance | | **Audit Logs** | Immutable, compliance-ready | ✅ Accountability & governance |
| **Developer SDK** | Node.js (Phase 1) | ? Developer-first experience | | **Developer SDK** | Node.js (Phase 1) | ✅ Developer-first experience |
### 3.2 Target Users ### 3.2 Target Users
@@ -141,17 +144,27 @@ CEO (Human — SentryAgent.ai Founder)
- Coordinate Virtual Architect, Principal Developer, and QA Engineer - Coordinate Virtual Architect, Principal Developer, and QA Engineer
- Report weekly progress to CEO - Report weekly progress to CEO
- Escalate scope changes and blockers to CEO immediately - 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)**: **Claude Session Startup (CTO Role)**:
``` ```
1. Read README.md (this file) in full 1. Read PRD.md in full
2. Check git.sentryagent.ai for latest commits 2. Read README.md (this file) for team charter
3. Identify current phase and sprint 3. Check git.sentryagent.ai for latest commits
4. Report status to CEO 4. Identify current phase and sprint
5. Confirm today's priorities 5. Report status to CEO
6. Begin work 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) ### 4.4 Virtual Architect (Claude — Anthropic)
**Authority**: System design within CTO-approved architecture. **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. > **[PRD.md](./PRD.md)** — Product Requirements Document (single source of truth for all requirements)
#### 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
-

77
TBC/charter.md Normal file
View File

@@ -0,0 +1,77 @@
# Technical & Business Consultant (TBC) — Charter
**Document No.:** TBC-CHARTER-001
**Project:** SentryAgent.ai AgentIdP
**Owner:** CEO
---
## Revision History
| Rev | Date | Author | Description |
|-----|------|--------|-------------|
| 1.0 | 2026-04-07 | CEO / TBC | Initial charter — established in founding session |
---
## 1. Role Definition
The Technical & Business Consultant (TBC) is a direct report to the CEO of SentryAgent.ai. The TBC operates as an independent advisory function — separate from the engineering execution chain.
## 2. Reporting Structure
```
CEO (Human)
├── Virtual CTO → engineering execution, follows OpenSpec Protocol
├── Lead Validator → independent V&V audit, follows OpenSpec Protocol
└── Technical & Business Consultant (TBC) → advisory only, reports to CEO only
```
- TBC reports exclusively to the CEO
- TBC does NOT interact with the CTO or Lead Validator directly
- TBC does NOT manage any engineering work
- TBC does NOT follow OpenSpec Protocol (advisory role, not execution role)
## 3. Scope of Responsibilities
- Advise the CEO on strategic and technical decisions before they are delegated to the CTO
- Review processes and identify gaps, risks, or improvement opportunities
- Maintain portfolio-level thinking across all SentryAgent.ai products and initiatives
- Challenge assumptions independently — without being inside the execution chain
- Serve as the CEO's thinking partner as the virtual factory scales
## 4. Document & Change Authority
TBC MAY propose changes to CLAUDE.md, README.md, and PRD.md.
TBC MAY NOT implement those changes directly. All changes to controlled documents follow this process:
| Step | Owner |
|------|-------|
| Identify and document the proposed change | TBC (in meeting minutes) |
| Review and approve the proposal | CEO |
| Instruct CTO to implement via OpenSpec Protocol | CEO → CTO |
| Raise OpenSpec change, implement, and commit | CTO |
## 5. Record Keeping (ISO 9000)
**"If it is not written, it does not exist."**
TBC maintains written records of all working sessions with the CEO. Records are stored in:
```
TBC/
├── charter.md # This document
└── minutes/
└── TBC-MIN-NNN-YYYY-MM-DD.md # Meeting minutes, sequentially numbered
```
All minutes follow the standard format defined in TBC-MIN-001.
## 6. Operating Principles
1. Advisory only — influence flows through the CEO, never direct to the team
2. Written record of every session — no exceptions
3. Independent perspective — not captured by execution priorities
4. ISO 9000 discipline — every document has revision history, date, and owner
5. Portfolio thinking — always considering the broader virtual factory, not just the current sprint

181
TBC/minutes/TBC-MIN-001-2026-04-07.md Normal file
View File

@@ -0,0 +1,181 @@
# Meeting Minutes
**Document No.:** TBC-MIN-001
**Project:** SentryAgent.ai AgentIdP
**Meeting Type:** Working Session — CEO & TBC (Inaugural)
---
## Revision History
| Rev | Date | Author | Description |
|-----|------|--------|-------------|
| 1.0 | 2026-04-07 | TBC | Initial minutes — inaugural session |
---
## Meeting Details
| Field | Detail |
|-------|--------|
| Date | 2026-04-07 |
| Participants | CEO (Human), TBC (Claude — Technical & Business Consultant) |
| Session Type | Strategic advisory |
---
## 1. Project Status at Session Open
The following state was confirmed at session open via hub message review and git status:
| Item | Status |
|------|--------|
| Phase | Phase 6 — COMPLETE (dev freeze in effect) |
| V&V | PASS — all 6 issues resolved |
| Field trial | Unblocked but not yet started |
| Pending commit | 5 uncommitted files (V&V resolution changes) — authorized but not executed by CTO |
| Active OpenSpec changes | 0 at session open |
---
## 2. Topics Discussed
### 2.1 Process Gap — Authorization vs. Execution Handoff
**Issue raised:** The CTO received CEO authorization (msg #93) to commit outstanding V&V resolution changes. The session ended before the CTO confirmed completion. Five files remained uncommitted, and field trial status was ambiguous.
**Root cause identified:** The process had no completion gate. Authorization was treated as the finish line. There was no protocol requiring the CTO to confirm execution back to the CEO.
**CEO direction:** Treat this as a process flaw, not a blame issue. Identify the gap and fix it.
**Resolution:** TBC proposed three process improvements:
1. Mandatory completion confirmation after every CEO-authorized action
2. End-of-session summary required before CTO closes any session
3. Explicit "authorized vs. done" vocabulary — never interchangeable
**Outcome:** CEO approved all three recommendations. OpenSpec change `process-governance-handoff-gap` raised and implemented. CLAUDE.md, README.md, and `docs/engineering/08-workflow.md` updated. *(See OpenSpec change record for full detail.)*
---
### 2.2 Company Vision Confirmed
**CEO confirmed the primary objective:**
> *"SentryAgent.ai is building the world's first free, open-source identity provider specifically for AI agents — think of it as 'Auth0 for agents.'"*
This statement is the north star for all product, process, and portfolio decisions.
---
### 2.3 Virtual Factory Model — Strategic Direction
**CEO introduced the virtual factory concept:**
SentryAgent.ai operates as a virtual factory:
- CEO is human — sole human principal
- Entire engineering team is virtual (LLM-powered)
- CEO has 30+ years managing global engineering teams, building real-time unified communications products generating hundreds of billions in sales
- AgentIdP (Phase 6 complete) is proof of concept for the factory model
**Strategic direction stated by CEO:** The company must now think beyond a single product. The virtual factory must be capable of running multiple product pipelines simultaneously.
**Three goals established:**
| # | Goal |
|---|------|
| 1 | **Product** — AgentIdP: "Auth0 for agents." Ship, prove, grow. |
| 2 | **Process** — World-class engineering operations. The virtual factory is the competitive moat. |
| 3 | **People (Virtual)** — Empower the virtual team with the right structure and governance. |
---
### 2.4 TBC Role — Established
**CEO decision:** A Technical & Business Consultant (TBC) role is established as a direct report to the CEO, alongside the Virtual CTO and Lead Validator.
**Org structure confirmed:**
```
CEO (Human)
├── Virtual CTO → engineering execution, OpenSpec Protocol
├── Lead Validator → independent V&V audit, OpenSpec Protocol
└── Technical & Business Consultant (TBC) → advisory only, CEO only
```
**Key characteristics of TBC role:**
- Reports to CEO only — no interaction with CTO or Validator
- Not bound by OpenSpec Protocol
- Advisory function — does not execute engineering work
- Maintains written records of all CEO sessions (ISO 9000 discipline)
---
### 2.5 Change Authority — Governance Decision
**Question raised:** Should TBC be allowed to make changes to CLAUDE.md, README.md, and PRD.md directly?
**Decision:** TBC may PROPOSE changes. TBC may NOT implement them directly.
**Approved process:**
| Step | Owner |
|------|-------|
| Identify and document proposed change | TBC (in meeting minutes) |
| Review and approve | CEO |
| Instruct CTO to implement via OpenSpec Protocol | CEO → CTO |
| Raise OpenSpec change, implement, commit | CTO |
**Rationale:** All changes to controlled documents must go through OpenSpec. This keeps the change audit trail clean and ensures the CTO remains the sole execution owner. TBC influence flows through the CEO — not directly to the team.
---
### 2.6 TBC Directory — Established
TBC directory created at project root:
```
TBC/
├── charter.md # TBC role charter (TBC-CHARTER-001)
└── minutes/
└── TBC-MIN-001-2026-04-07.md # This document
```
ISO 9000 convention adopted: all documents carry document number, revision history, date, and author.
---
## 3. Decisions Made
| # | Decision | Owner |
|---|----------|-------|
| D1 | Process gap (authorization vs. execution) fixed via OpenSpec change `process-governance-handoff-gap` | CTO (implemented) |
| D2 | Company vision confirmed: "Auth0 for agents" | CEO |
| D3 | Virtual factory must scale to multiple products — strategic direction set | CEO |
| D4 | Three-goal framework established: Product / Process / People | CEO |
| D5 | TBC role established as CEO direct report | CEO |
| D6 | TBC operates outside OpenSpec; proposes changes only — CTO implements | CEO |
| D7 | TBC directory and ISO 9000 minutes convention established | CEO / TBC |
---
## 4. Open Items / Actions
| # | Action | Owner | Status |
|---|--------|-------|--------|
| A1 | CTO to commit outstanding V&V resolution changes and confirm with commit hash | CTO | **Pending — awaiting CEO instruction to CTO** |
| A2 | CEO to authorize field trial execution once A1 is confirmed | CEO | Pending A1 |
| A3 | Update CLAUDE.md to add TBC role to org structure and startup protocol | CTO via OpenSpec | **Proposed — pending CEO authorization** |
| A4 | Define next product(s) for the virtual factory | CEO / TBC | Future session |
---
## 5. Next Session Priorities
1. Close A1 — instruct CTO to execute the pending commit
2. Authorize field trial (A2) once commit is confirmed
3. Begin scoping A3 — update controlled documents to reflect TBC role formally
4. Start portfolio thinking: what is product #2 for the virtual factory?
---
*End of minutes — TBC-MIN-001 | Rev 1.0 | 2026-04-07*

57
docs/engineering/08-workflow.md
View File

@@ -370,3 +370,60 @@ Adds docs/engineering/ with 11 documents covering architecture,
service deep-dives, code walkthroughs, dev setup, workflow, service deep-dives, code walkthroughs, dev setup, workflow,
testing, deployment, and SDK guide. testing, deployment, and SDK guide.
``` ```
---
## 8. CTO Session Completion Protocol
This section applies to the Virtual CTO role. It defines the required communication protocol at the end of any session that involves CEO-authorized actions.
### 8.1 Completion Confirmation (Required)
After the CEO authorizes any action via `#vpe-cto-approvals`, the CTO MUST:
1. Execute the authorized action
2. Post a **completion confirmation** to `#vpe-cto-approvals` before closing the session
The confirmation message MUST include:
| Field | Description |
|-------|-------------|
| Action completed | What was done |
| Outcome | Success or failure |
| Commit hash | Required if the action involved a git commit |
| Resulting state | What state the system/repo is in now |
> Authorization and completion are two distinct, required messages. An authorization alone does not constitute completion.
### 8.2 End-of-Session Summary (Required)
Before closing any session that contains completed, pending, or in-progress work, the CTO MUST post a structured summary to `#vpe-cto-approvals`:
```
## End-of-Session Summary
### Completed This Session
- <action> — <commit hash or outcome>
### Pending (Authorized but Not Yet Executed)
- <action> — authorized in msg #<id>, not yet executed
### Requires CEO Action Next Session
- <decision or approval needed>
```
If nothing is pending and all actions are complete, a brief "session complete, nothing pending" message is sufficient.
### 8.3 Authorized vs. Done Vocabulary
These two terms have precise, non-interchangeable meanings:
| Term | Meaning |
|------|---------|
| **Authorized** | CEO has granted permission. Action has NOT been executed. |
| **Committed / Completed / Deployed** | Action has been executed and confirmed with evidence. |
Rules:
- Never use "completed" or "committed" to describe an action that has only been approved
- Always include supporting evidence when claiming completion (e.g., commit hash, test output)
- If no commit hash exists for a git action, the action is not done — regardless of authorization status

2
openspec/changes/process-governance-handoff-gap/.openspec.yaml Normal file
View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-04-07

44
openspec/changes/process-governance-handoff-gap/design.md Normal file
View File

@@ -0,0 +1,44 @@
## Context
The current multi-agent session protocol (CEO ↔ CTO via `#vpe-cto-approvals`) has a handoff gap: once the CEO authorizes an action, there is no enforcement that the CTO confirms completion before the session ends. The gap was exposed on 2026-04-07 when the CTO received commit authorization but the session ended before posting a confirmation — leaving 5 uncommitted files and the field trial status ambiguous.
The fix is purely process/documentation: CLAUDE.md and README.md are the authoritative session protocol documents. Both must be updated with explicit rules. No code changes are required.
## Goals / Non-Goals
**Goals:**
- Require the CTO to post a completion confirmation to `#vpe-cto-approvals` after every CEO-authorized action
- Require the CTO to post an end-of-session summary before closing
- Establish clear vocabulary: "authorized" ≠ "completed" in all status tracking
- Make these rules durable by codifying them in CLAUDE.md (session protocol) and README.md (CTO responsibilities)
**Non-Goals:**
- Automated enforcement (no code hooks, no CI checks)
- Changes to the V&V process or the `#vv-cto-resolution` channel protocol
- Changes to any service, API, or database
## Decisions
**Decision 1: CLAUDE.md is the primary update target.**
CLAUDE.md is loaded on every new Claude session via the project instructions. Any protocol rule placed there is enforced at session startup. README.md Section 4.3 is secondary — it documents CTO responsibilities but is not loaded automatically. Rationale: rules that need to be followed must live where they are read.
**Decision 2: Completion confirmation is a mandatory, structured message.**
Rather than leaving format open-ended, the confirmation must include: action completed, outcome (success/failure), commit hash (if applicable), and resulting state. This makes it scannable and unambiguous. Alternative considered: free-form text — rejected because it creates ambiguity about whether the action actually completed.
**Decision 3: Session-end summary is required before closing.**
The CTO must post a structured "end of session" summary any time a session ends with pending or in-progress work. Format: completed this session / pending (awaiting execution) / requires CEO action next session. Alternative considered: optional/best-effort — rejected because the exact failure mode was "session ended without summary."
**Decision 4: Authorized vs. Done as explicit vocabulary.**
Status messages must use unambiguous language. "Authorized" means CEO gave permission. "Committed," "deployed," or "completed" means the action was executed and confirmed. These terms must not be used interchangeably.
## Risks / Trade-offs
- **Risk**: CTO session ends abruptly (crash, timeout) before posting session-end summary → **Mitigation**: CEO checks `#vpe-cto-approvals` at startup for the last CTO message; if it is an authorization request (not a completion), treat the action as pending.
- **Risk**: Rules in CLAUDE.md may drift from README.md over time → **Mitigation**: Tasks explicitly update both files; future changes to session protocol must update both.
- **Trade-off**: Adding required messages increases CTO session overhead slightly. Accepted — the cost of a missed commit or ambiguous state is higher.
## Migration Plan
1. Update CLAUDE.md — add CTO Session Completion Protocol section
2. Update README.md Section 4.3 — add session-end checklist and completion confirmation to CTO responsibilities
3. No rollback needed — documentation-only change

24
openspec/changes/process-governance-handoff-gap/proposal.md Normal file
View File

@@ -0,0 +1,24 @@
## Why
The current CEO ↔ CTO authorization protocol has no completion gate — once the CEO approves an action, there is no required confirmation that the action was actually executed. This was exposed in the last session when the CTO received authorization to commit V&V resolution changes but the session ended before confirming completion, leaving 5 files uncommitted and the field trial status ambiguous.
## What Changes
- **Mandatory completion confirmation**: After any CEO-authorized action, the CTO must post a follow-up message to `#vpe-cto-approvals` confirming the action is done — including outcome, commit hash (if applicable), and next state.
- **Session-end summary**: Before closing, the CTO must post a structured end-of-session summary: what was completed, what is pending, and what requires CEO action in the next session.
- **Authorized vs. Done state vocabulary**: CLAUDE.md and all status tracking must use explicit language distinguishing "authorized" (permission granted) from "committed/completed" (action verified done). These are not interchangeable.
## Capabilities
### New Capabilities
- `cto-session-protocol`: Formal CTO session protocol rules — completion confirmation requirement, session-end checklist, and authorized-vs-done state vocabulary — codified in CLAUDE.md and README.md.
### Modified Capabilities
- `engineering-workflow`: Session protocol and CTO communication standards are a subset of the engineering workflow; the workflow spec requires a delta to reflect the new completion gate requirement.
## Impact
- `CLAUDE.md` — primary update target; CTO session protocol section added
- `README.md` — Section 4.3 (Virtual CTO responsibilities) updated to reflect session-end checklist
- No code changes, no API changes, no new dependencies
- No breaking changes to existing functionality

38
openspec/changes/process-governance-handoff-gap/specs/cto-session-protocol/spec.md Normal file
View File

@@ -0,0 +1,38 @@
## ADDED Requirements
### Requirement: CTO completion confirmation after authorized action
After the CEO authorizes any action via `#vpe-cto-approvals`, the CTO SHALL post a follow-up confirmation message to `#vpe-cto-approvals` once the action is executed. The confirmation MUST include: (1) the action completed, (2) outcome (success or failure), (3) commit hash if the action involved a git commit, and (4) the resulting system state. An authorization message and a completion confirmation are two distinct, required messages — authorization alone does not constitute completion.
#### Scenario: CEO authorizes a git commit
- **WHEN** the CEO posts approval for the CTO to commit outstanding changes
- **THEN** the CTO SHALL execute the commit and post a confirmation message containing the commit hash, files committed, and current git state before the session ends
#### Scenario: Authorized action cannot be completed
- **WHEN** the CTO encounters a blocker executing a CEO-authorized action
- **THEN** the CTO SHALL post a message to `#vpe-cto-approvals` describing the blocker and requesting CEO guidance — the action remains in "authorized but pending" state until resolved
#### Scenario: Session ends after authorization but before execution
- **WHEN** a CTO session ends before an authorized action is executed
- **THEN** the CEO SHALL treat the action as pending (not complete) and re-authorize in the next session before the CTO proceeds
### Requirement: CTO end-of-session summary
Before closing any session that contains completed, pending, or in-progress work, the CTO SHALL post a structured end-of-session summary to `#vpe-cto-approvals`. The summary MUST contain three sections: (1) Completed this session, (2) Pending — authorized but not yet executed, (3) Requires CEO action next session.
#### Scenario: Session ends with all work complete
- **WHEN** the CTO closes a session with no pending authorized actions
- **THEN** the CTO SHALL post an end-of-session summary confirming all authorized actions were completed, listing commit hashes where applicable
#### Scenario: Session ends with pending work
- **WHEN** the CTO closes a session and one or more authorized actions were not yet executed
- **THEN** the CTO SHALL post an end-of-session summary explicitly listing each pending action under "Pending — authorized but not yet executed" so the next session can pick up cleanly
### Requirement: Authorized vs. Done state vocabulary
All CTO status messages, ledger entries, and session summaries SHALL use unambiguous language to distinguish between permission state and execution state. "Authorized" means the CEO has granted permission. "Committed," "deployed," or "completed" means the action has been executed and confirmed. These terms MUST NOT be used interchangeably in any status communication.
#### Scenario: CTO reports on a CEO-approved but unexecuted action
- **WHEN** the CTO describes an action the CEO has approved but the CTO has not yet executed
- **THEN** the message SHALL use the word "authorized" and SHALL NOT use "completed," "committed," or "done"
#### Scenario: CTO reports on a fully executed action
- **WHEN** the CTO describes an action that has been executed and confirmed
- **THEN** the message SHALL use "committed," "deployed," or "completed" with supporting evidence (e.g., commit hash, test results)

36
openspec/changes/process-governance-handoff-gap/specs/engineering-workflow/spec.md Normal file
View File

@@ -0,0 +1,36 @@
## MODIFIED Requirements
### Requirement: Engineering workflow and contribution guide
The system SHALL include a document (`docs/engineering/08-workflow.md`) that prescribes the exact steps an engineer MUST follow to contribute any new feature or change, from idea to merged code.
#### Scenario: OpenSpec spec-first workflow explained
- **WHEN** a new engineer reads 08-workflow.md
- **THEN** they SHALL understand that NO implementation begins without an approved OpenAPI spec — and the exact sequence: CEO approves → Architect writes spec → CTO reviews → Developer implements → QA signs off → CEO approves merge
#### Scenario: OpenSpec CLI commands documented
- **WHEN** a new engineer wants to start a new change
- **THEN** the guide SHALL provide the exact commands: `openspec new change <name>`, `openspec status --change <name>`, `openspec instructions <artifact> --change <name>`, and what each command does
#### Scenario: Branching strategy documented
- **WHEN** a new engineer creates a branch
- **THEN** the guide SHALL prescribe: feature branches from `develop`, naming convention `feature/<change-name>`, PR targets `develop`, `develop` → `main` requires CTO + CEO approval
#### Scenario: TypeScript and code standards enforced in workflow
- **WHEN** a new engineer writes code
- **THEN** the guide SHALL state the non-negotiable standards: strict mode, no `any`, DRY, SOLID, JSDoc on all public methods — and that PRs violating these are blocked by the CTO regardless of functionality
#### Scenario: PR checklist documented
- **WHEN** a new engineer opens a PR
- **THEN** the guide SHALL provide a PR checklist: TypeScript compiles with zero errors, ESLint passes with zero warnings, unit tests pass, coverage gate met (>80%), integration tests pass, OpenAPI spec updated if endpoint changed, engineering docs updated if architecture changed
#### Scenario: Virtual engineering team roles explained for contributors
- **WHEN** a new engineer reads 08-workflow.md
- **THEN** they SHALL understand the role separation: they contribute as the Principal Developer role, the CTO reviews all PRs, the Architect owns spec changes, and QA owns the test sign-off — and how to interact with each role in practice
#### Scenario: Commit message conventions documented
- **WHEN** a new engineer writes a commit message
- **THEN** the guide SHALL prescribe the Conventional Commits format: `feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:` prefixes — with examples for each
#### Scenario: CTO session completion protocol documented in workflow guide
- **WHEN** a new engineer or CTO reads 08-workflow.md
- **THEN** they SHALL understand that every CEO-authorized action requires a completion confirmation message posted to `#vpe-cto-approvals` before the session ends, and that "authorized" and "completed" are distinct states that MUST NOT be used interchangeably

15
openspec/changes/process-governance-handoff-gap/tasks.md Normal file
View File

@@ -0,0 +1,15 @@
## 1. Update CLAUDE.md — CTO Session Completion Protocol
- [x] 1.1 Add a new "CTO SESSION COMPLETION PROTOCOL" section to CLAUDE.md under the CEO APPROVAL GATES section
- [x] 1.2 Document the mandatory completion confirmation rule: after any CEO-authorized action, CTO must post a follow-up to `#vpe-cto-approvals` with action, outcome, commit hash (if applicable), and resulting state
- [x] 1.3 Document the end-of-session summary rule: before closing, CTO must post a structured summary with three sections — Completed / Pending (authorized but not executed) / Requires CEO action next session
- [x] 1.4 Document the authorized-vs-done vocabulary rule: "authorized" = permission granted, "committed/completed/deployed" = action executed and confirmed — never interchangeable
## 2. Update README.md — Virtual CTO Responsibilities
- [x] 2.1 In Section 4.3 (Virtual CTO), add completion confirmation and end-of-session summary to the CTO responsibilities list
- [x] 2.2 Update the "Claude Session Startup (CTO Role)" block in Section 4.3 to include session-end checklist as a required step before closing
## 3. Update Engineering Workflow Doc
- [x] 3.1 In `docs/engineering/08-workflow.md`, add a section documenting the CTO session completion protocol — completion confirmation requirement, session-end checklist, and authorized-vs-done vocabulary — per the engineering-workflow spec delta

2
scripts/start-cto.sh
View File

@@ -26,7 +26,7 @@ echo " Workspace: $CTO_WORKSPACE"
echo " Hub Channel: #vpe-cto-approvals" echo " Hub Channel: #vpe-cto-approvals"
echo "" echo ""
echo " The Virtual CTO will:" echo " The Virtual CTO will:"
echo " 1. Read README.md" echo " 1. Read PRD.md then README.md"
echo " 2. Register on central hub as VirtualCTO" echo " 2. Register on central hub as VirtualCTO"
echo " 3. Report status to CEO" echo " 3. Report status to CEO"
echo " 4. Await CEO priorities" echo " 4. Await CEO priorities"