Architecture

Three layers. Clear boundaries. No vibes crossing lanes.

The Three Layers

Loaded Vibes uses a strict three-layer architecture to maintain separation of concerns and ensure predictable behavior. Each layer has clear ownership and responsibilities.

📦

Development

Source-of-truth assets: specs, templates, and maintainer configurations. Where the framework itself is authored.

.github/ · .vscode/ · docs/

spec/ · templates/ · decisions/

🚀

Framework

The shipped payload delivered to users. Version-controlled, checksummed, and treated as immutable after installation.

dist/.github/ · dist/.vscode/

dist/cli/ · dist/genaiscript/

⚡

Generated

Output of DevCycle execution: application code, summaries, and runtime state. Managed by the orchestrator.

src/ · tests/

.loaded-vibes/ · *.summary.json

Layer Boundaries

Each layer operates under strict rules to prevent cross-contamination and maintain traceability:

Development → Framework

Development assets reference Framework assets only through templates and manifests
Templates in templates/ seed artifacts in dist/
No direct imports of runtime outputs during authoring

Framework → Generated

Framework provides instructions, prompts, and toolsets
Generated code follows patterns defined in Framework layer
Framework never directly modifies Generated files

Generated → Framework

Generated files can read Framework assets
Generated files never modify Framework assets
Feedback flows through DevCycle execution summaries

⚠️

Boundary violations

Crossing layer boundaries without using proper channels (templates, manifests, DevCycle outputs) will trigger warnings from lv doctor and may cause unpredictable upgrade behavior.

Data Flow

Data flows through the system in a predictable pattern:

┌─────────────────────────────────────────────────────────────┐
│                     DEVELOPMENT LAYER                        │
│  docs/PRD.md → templates/*.template.md → spec/*.spec.md     │
└─────────────────────────────┬───────────────────────────────┘
                              │ Template Expansion
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      FRAMEWORK LAYER                         │
│  dist/.github/ ← prompts, instructions, toolsets, agents   │
│  dist/.vscode/ ← workspace settings, MCP configuration     │
│  dist/cli/     ← CLI commands, dashboard components        │
└─────────────────────────────┬───────────────────────────────┘
                              │ DevCycle Execution
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      GENERATED LAYER                         │
│  src/          ← application code, components, services     │
│  tests/        ← unit tests, integration tests              │
│  .loaded-vibes/ ← state, logs, checkpoints                  │
└─────────────────────────────────────────────────────────────┘

Orchestrator Role

The orchestrator is the central coordinator that manages state transitions and ensures layer integrity:

State Management: Tracks current DevCycle, phase, and checkpoint status
Artifact Resolution: Loads prompts, instructions, and toolsets from the correct layer
Execution Logging: Records all actions in NDJSON format for auditability
Boundary Enforcement: Prevents unauthorized cross-layer modifications

MCP Integration

Model Context Protocol servers provide controlled access to system capabilities:

Server	Purpose	Layer Access
filesystem	File read/write operations	Generated, Framework (read)
git	Version control operations	All layers (read), Generated (write)
memory	Persistent context storage	.loaded-vibes/ only
postgres	Database operations	Generated layer data only
github	GitHub API integration	External service
fetch	HTTP requests	External services
sequentialthinking	Multi-step reasoning	Orchestrator internal

💡

Security boundary

MCP servers operate within the Bad Vibes Firewall. Destructive operations require explicit human approval through checkpoint confirmation.

Next Steps

Now that you understand the architecture, explore DevCycles to learn how the framework orchestrates development workflows across these layers.