Project Structure

A map of your project's territory. Know where everything lives.

Overview

A Loaded Vibes project follows a consistent structure that separates framework assets from your application code. Here's what you'll find after running lv create:

Project roottext

my-project/
├── .github/                    # GitHub Copilot & workflow assets
│   ├── agents/                 # Custom AI agent definitions
│   ├── instructions/           # Domain-specific instructions
│   ├── prompts/                # Reusable prompt files
│   ├── toolsets/               # Tool configurations
│   ├── workflows/              # GitHub Actions
│   └── copilot-instructions.md # Global Copilot rules
├── .vscode/                    # VS Code workspace settings
│   ├── settings.json           # Editor configuration
│   ├── extensions.json         # Recommended extensions
│   └── mcp.json                # MCP server configuration
├── .loaded-vibes/              # Framework runtime state
│   ├── state.json              # Current DevCycle state
│   ├── logs/                   # Execution logs (NDJSON)
│   ├── checkpoints/            # Phase checkpoints
│   └── cache/                  # Cached computations
├── docs/                       # Project documentation
│   ├── PRD.md                  # Product requirements
│   ├── TECH_REQUIREMENTS.md    # Technical specifications
│   └── decisions/              # Architecture Decision Records
├── src/                        # Your application code
│   ├── ...                     # (Stack-specific structure)
├── tests/                      # Test files
├── package.json                # Dependencies
└── loaded-vibes.config.json    # Framework configuration

Key Directories

.github/ — Copilot & Automation

Contains all GitHub Copilot customization and GitHub Actions workflows:

.github/
├── agents/                     # AI agent profiles
│   ├── architect.agent.md      # Architecture decisions
│   ├── reviewer.agent.md       # Code review
│   └── debugger.agent.md       # Debugging assistance
├── instructions/               # Stack & domain rules
│   ├── nextjs.instructions.md  # Next.js patterns
│   ├── prisma.instructions.md  # Database conventions
│   └── testing.instructions.md # Test requirements
├── prompts/                    # Reusable prompts
│   ├── feature.prompt.md       # Feature implementation
│   ├── bugfix.prompt.md        # Bug fixing
│   └── refactor.prompt.md      # Refactoring
├── toolsets/                   # Tool configurations
│   └── default.toolset.jsonc   # MCP tool bindings
└── copilot-instructions.md     # Global project rules

✨

Layered instructions

Instructions are loaded hierarchically: global → stack → domain. More specific instructions override general ones without duplicating rules.

.loaded-vibes/ — Runtime State

This directory contains all framework runtime data. It's gitignored by default but can be committed for reproducibility:

.loaded-vibes/
├── state.json                  # Current orchestrator state
├── logs/
│   ├── 2024-01-15-init.ndjson  # DevCycle execution logs
│   └── 2024-01-15-scaffold.ndjson
├── checkpoints/
│   ├── init/                   # Phase snapshots
│   └── scaffold/
├── cache/
│   └── requirements/           # Cached requirement parsing
└── manifests/
    └── installed.json          # Framework version tracking

.vscode/ — Workspace Settings

VS Code workspace configuration that activates framework features:

.vscode/settings.jsonjson

{
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": ".github/copilot-instructions.md" }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    { "file": ".github/instructions/testing.instructions.md" }
  ],
  "editor.formatOnSave": true,
  "typescript.preferences.importModuleSpecifier": "relative"
}

docs/ — Living Documentation

Project documentation that the framework reads and updates:

docs/
├── PRD.md                      # Product requirements (EARS notation)
├── TECH_REQUIREMENTS.md        # Technical specifications
├── decisions/
│   ├── ADR-001-auth.md         # Architecture Decision Records
│   └── ADR-002-api.md
└── summaries/                  # Generated execution summaries
    └── 2024-01-15-feature-auth.md

Configuration Files

loaded-vibes.config.json

The main framework configuration file:

loaded-vibes.config.jsonjson

{
  "version": "1.0.0",
  "stack": "fullstack",
  "features": {
    "ai": { "enabled": true, "provider": "copilot" },
    "telemetry": { "enabled": true, "anonymous": true },
    "upgrades": { "strategy": "merge", "autoBackup": true }
  },
  "devcycles": {
    "active": ["init", "scaffold", "test", "deploy"],
    "custom": []
  },
  "paths": {
    "src": "src",
    "tests": "tests",
    "docs": "docs"
  }
}

package.json scripts

Standard npm scripts for common operations:

package.json (scripts)json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest",
    "lv": "lv",
    "lv:init": "lv devcycle run init",
    "lv:validate": "lv devcycle run validate",
    "lv:deploy": "lv devcycle run deploy"
  }
}

Generated Files

DevCycles generate various files during execution. These are clearly marked with comments indicating their origin:

Example generated file headertypescript

/**
 * @generated by Loaded Vibes
 * @devcycle scaffold
 * @phase implement
 * @timestamp 2024-01-15T10:30:00Z
 *
 * DO NOT EDIT - regenerate with: lv devcycle run scaffold --feature auth
 */

export interface User {
  id: string;
  email: string;
  createdAt: Date;
}

⚠️

Generated file policy

Files marked @generated will be overwritten on the next DevCycle run. If you need to customize them, use the --preserve-custom flag or move custom code to non-generated files.

Gitignore Defaults

The framework sets up sensible gitignore defaults:

.gitignoretext

# Loaded Vibes runtime (optional - commit for reproducibility)
.loaded-vibes/logs/
.loaded-vibes/cache/
.loaded-vibes/checkpoints/

# Keep state and manifests for reproducibility
!.loaded-vibes/state.json
!.loaded-vibes/manifests/

# Node
node_modules/
.next/
dist/

# Environment
.env*.local

Next Steps

Now that you understand the project layout, learn about the three-layer architecture that powers the framework, or dive into DevCycles to understand the development workflows.