# mazharr-hussain/vash-framework architecture

> Architecture diagram of the GitHub repository mazharr-hussain/vash-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mazharr-hussain/vash-framework
- Repository: https://github.com/mazharr-hussain/vash-framework

## Overview

VASH is a Python framework for an AI-driven software-house workflow: users configure a project freeze, run Agent-vs-Agent work, validate it through deterministic gates, and use adapters for model, forge, CI, and cloud services. The CLI also supports project loading, reusable skills, stack checks, and OCI runner onboarding. The README describes these capabilities at a high level; edges below rely on the sampled excerpts and SOURCE INDEX references, so unsampled runtime wiring is intentionally limited.

Main entry points: [`src/vash/adapters/cloud/oci/onboard.py`](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/onboard.py) (OCI onboarding), [`src/vash/cli/main.py`](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/main.py) (VASH CLI), [`src/vash/ava/runner.py`](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/ava/runner.py) (AvA runner), [`src/vash/loader/load.py`](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/load.py) (Project loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Project workflow"]
  node_cli["VASH CLI<br/>[main.py]"]
  node_init["Project init<br/>[init.py]"]
  node_loader["Project loader<br/>[load.py]"]
  node_manifest["Manifest parser<br/>[manifest.py]"]
  node_skills["Skills and agents<br/>[skills.py]"]
  node_skill_cli["Skill commands<br/>[skill.py]"]
  node_gate1["Gate 1 checks<br/>[gate1.py]"]
  node_stackcheck["Stack checks<br/>[check_stack.py]"]
end

subgraph group_engine["AvA engine"]
  node_ava_cli["AvA command<br/>[ava.py]"]
  node_runner["AvA runner<br/>[runner.py]"]
  node_freeze["Project freeze<br/>[freeze.py]"]
  node_llm_router["LLM routing<br/>[__init__.py]"]
end

subgraph group_adapters["Technology adapters"]
  node_llm_adapters["LLM adapters<br/>[adapter.py]"]
  node_forge["GitHub forge<br/>[adapter.py]"]
  node_pr_review["PR review<br/>[pr_review.py]"]
  node_ci_adapters["CI adapters<br/>[adapter.py]"]
end

subgraph group_cloud["OCI onboarding"]
  node_oci_adapter["OCI adapter<br/>[adapter.py]"]
  node_onboard["OCI onboarding<br/>[onboard.py]"]
  node_foundation["OCI foundation<br/>[foundation.py]"]
  node_guardrails["OCI guardrails<br/>[guardrails.py]"]
  node_security["OCI security<br/>[security.py]"]
  node_inventory["OCI inventory<br/>[inventory.py]"]
  node_cleaner["OCI cleaner<br/>[cleaner.py]"]
end

subgraph group_support["Shared runtime"]
  node_interfaces["Adapter interfaces<br/>[interfaces.py]"]
  node_registry["Adapter registry<br/>[registry.py]"]
  node_paths["Path resolver<br/>[paths.py]"]
  node_write_guard["MCP write guard<br/>[write_guard.py]"]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches init"| node_init
node_cli -->|"dispatches load"| node_loader
node_cli -->|"dispatches AvA"| node_ava_cli
node_cli -->|"dispatches skills"| node_skill_cli
node_ava_cli -->|"runs activity"| node_runner
node_runner -->|"loads configuration"| node_freeze
node_runner -->|"runs checks"| node_gate1
node_runner -->|"requests replies"| node_llm_router
node_runner -->|"loads named skills"| node_skills
node_llm_router -->|"loads adapter"| node_registry
node_llm_adapters -->|"implements interface"| node_interfaces
node_loader -->|"reads settings"| node_freeze
node_loader -->|"uses manifest"| node_manifest
node_loader -->|"loads skills"| node_skills
node_manifest -->|"uses skill data"| node_skills
node_skill_cli -->|"validates skills"| node_skills
node_skill_cli -->|"reads settings"| node_freeze
node_skill_cli -->|"loads forge adapter"| node_registry
node_cli -->|"dispatches check"| node_stackcheck
node_onboard -->|"uses cloud adapter"| node_oci_adapter
node_onboard -->|"uses foundation"| node_foundation
node_onboard -->|"applies guardrails"| node_guardrails
node_onboard -->|"uses security setup"| node_security
node_onboard -->|"queries resources"| node_inventory
node_onboard -->|"cleans resources"| node_cleaner
node_oci_adapter -->|"implements interface"| node_interfaces
node_foundation -->|"uses adapter"| node_oci_adapter
node_guardrails -->|"uses foundation"| node_foundation
node_security -->|"uses foundation"| node_foundation
node_forge -->|"implements interface"| node_interfaces
node_ci_adapters -->|"implements interface"| node_interfaces
node_pr_review -->|"uses GitHub API"| node_forge
node_pr_review -.->|"uses model adapter"| node_llm_adapters
node_init -->|"resolves paths"| node_paths

click node_cli "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/main.py"
click node_init "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/init.py"
click node_loader "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/load.py"
click node_manifest "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/manifest.py"
click node_skills "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/skills.py"
click node_skill_cli "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/skill.py"
click node_gate1 "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/tools/gate1.py"
click node_stackcheck "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/tools/check_stack.py"
click node_ava_cli "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/ava.py"
click node_runner "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/ava/runner.py"
click node_freeze "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/freeze.py"
click node_llm_router "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/llm/__init__.py"
click node_llm_adapters "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/llm/ollama/adapter.py"
click node_forge "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/forge/github/adapter.py"
click node_pr_review "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/forge/github/pr_review.py"
click node_ci_adapters "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/ci/github_actions/adapter.py"
click node_oci_adapter "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/adapter.py"
click node_onboard "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/onboard.py"
click node_foundation "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/foundation.py"
click node_guardrails "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/guardrails.py"
click node_security "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/security.py"
click node_inventory "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/inventory.py"
click node_cleaner "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/cleaner.py"
click node_interfaces "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/interfaces.py"
click node_registry "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/registry.py"
click node_paths "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/paths.py"
click node_write_guard "https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/mcp/write_guard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_init,node_loader,node_manifest,node_skills,node_skill_cli,node_gate1,node_stackcheck toneBlue
class node_ava_cli,node_runner,node_freeze,node_llm_router toneAmber
class node_llm_adapters,node_forge,node_pr_review,node_ci_adapters toneMint
class node_oci_adapter,node_onboard,node_foundation,node_guardrails,node_security,node_inventory,node_cleaner toneRose
class node_interfaces,node_registry,node_paths,node_write_guard,node_user toneIndigo
```

## Components

### Project workflow

- [VASH CLI](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/main.py): `src/vash/cli/main.py`
- [Project init](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/init.py): `src/vash/cli/init.py`
- [Project loader](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/load.py): `src/vash/loader/load.py`
- [Manifest parser](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/manifest.py): `src/vash/loader/manifest.py`
- [Skills and agents](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/loader/skills.py): `src/vash/loader/skills.py`
- [Skill commands](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/skill.py): `src/vash/cli/skill.py`
- [Gate 1 checks](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/tools/gate1.py): `src/vash/tools/gate1.py`
- [Stack checks](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/tools/check_stack.py): `src/vash/tools/check_stack.py`

### AvA engine

- [AvA command](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/cli/ava.py): `src/vash/cli/ava.py`
- [AvA runner](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/ava/runner.py): `src/vash/ava/runner.py`
- [Project freeze](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/freeze.py): `src/vash/core/freeze.py`
- [LLM routing](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/llm/__init__.py): `src/vash/adapters/llm/__init__.py`

### Technology adapters

- [LLM adapters](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/llm/ollama/adapter.py): `src/vash/adapters/llm/ollama/adapter.py`
- [GitHub forge](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/forge/github/adapter.py): `src/vash/adapters/forge/github/adapter.py`
- [PR review](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/forge/github/pr_review.py): `src/vash/adapters/forge/github/pr_review.py`
- [CI adapters](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/ci/github_actions/adapter.py): `src/vash/adapters/ci/github_actions/adapter.py`

### OCI onboarding

- [OCI adapter](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/adapter.py): `src/vash/adapters/cloud/oci/adapter.py`
- [OCI onboarding](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/onboard.py): `src/vash/adapters/cloud/oci/onboard.py`
- [OCI foundation](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/foundation.py): `src/vash/adapters/cloud/oci/foundation.py`
- [OCI guardrails](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/guardrails.py): `src/vash/adapters/cloud/oci/guardrails.py`
- [OCI security](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/security.py): `src/vash/adapters/cloud/oci/security.py`
- [OCI inventory](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/inventory.py): `src/vash/adapters/cloud/oci/inventory.py`
- [OCI cleaner](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/adapters/cloud/oci/cleaner.py): `src/vash/adapters/cloud/oci/cleaner.py`

### Shared runtime

- [Adapter interfaces](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/interfaces.py): `src/vash/core/interfaces.py`
- [Adapter registry](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/registry.py): `src/vash/core/registry.py`
- [Path resolver](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/core/paths.py): `src/vash/core/paths.py`
- [MCP write guard](https://github.com/mazharr-hussain/vash-framework/blob/main/src/vash/mcp/write_guard.py): `src/vash/mcp/write_guard.py`

### Other components

- **Engineer**

## Connections

- Engineer → VASH CLI: runs commands (evidence: `src/vash/cli/main.py`)
- VASH CLI → Project init: dispatches init (evidence: `src/vash/cli/main.py`)
- VASH CLI → Project loader: dispatches load (evidence: `src/vash/cli/main.py`)
- VASH CLI → AvA command: dispatches AvA (evidence: `src/vash/cli/main.py`)
- VASH CLI → Skill commands: dispatches skills (evidence: `src/vash/cli/main.py`)
- AvA command → AvA runner: runs activity (evidence: `src/vash/cli/ava.py`)
- AvA runner → Project freeze: loads configuration (evidence: `src/vash/ava/runner.py`)
- AvA runner → Gate 1 checks: runs checks (evidence: `src/vash/ava/runner.py`)
- AvA runner → LLM routing: requests replies (evidence: `src/vash/ava/runner.py`)
- AvA runner → Skills and agents: loads named skills (evidence: `src/vash/ava/runner.py`)
- LLM routing → Adapter registry: loads adapter (evidence: `src/vash/adapters/llm/__init__.py`)
- LLM adapters → Adapter interfaces: implements interface (evidence: `src/vash/adapters/llm/ollama/adapter.py`)
- Project loader → Project freeze: reads settings (evidence: `src/vash/loader/load.py`)
- Project loader → Manifest parser: uses manifest (evidence: `src/vash/loader/load.py`)
- Project loader → Skills and agents: loads skills (evidence: `src/vash/loader/load.py`)
- Manifest parser → Skills and agents: uses skill data (evidence: `src/vash/loader/manifest.py`)
- Skill commands → Skills and agents: validates skills (evidence: `src/vash/cli/skill.py`)
- Skill commands → Project freeze: reads settings (evidence: `src/vash/cli/skill.py`)
- Skill commands → Adapter registry: loads forge adapter (evidence: `src/vash/cli/skill.py`)
- VASH CLI → Stack checks: dispatches check (evidence: `src/vash/cli/main.py`)
- OCI onboarding → OCI adapter: uses cloud adapter (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI onboarding → OCI foundation: uses foundation (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI onboarding → OCI guardrails: applies guardrails (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI onboarding → OCI security: uses security setup (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI onboarding → OCI inventory: queries resources (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI onboarding → OCI cleaner: cleans resources (evidence: `src/vash/adapters/cloud/oci/onboard.py`)
- OCI adapter → Adapter interfaces: implements interface (evidence: `src/vash/adapters/cloud/oci/adapter.py`)
- OCI foundation → OCI adapter: uses adapter (evidence: `src/vash/adapters/cloud/oci/foundation.py`)
- OCI guardrails → OCI foundation: uses foundation (evidence: `src/vash/adapters/cloud/oci/guardrails.py`)
- OCI security → OCI foundation: uses foundation (evidence: `src/vash/adapters/cloud/oci/security.py`)
- GitHub forge → Adapter interfaces: implements interface (evidence: `src/vash/adapters/forge/github/adapter.py`)
- CI adapters → Adapter interfaces: implements interface (evidence: `src/vash/adapters/ci/github_actions/adapter.py`)
- PR review → GitHub forge: uses GitHub API (evidence: `src/vash/adapters/forge/github/pr_review.py`)
- PR review → LLM adapters: uses model adapter (evidence: `src/vash/adapters/forge/github/pr_review.py`)
- Project init → Path resolver: resolves paths (evidence: `src/vash/cli/init.py`)
