# foryourhealth111-pixel/vibe-skills architecture

> Architecture diagram of the GitHub repository foryourhealth111-pixel/vibe-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/foryourhealth111-pixel/vibe-skills
- Repository: https://github.com/foryourhealth111-pixel/vibe-skills

## Overview

VibeSkills is a local-Skill discovery and workflow-orchestration product, exposed through a CLI and installed into supported host environments. Its central workflow is to interpret a task, find and select relevant installed Skills, plan dependent work, execute it, and verify deliverables. The graph also shows installation and shared contracts. The README documents the user-facing workflow and capabilities; source-level edges are limited to relationships visible in excerpts or SOURCE INDEX references, so some documented but unsampled subsystems have no internal call links.

Main entry points: [`packages/runtime-core/src/vgo_runtime/kernel/loop.py`](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/loop.py) (Workflow Loop), [`packages/runtime-core/src/vgo_runtime/kernel/skill_index.py`](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/skill_index.py) (Skill Index), [`apps/vgo-cli/src/vgo_cli/main.py`](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/main.py) (VibeSkills CLI), [`apps/vgo-cli/src/vgo_cli/commands.py`](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/commands.py) (CLI Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["VibeSkills CLI<br/>[main.py]"]
  node_commands["CLI Commands<br/>[commands.py]"]
  node_canonical["Canonical Entry<br/>[canonical_entry.py]"]
end

subgraph group_routing["Skill Routing"]
  node_router["Task Router"]
  node_skill_index[("Skill Index<br/>[skill_index.py]")]
  node_host_roots["Host Skill Roots"]
  node_capability["Capability Bridge"]
end

subgraph group_runtime["Workflow Runtime"]
  node_workflow["Workflow Loop<br/>[loop.py]"]
  node_planner["Work Planner<br/>[planner.py]"]
  node_executor["Work Executor<br/>[executor.py]"]
  node_verifier["Deliverable Verifier<br/>[verifier.py]"]
  node_artifacts["Artifact Contract"]
  node_skills["Bundled Skills"]
end

subgraph group_install["Host Installation"]
  node_installer["Installer Runtime<br/>[install_runtime.py]"]
  node_adapter_registry[("Adapter Registry")]
  node_uninstaller["Uninstall Service"]
end

subgraph group_contracts["Shared Contracts"]
  node_contracts["Host and Target Contracts"]
end

node_user(("User"))
node_host["Host Environment"]

node_user -.->|"invokes"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -.->|"launches workflow"| node_canonical
node_canonical -->|"invokes"| node_workflow
node_workflow -->|"uses"| node_planner
node_workflow -->|"uses"| node_executor
node_workflow -->|"uses"| node_verifier
node_workflow -->|"uses"| node_skill_index
node_workflow -->|"uses"| node_host_roots
node_workflow -->|"uses"| node_artifacts
node_router -->|"uses"| node_skill_index
node_skill_index -->|"uses"| node_capability
node_skill_index -->|"uses"| node_host_roots
node_user -.->|"requests installation"| node_installer
node_installer -.->|"installs into"| node_host
node_uninstaller -->|"loads"| node_adapter_registry
node_adapter_registry -->|"uses shared definitions"| node_contracts
node_user -.->|"uses Skills"| node_host

click node_cli "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/main.py"
click node_commands "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/commands.py"
click node_canonical "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/canonical_entry.py"
click node_router "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/router_contract_runtime.py"
click node_skill_index "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/skill_index.py"
click node_host_roots "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/host_skill_roots.py"
click node_capability "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/capability_bridge.py"
click node_workflow "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/loop.py"
click node_planner "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/planner.py"
click node_executor "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/executor.py"
click node_verifier "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/verifier.py"
click node_artifacts "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/artifact_contract.py"
click node_skills "https://github.com/foryourhealth111-pixel/vibe-skills/tree/main/bundled/skills"
click node_installer "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/install_runtime.py"
click node_adapter_registry "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/adapter_registry.py"
click node_uninstaller "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/uninstall_service.py"
click node_contracts "https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/contracts/src/vgo_contracts/canonical_vibe_contract.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_commands,node_canonical,node_user toneBlue
class node_router,node_skill_index,node_host_roots,node_capability toneAmber
class node_workflow,node_planner,node_executor,node_verifier,node_artifacts,node_skills toneMint
class node_installer,node_adapter_registry,node_uninstaller toneRose
class node_contracts,node_host toneIndigo
```

## Components

### User Entry

- [VibeSkills CLI](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/main.py): `apps/vgo-cli/src/vgo_cli/main.py`
- [CLI Commands](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/apps/vgo-cli/src/vgo_cli/commands.py): `apps/vgo-cli/src/vgo_cli/commands.py`
- [Canonical Entry](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/canonical_entry.py): `packages/runtime-core/src/vgo_runtime/canonical_entry.py`

### Skill Routing

- [Task Router](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/router_contract_runtime.py): `packages/runtime-core/src/vgo_runtime/router_contract_runtime.py`
- [Skill Index](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/skill_index.py): `packages/runtime-core/src/vgo_runtime/kernel/skill_index.py`
- [Host Skill Roots](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/host_skill_roots.py): `packages/runtime-core/src/vgo_runtime/kernel/host_skill_roots.py`
- [Capability Bridge](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/capability_bridge.py): `packages/runtime-core/src/vgo_runtime/kernel/capability_bridge.py`

### Workflow Runtime

- [Workflow Loop](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/loop.py): `packages/runtime-core/src/vgo_runtime/kernel/loop.py`
- [Work Planner](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/planner.py): `packages/runtime-core/src/vgo_runtime/kernel/planner.py`
- [Work Executor](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/executor.py): `packages/runtime-core/src/vgo_runtime/kernel/executor.py`
- [Deliverable Verifier](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/kernel/verifier.py): `packages/runtime-core/src/vgo_runtime/kernel/verifier.py`
- [Artifact Contract](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/runtime-core/src/vgo_runtime/artifact_contract.py): `packages/runtime-core/src/vgo_runtime/artifact_contract.py`
- [Bundled Skills](https://github.com/foryourhealth111-pixel/vibe-skills/tree/main/bundled/skills): `bundled/skills`

### Host Installation

- [Installer Runtime](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/install_runtime.py): `packages/installer-core/src/vgo_installer/install_runtime.py`
- [Adapter Registry](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/adapter_registry.py): `packages/installer-core/src/vgo_installer/adapter_registry.py`
- [Uninstall Service](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/installer-core/src/vgo_installer/uninstall_service.py): `packages/installer-core/src/vgo_installer/uninstall_service.py`

### Shared Contracts

- [Host and Target Contracts](https://github.com/foryourhealth111-pixel/vibe-skills/blob/main/packages/contracts/src/vgo_contracts/canonical_vibe_contract.py): `packages/contracts/src/vgo_contracts/canonical_vibe_contract.py`

### Other components

- **User**
- **Host Environment**

## Connections

- User → VibeSkills CLI: invokes (evidence: `README.md`)
- VibeSkills CLI → CLI Commands: dispatches (evidence: `apps/vgo-cli/src/vgo_cli/main.py`)
- CLI Commands → Canonical Entry: launches workflow
- Canonical Entry → Workflow Loop: invokes (evidence: `packages/runtime-core/src/vgo_runtime/canonical_entry.py`)
- Workflow Loop → Work Planner: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Workflow Loop → Work Executor: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Workflow Loop → Deliverable Verifier: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Workflow Loop → Skill Index: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Workflow Loop → Host Skill Roots: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Workflow Loop → Artifact Contract: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/loop.py`)
- Task Router → Skill Index: uses (evidence: `packages/runtime-core/src/vgo_runtime/router_contract_runtime.py`)
- Skill Index → Capability Bridge: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/skill_index.py`)
- Skill Index → Host Skill Roots: uses (evidence: `packages/runtime-core/src/vgo_runtime/kernel/skill_index.py`)
- User → Installer Runtime: requests installation (evidence: `README.md`)
- Installer Runtime → Host Environment: installs into (evidence: `README.md`)
- Uninstall Service → Adapter Registry: loads (evidence: `packages/installer-core/src/vgo_installer/uninstall_service.py`)
- Adapter Registry → Host and Target Contracts: uses shared definitions (evidence: `packages/installer-core/src/vgo_installer/adapter_registry.py`)
- User → Host Environment: uses Skills (evidence: `README.md`)
