Root Documentation: The Foundation

Why Foundation Documents Matter

Foundation documents are the bedrock of VDD. They capture your original vision in a structured format, establishing the core truths that guide every decision throughout the project.

These three documents form a hierarchy of intent:

project_description.md - What we’re building and why
philosophy.md - Core principles and beliefs driving decisions
known_requirements.md - Specific requirements and constraints

AI reads these first in every session. They become the lens through which AI interprets all subsequent project development.

The Three Foundation Documents

1. project_description.md - The North Star

This document transforms scattered project information into structured understanding. It’s the single source of truth about what you’re building.

Core Questions to Answer:

What are we building?
What are the various scopes of this project?
What problem are we solving?
What does success look like?
Who will use it and why?

2. philosophy.md - The Soul

Philosophy captures the intangible aspects that shape every decision. It’s about values, not features. This document prevents technically correct but visionally/spiritually wrong implementations.

Core Question to Answer:

what is the philosophy of this project?

3. known_requirements.md - The Contract

Requirements translate vision into concrete constraints. They define the boundaries within which AI must operate.