VDK Ecosystem Overview

VDK is organized as a contract-driven system where each component has a strict role. The ordering is intentional and required for consistency.

Required Operating Order

1. ai-context-schema - defines canonical blueprint semantics
2. VDK-Blueprints - curated canonical inventory
3. VDK-CLI - retrieval, adaptation, and deployment engine
4. VDK-Hub - discovery and distribution surface
5. VDK-Wiki - documentation surface

If behavior conflicts appear, CLI runtime behavior is the source of truth for execution semantics.

Why CLI Is the Ecosystem Heart

VDK-CLI is the runtime interpreter that decides:

• which blueprints are selected,
• how candidates are ranked,
• whether adaptation is lossless, lossy, or unsupported,
• and how deployment is executed deterministically.

Hub and Wiki must mirror this behavior; they should not redefine retrieval/deployment rules.

Standardized Curated Blueprint Library

The blueprint library is intentionally curated to maximize signal and avoid noise.

Canonical kinds

Every blueprint uses one canonical kind:

• project-memory
• conditional-rule
• skill
• command
• workflow
• agent
• hook
• mcp-integration
• plugin-distribution

Specificity layers

Each blueprint also has a reuse layer:

• L0 Foundation Generic
• L1 Language/Framework
• L2 Stack/Domain Pattern
• L3 Workspace/Organization Specific
• L4 Provenance Variant

Default retrieval uses a curated blend of L0-L3. L4 is excluded unless explicitly requested.

End-to-End Deployment Flow

schema contract -> curated inventory -> CLI selection/adaptation -> target carrier files

Typical runtime flow:

1. Detect project stack.
2. Search curated inventory by canonical metadata.
3. Select generic + specific candidates.
4. Adapt to tool-native carrier format.
5. Deploy into project directories with deterministic output.

Command-Oriented User Flow

Use CLI deployment as the installation mechanism:

• vdk search --kind skill --platform claude-code
• vdk search --query nextjs --specificity L2
• vdk deploy <blueprint-id>

This ensures installation behavior is consistent across local use, Hub-assisted discovery, and documentation guidance.

Component Responsibilities

ai-context-schema

• Own canonical taxonomy and metadata semantics.
• Define adaptation/equivalence vocabulary.

VDK-Blueprints

• Maintain schema-valid curated artifacts.
• Keep generic and specific coverage balanced.

VDK-CLI

• Enforce retrieval and deployment policy.
• Emit explicit adaptation outcomes.

VDK-Hub

• Provide synchronized browse/filter/install surfaces.
• Reflect CLI defaults (L0-L3, optional L4).

VDK-Wiki

• Explain contract and operational behavior.
• Avoid introducing alternate runtime semantics.