sentryagent-idp/openspec/changes/archive/2026-04-07-vv-architect-setup/design.md

Design — vv-architect-setup

Context

SentryAgent.ai uses a multi-agent Claude Code architecture:

• CEO-Session — human-facing, governance and priorities
• VirtualCTO — technical authority, directs engineering team
• Engineering Team (Architect, Developer, QA) — spawned as subagents by CTO

All prior phases passed through the CTO's review and QA sign-off. No independent verification existed outside that chain. The V&V Architect adds a separate audit loop that operates with full read access to the codebase but no write authority over it.

Goals / Non-Goals

Goals:

• Provide CEO-level assurance that the codebase matches the PRD and OpenSpec
• Detect spec-implementation gaps, DRY violations, TypeScript violations, test gaps, and security issues
• Create a formal, auditable issue trail (VV_ISSUE_NNN.md files)
• Enable the CEO to see a release gate status at any time (LEDGER.md)

Non-Goals:

• The validator does NOT fix code — it only reports findings
• The validator does NOT block the CTO from working in parallel
• The validator does NOT attend to new feature planning or business decisions
• The validator does NOT replace the QA Engineer — QA tests functionality; V&V audits completeness and standards compliance

Architecture

CEO (Human)
├── CEO-Session (this Claude Code instance)
│   └── VirtualCTO (separate terminal — .cto-workspace/)
│       ├── Virtual Architect    (subagent)
│       ├── Virtual Developer    (subagent)
│       └── Virtual QA Engineer (subagent)
└── LeadValidator (separate terminal — .validator-workspace/)   ← NEW
    Reports findings to CEO via #vv-findings
    BLOCKER alerts also go to #vpe-cto-approvals

The LeadValidator is the only agent in the system that:

1. Reports directly to the CEO (not via CTO)
2. Can issue a BLOCKER that prevents release
3. Operates from an isolated workspace with no engineering team context

Decisions

D1: System Prompt Injection vs. CLAUDE.md Workspace

Decision: Use --system-prompt-file VALIDATOR.md to inject the validator's identity.

Rationale: The CTO uses .cto-workspace/CLAUDE.md for its identity because Claude Code reads CLAUDE.md as project context. For the validator, using --system-prompt-file is more explicit and harder to accidentally override — the validator's identity is injected at the OS level, not discovered by file-scan. This also prevents any future accidental CLAUDE.md conflicts if the workspace is updated.

Alternative considered: Give validator its own CLAUDE.md identity like the CTO — rejected because --system-prompt-file makes the validator identity non-negotiable and audit-grade.

D2: Shared Ledger — Filesystem vs. Central Hub Only

Decision: Filesystem ledger (openspec/vv_audit/) as primary, central hub as notification layer.

Rationale: Issue files (VV_ISSUE_NNN.md) need to be persistent, versioned in git, and readable by humans without opening a terminal. The central hub is ephemeral session state. Filesystem issues survive session restarts; hub messages do not.

Alternative considered: Hub-only communication — rejected because hub messages are not committed to git and cannot be audited historically.

D3: Issue Severity Model

Decision: Three-tier severity — BLOCKER / MAJOR / MINOR.

Severity	Release impact	Who can close
BLOCKER	Prevents release	CEO acknowledges; CTO resolves
MAJOR	Must resolve before next phase	CTO resolves; Validator confirms
MINOR	Best-effort improvement	CTO resolves; no re-audit needed

Rationale: Binary pass/fail is too blunt for a mature codebase. Three tiers allow the team to ship with known MINOR issues while ensuring BLOCKERs are never silently bypassed.

D4: Validator Workspace Isolation

Decision: Validator writes its own minimal CLAUDE.md to .validator-workspace/ rather than copying the CEO session's CLAUDE.md.

Rationale: The CEO session CLAUDE.md defines multi-agent setup and CEO startup protocol — none of which applies to an auditor. Copying it would contaminate the validator context. The validator's workspace CLAUDE.md only provides absolute path references to project resources.

D5: Audit Phases

Decision: 8 audit phases covering all PRD compliance dimensions.

Phase	Scope
A	OpenSpec task completeness
B	API surface vs OpenAPI specs
C	TypeScript strict mode compliance
D	DRY principle enforcement
E	SOLID principle spot-checks
F	Test coverage (>80% threshold)
G	AGNTCY compliance
H	Security (OWASP Top 10)

All 8 phases must be run per audit session. A validator may document why a phase was skipped but cannot silently omit it.

File Map

File	Purpose
VALIDATOR.md	System prompt for LeadValidator agent
scripts/start-validator.sh	Launches validator, sets up workspace, sanity-checks VALIDATOR.md
.validator-workspace/	Isolated workspace (gitignored)
.validator-workspace/CLAUDE.md	Validator workspace context (absolute paths only)
openspec/vv_audit/LEDGER.md	Audit ledger index — updated after each session
openspec/vv_audit/VV_ISSUE_NNN.md	Individual issue files written by validator
.cto-workspace/CLAUDE.md	Updated Peer-Review Protocol section

Hub Channels

Channel	Purpose
#vv-findings	Validator → CEO + CTO: audit summaries, issue notifications
#vpe-cto-approvals	Validator → CEO only: BLOCKER escalations