# eddlev/vm4ai-air-kit architecture

> Architecture diagram of the GitHub repository eddlev/vm4ai-air-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eddlev/vm4ai-air-kit
- Repository: https://github.com/eddlev/vm4ai-air-kit
- Video tour (about a minute): https://gitdiagram.com/eddlev/vm4ai-air-kit/video

## Overview

AIR is a prompt-based framework for carrying structured AI project work across conversations and compatible platforms, not a standalone service stack. The principal workflow loads the Foundation, onboards a project, maintains an active task and recorded evidence, applies approval boundaries to material actions, then carries project state forward through a validated Handoff. Route and Specialist catalogs support discovery; Specialist packages add focused capabilities. The README and tree establish these product branches. Sampled validators corroborate contract and Handoff boundaries, but do not expose the complete prompt runtime, so uncertain internal wiring is omitted.

Main entry points: [`catalog/AIR_SPECIALIST_PACKAGE_INDEX.json`](https://github.com/eddlev/vm4ai-air-kit/blob/main/catalog/AIR_SPECIALIST_PACKAGE_INDEX.json) (Specialist Package Index), [`prompts/AIR_CORE_RUNTIME.md`](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md) (Core Runtime), [`prompts/AIR_CONTROL_SURFACE.md`](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CONTROL_SURFACE.md) (Control Surface), [`prompts/AIR_DEFAULT_STARTER_PROFILE.json`](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_DEFAULT_STARTER_PROFILE.json) (Starter Profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_foundation["Foundation Runtime"]
  node_core["Core Runtime"]
  node_control["Control Surface"]
  node_governance["Governance Rules<br/>[AIR_GOV.md]"]
  node_starter["Starter Profile"]
  node_approval["Approval Boundaries"]
end

subgraph group_project["Project Continuity"]
  node_projectstate["Project State"]
  node_activework["Active Task"]
  node_evidence["Evidence and Blockers"]
  node_handoff["Handoff Card"]
end

subgraph group_discovery["Capability Discovery"]
  node_route["Runtime Route Map"]
  node_index["Specialist Package Index"]
end

subgraph group_specialists["Specialist Packages"]
  node_capability["Capability Ecology"]
  node_govspec["AI Governance"]
  node_grounding["Grounding"]
  node_copywriting["Public Copywriting"]
  node_verification["Specification Verification"]
end

node_human(("Human"))
node_platform(("Compatible AI Platform"))

node_human -->|"starts project"| node_platform
node_platform -->|"loads foundation"| node_core
node_platform -->|"loads foundation"| node_control
node_platform -->|"loads foundation"| node_governance
node_platform -->|"loads foundation"| node_starter
node_starter -->|"supports onboarding"| node_core
node_core -->|"frames project"| node_projectstate
node_core -->|"organizes work"| node_activework
node_activework -->|"records findings"| node_evidence
node_control -->|"defines approval"| node_approval
node_human -->|"approves scope"| node_approval
node_projectstate -->|"carries recorded state"| node_handoff
node_handoff -->|"restores for validation"| node_platform
node_platform -.->|"consults routes"| node_route
node_platform -.->|"discovers packages"| node_index
node_index -.->|"lists package"| node_capability
node_index -.->|"lists package"| node_govspec
node_index -.->|"lists package"| node_grounding
node_index -.->|"lists package"| node_copywriting
node_index -.->|"lists package"| node_verification

click node_core "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md"
click node_control "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CONTROL_SURFACE.md"
click node_governance "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_GOV.md"
click node_starter "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_DEFAULT_STARTER_PROFILE.json"
click node_projectstate "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md"
click node_activework "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md"
click node_evidence "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md"
click node_approval "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CONTROL_SURFACE.md"
click node_handoff "https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_HANDOFF_CARD_TEMPLATE.json"
click node_route "https://github.com/eddlev/vm4ai-air-kit/blob/main/catalog/AIR_RUNTIME_ROUTE_MAP.json"
click node_index "https://github.com/eddlev/vm4ai-air-kit/blob/main/catalog/AIR_SPECIALIST_PACKAGE_INDEX.json"
click node_capability "https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/capability%20ecology%20architect/AIR_CAPABILITY_ECOLOGY_ARCHITECT.json"
click node_govspec "https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/governance%20specialist/AIR_AI_GOVERNANCE_SPECIALIST.json"
click node_grounding "https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/grounding%20specialist/AIR_GROUNDING_SPECIALIST.json"
click node_copywriting "https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/public%20surface%20copywriting%20specialist/AIR_PUBLIC_SURFACE_COPYWRITING_SPECIALIST.json"
click node_verification "https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/specification%20first%20verification%20specialist/AIR_SPECIFICATION_FIRST_VERIFICATION_SPECIALIST.json"

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_core,node_control,node_governance,node_starter,node_approval toneBlue
class node_projectstate,node_activework,node_evidence,node_handoff toneAmber
class node_route,node_index toneMint
class node_capability,node_govspec,node_grounding,node_copywriting,node_verification toneRose
class node_human,node_platform toneIndigo
```

## Components

### Foundation Runtime

- [Core Runtime](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md): `prompts/AIR_CORE_RUNTIME.md`
- [Control Surface](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CONTROL_SURFACE.md): `prompts/AIR_CONTROL_SURFACE.md`
- [Governance Rules](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_GOV.md): `prompts/AIR_GOV.md`
- [Starter Profile](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_DEFAULT_STARTER_PROFILE.json): `prompts/AIR_DEFAULT_STARTER_PROFILE.json`
- [Approval Boundaries](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CONTROL_SURFACE.md): `prompts/AIR_CONTROL_SURFACE.md`

### Project Continuity

- [Project State](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md): `prompts/AIR_CORE_RUNTIME.md`
- [Active Task](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md): `prompts/AIR_CORE_RUNTIME.md`
- [Evidence and Blockers](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_CORE_RUNTIME.md): `prompts/AIR_CORE_RUNTIME.md`
- [Handoff Card](https://github.com/eddlev/vm4ai-air-kit/blob/main/prompts/AIR_HANDOFF_CARD_TEMPLATE.json): `prompts/AIR_HANDOFF_CARD_TEMPLATE.json`

### Capability Discovery

- [Runtime Route Map](https://github.com/eddlev/vm4ai-air-kit/blob/main/catalog/AIR_RUNTIME_ROUTE_MAP.json): `catalog/AIR_RUNTIME_ROUTE_MAP.json`
- [Specialist Package Index](https://github.com/eddlev/vm4ai-air-kit/blob/main/catalog/AIR_SPECIALIST_PACKAGE_INDEX.json): `catalog/AIR_SPECIALIST_PACKAGE_INDEX.json`

### Specialist Packages

- [Capability Ecology](https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/capability%20ecology%20architect/AIR_CAPABILITY_ECOLOGY_ARCHITECT.json): `profiles/capability ecology architect/AIR_CAPABILITY_ECOLOGY_ARCHITECT.json`
- [AI Governance](https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/governance%20specialist/AIR_AI_GOVERNANCE_SPECIALIST.json): `profiles/governance specialist/AIR_AI_GOVERNANCE_SPECIALIST.json`
- [Grounding](https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/grounding%20specialist/AIR_GROUNDING_SPECIALIST.json): `profiles/grounding specialist/AIR_GROUNDING_SPECIALIST.json`
- [Public Copywriting](https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/public%20surface%20copywriting%20specialist/AIR_PUBLIC_SURFACE_COPYWRITING_SPECIALIST.json): `profiles/public surface copywriting specialist/AIR_PUBLIC_SURFACE_COPYWRITING_SPECIALIST.json`
- [Specification Verification](https://github.com/eddlev/vm4ai-air-kit/blob/main/profiles/specification%20first%20verification%20specialist/AIR_SPECIFICATION_FIRST_VERIFICATION_SPECIALIST.json): `profiles/specification first verification specialist/AIR_SPECIFICATION_FIRST_VERIFICATION_SPECIALIST.json`

### Other components

- **Human**
- **Compatible AI Platform**

## Connections

- Human → Compatible AI Platform: starts project
- Compatible AI Platform → Core Runtime: loads foundation
- Compatible AI Platform → Control Surface: loads foundation
- Compatible AI Platform → Governance Rules: loads foundation
- Compatible AI Platform → Starter Profile: loads foundation
- Starter Profile → Core Runtime: supports onboarding
- Core Runtime → Project State: frames project
- Core Runtime → Active Task: organizes work
- Active Task → Evidence and Blockers: records findings
- Control Surface → Approval Boundaries: defines approval
- Human → Approval Boundaries: approves scope
- Project State → Handoff Card: carries recorded state
- Handoff Card → Compatible AI Platform: restores for validation
- Compatible AI Platform → Runtime Route Map: consults routes
- Compatible AI Platform → Specialist Package Index: discovers packages
- Specialist Package Index → Capability Ecology: lists package
- Specialist Package Index → AI Governance: lists package
- Specialist Package Index → Grounding: lists package
- Specialist Package Index → Public Copywriting: lists package
- Specialist Package Index → Specification Verification: lists package