Verdict Codebase Structure Map
Based on my exploration of the Verdict codebase (500k+ lines), here's a comprehensive map
of the overall structure:
1. HIGH-LEVEL DIRECTORY STRUCTURE
/Verdict (root)
├── /services/ # Core microservices (P0 stack)
├── /cloud/ # Cloud backend & web services
├── /docs/ # Documentation & PRDs
├── /artifacts/ # Runtime artifacts & state
├── /configs/ # Configuration files
├── /tests/ # Test suites
├── /extensions/ # VSCode extension
├── /scripts/ # Operational scripts
├── /tools/ # Utility tools
├── /.claude/agents/ # Agent role definitions (coordinator/execution hierarchy)
├── /app/ # Original LNSP/FactoidWiki pipeline
├── /cli.py # Main CLI entry point
└── /CLAUDE.md # Project instructions
2. AGENT HIERARCHY & ORCHESTRATION (PAS - Polyglot Agent Swarm)
The agent system is defined in /.claude/agents/ with a clear coordinator/execution
hierarchy:
Coordinator Tier (High-Level Planning)
Located:
/Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/.claude/agents/coordinator/
- Architect (architect.md) - Role: coord / Tier: 1
- Decomposes PRDs, allocates tasks to Directors
- Children: Director-Code, Director-Models, Director-Data, Director-DevSecOps,
Director-Docs
- Full read/write filesystem, bash, git, python, network access
- 200k token budget per run
Execution Tier (Domain-Specific Coordination)
Located:
/Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/.claude/agents/execution/
- Directors (5 variants, e.g., director-code.md)
- Director-Code, Director-Models, Director-Data, Director-DevSecOps, Director-Docs
- Each handles domain-specific decomposition and lane planning
- Managers (5 variants, e.g., manager-code.md)
- Orchestrate Manager execution within Director lanes
- Execution Agents (17+ specialized agents)
- Code-Writer, Deployment-Orchestrator, DevsecOps-Agent, Evaluator-Gatekeeper
- Documentation-Generator, Graph-Builder, Release-Coordinator, etc.
3. PAS (PROJECT AUTOMATION SYSTEM) - Core Orchestrator
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/services/pas/
Root Orchestrator (Port 6100)
- File: /services/pas/root/app.py (43.7 KB)
- Responsibility: Accept Prime Directives, create run IDs, spawn background tasks, track
status
- Core Class: Uses RoleStrategySwitchboard factory to instantiate role adapters
- Entry Point: FastAPI app with streaming response support
- Key Routes:
- Blueprint router: /services/pas/root/routers/blueprint.py
- PLMS Plans router: /services/plms/api/plans.py
Agent Implementations
- Architect (/services/pas/architect/app.py)
- Plan parsing, decomposition, SAM hooks
- Classes: PlanModels, PlanParser, PlanRevision
- Directors (5 variants)
- Code (/services/pas/director_code/), Data, Models, DevSecOps, Docs
- Each has app.py + decomposer.py
- Managers (5 variants)
- Code, Data, Models, DevSecOps, Docs
- Located in /services/pas/manager_
- Jobcard Store (/services/pas/jobcard_store/)
- Database models: models.py
- Database access: database.py
- FastAPI app: app.py
Support Systems
- TRON (Task Resource Orchestration Network) - /services/pas/tron/
- Service monitor, restart manager, kill coordinator, notification integration
- Guardian (Error/Backup Recovery) - /services/pas/guardian_/
- Error recovery, backup/recovery, escalation, token management
- Stub/Test Infrastructure - /services/pas/stub/app.py
4. TASK EXECUTION AGENTS (TEA) - Role Adapters & Backends
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/services/common/r
ole_adapters/
Role Strategy Switchboard (Factory Pattern)
File: /services/pas/root/strategy_switchboard.py
- Reads effective_config.task_execution_agents from Run Packs
- Instantiates correct adapter per tier based on strategy
- Valid Strategies:
- Architect: verdict | claude_planner
- Director: verdict | claude_planner
- Manager: verdict | claude_planner_only
- Programmer: aider | claude_executor | verdict_native
Adapter Base Classes
- ArchitectAdapter (ABC)
- DirectorAdapter (ABC)
- ManagerAdapter (ABC)
- ProgrammerBackend (ABC)
Backend Implementations
- AiderCliBackend: CLI one-shot execution with local LLM
- ClaudeCodeVCCABackend: Claude Code via VCCA (Verdict ⇄ CloudCode Adapter)
- VerdictNativeBackend: Future native implementation
- VerdictArchitectAdapter, VerdictDirectorAdapter, VerdictManagerAdapter: Native Verdict
implementations
- ClaudePlannerArchitectAdapter, ClaudePlannerDirectorAdapter,
ClaudePlannerOnlyManagerAdapter: Claude-based planners
5. CLAUDE CODE INTEGRATION (VCCA - Verdict ⇄ CloudCode Adapter)
Location:
/Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/services/common/vcca/
VCCA Core Components
- Main Adapter (adapter.py - 28.9 KB)
- Class: VCCAAdapter
- Translates JobCard to Claude Code tasks
- BYOK model injection via environment variables
- Kill-switch implementation (SIGTERM → wait 5s → SIGKILL)
- Timeout monitoring with background tasks
- Artifact capture (diffs, logs, test results)
- Access Methods (access_methods.py - 24.9 KB)
- CliSubprocessMethod: Execute via subprocess (current)
- EmbeddedMethod: Future embedded SDK
- RemoteServiceMethod: Future remote service
- Factory: get_access_method()
- Config & Results
- VCCAConfig: Timeout, kill-switch, artifact capture settings
- VCCAResult: Status, artifacts, files modified, acceptance results
Integration Points
- PAS Programmer tier calls VCCAAdapter.execute()
- Receives JobCard (task description + files)
- Returns ExecutionResult with diffs, test results, logs
- Supports BYOK via model_config parameter
6. RUN PACKS & CONFIGURATION (Config Registry)
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/cloud/services/co
nfig_registry/
Core Services
- Main API (main.py - 97.6 KB)
- FastAPI endpoints for CRUD operations
- Port: 6125 (Config Registry service port)
- RunPack Service (service/runpack_service.py)
- RunPackResponse dataclass
- CRUD operations on Run Packs
- Database persistence via SQLAlchemy
- Transaction management
- Compiler Service (service/compiler_service.py)
- Compiles profile selections into effective_config
- CompileResult with compiled output
- Validator (validator.py - 30 KB)
- Profile validation
- Schema compliance checking
Run Pack Profiles (8 Types)
1. Model - Model selection and routing
2. Prompt - Prompt engineering settings
3. Resource - CPU/memory/token budgets
4. Telemetry - Logging and monitoring
5. Execution - Runtime execution parameters
6. Orchestration - Agent behavior and lanes
7. Cost - Cost control and billing
8. Task Execution Agents (NEW) - Agent backend selection per tier
Database Schema
- Models: /cloud/db/models.py
- ConfigRunPack - Main Run Pack entity
- ConfigRunPackRevision - Version tracking
- Migrations: /cloud/db/alembic/versions/
- 025_add_run_packs_tables.py
- 028_add_system_scope_and_default_run_pack.py
Schema Files
- /cloud/services/config_registry/schemas/runpack.v1.json
- /cloud/services/config_registry/schemas/profiles/orchestration.v1.json
- Profile definitions in /cloud/services/config_registry/schemas/profiles/
7. CLOUD SERVICES ECOSYSTEM
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/cloud/services/
- Gateway (Port 6123) - gateway/
- Vendor routing, cost estimation, model management
- run_pack_client.py - Client for config registry
- cost_estimator.py - Cost calculations
- vendor_client.py - Vendor API interactions
- Config Registry (Port 6125) - config_registry/
- Run Packs, Workflow Packages, profile management
- Billing (billing/) - Credit tracking and charges
- Ledger (ledger/) - Experiment/run recording
- Jobs (jobs/) - Job scheduling
- Price Book (price_book/) - Model pricing
- Notifications (notifications/) - Alerts
- Policy (policy/) - Authorization
- Publisher (publisher/) - Event publishing
- Stripe (stripe/) - Payment integration
8. LOCAL GATEWAY & SERVICES
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/services/gateway/
- Port 6120 (Local Gateway) - Proxy only, NO billing
- Provides OpenAI-compatible API for local LLMs
- Used by Claude Code as provider (BYOK via model_config)
- Routes to:
- Local Ollama instances
- LAN LLM providers
- Cloud vendors
9. KEY SUPPORTING SYSTEMS
PLMS (Project Lifecycle Management System)
- Location: /services/plms/
- Port: 6100 (via PAS Root)
- Auto-generates PRDs and Run Packs with sensible defaults
- Components: plms_ideation/, plms_clarification/, plms_estimation/, plms_prd_gen/
Demo Agents (Example Implementations)
- Location: /services/demo_agents/
- Full role hierarchy example: dir_code/, mgr_code/, prog_code_fast/, prog_code_heavy/
Common Utilities
- Location: /services/common/
- base_agent.py, base_director.py, base_programmer.py - Base classes
- comms_logger.py - Unified logging
- heartbeat.py - Service health monitoring
- provider_registry.py - Model provider management
- llm_tool_caller.py - Tool invocation
- relay_client.py - Message relay
- job_card.py - Job card definitions
- prompt_templates.py - Prompt engineering
10. DOCUMENTATION HUB
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/docs/
Key PRDs (Product Requirements Documents)
- PRD_Task_Execution_Agents_v2.1.md (1,958 lines)
- Complete specification for agent strategy selection
- VCCA architecture details
- Role adapter interface definitions
- Strategy-backend compatibility matrix
- PRD_Run_Packs_and_Workflow_Packages_v1.md
- Run Pack schema and profiles
- Workflow package definitions
- PRD_Task_Execution_Agents_Aider_and_ClaudeCode.md
- Aider integration details
- Claude Code integration specifics
Howto Guides
- how_to_use_run_packs_settings.md - Run Pack management
- how_to_manage_model_aliases.md - Model alias configuration
- how_to_add_vendor_models.md - Vendor model integration
Architectural Docs
- docs/architecture.md - FactoidWiki/LNSP pipeline details
- docs/SERVICE_PORTS.md - Complete port mapping
- docs/QUICK_COMMANDS.md - Quick start
- docs/DATA_FLOW_DIAGRAM.md - Data flow overview
11. CONFIGURATION FILES
Location: /Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/configs/pas/
- agent_tools.json - Available tools per agent
- llm_codes.json - LLM capabilities
- model_pool_registry.json - Model pool definitions
- programmer_.yaml - Programmer-specific configs (006-010)
- manager_.yaml - Manager-specific configs
12. VSCode EXTENSION (Verdict IDE)
Location:
/Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/extensions/verdict-vscode/
- Entry Point: src/extension.ts
- Chat UI: src/chatPanel.ts
- Deep Links: src/deepLinkHandler.ts (handles verdict:// URLs)
- Package: version 1.0.121+
- Build: npm run compile → npm run package (generates .vsix)
13. BLUEPRINT (VERDICT IDE INTEGRATION)
Location:
/Users/trentcarter/Artificial_Intelligence/AI_Projects/Verdict/services/blueprint/
- Router: /services/pas/root/routers/blueprint.py
- Provides integration API for Verdict IDE
- Handles deeplink protocol parsing
- Forwards tasks to PAS Root
---
CRITICAL ARCHITECTURE INSIGHTS
Agent Execution Flow
User (IDE/HMI)
↓
PAS-Root (6100) reads Run Pack
↓
RoleStrategySwitchboard selects adapters
↓
Architect (plans) → Directors (coordinate) → Managers (route) → Programmers (execute)
↓
Programmer calls appropriate backend:
- AiderCliBackend (local, CLI)
- ClaudeCodeVCCABackend (stateful, autonomous)
- VerdictNativeBackend (future)
↓
Result: ExecutionResult with diffs, artifacts, acceptance status
Key Files for Integration
- Orchestration Entry: /services/pas/root/app.py
- Strategy Selection: /services/pas/root/strategy_switchboard.py
- Claude Code Integration: /services/common/vcca/adapter.py
- Programmer Base: /services/common/role_adapters/programmer_backend.py
- Run Pack Config: /cloud/services/config_registry/main.py
- PRD Reference: /docs/PRDs/PRD_Task_Execution_Agents_v2.1.md
Model Routing (BYOK Pattern)
Claude Code Runtime
↓ (BYOK environment vars)
Local Gateway (6120)
↓ (OpenAI-compatible proxy)
Ollama / LAN LLM / Cloud Vendor (based on Run Pack model_set)
---
FILE COUNT SUMMARY
- PAS Services: 50+ Python files (architect, 5 directors, 5 managers, support systems)
- VCCA Adapter: 2 main files (adapter.py, access_methods.py)
- Config Registry: 40+ files (API, compiler, validator, database)
- Cloud Services: 200+ files across 13 service domains
- Common Utilities: 80+ files (base classes, logging, LLM tools, adapters)
- Documentation: 100+ markdown files (PRDs, howtos, guides)
- Tests: 50+ test files covering PAS, Config Registry, Gateway
---
This map gives you a complete picture of how Verdict's agent swarm (PAS) operates, how
Claude Code integrates via VCCA, and how Run Packs configure everything from orchestration
strategy to execution backend selection.