dot-bep

What is this?

An open .bep data format designed to author and execute BIM Execution Plans. Its used to define, distribute and track a BIM Execution Plan programmatically. The goal is to replace text-based BEPs with a structured format that enables:

• Dynamic frontends for navigating BEPs.
• Integration with BIM apps for actionable workflows and automatic validations.
• An MCP for managing the BEP in natural language.
• Deriving information like responsibility matrices, TIDPs, MIDPs, deliverable naming codes, etc.
• A transparent version history.

---

The .bep format

A .bep file is a zip with the following structure:

project.bep
├── bep.json                          ← current state (latest version)
├── changelog.json                    ← { current, versions[] }
├── baseline/                         ← last committed state (reference for diffs and discard)
│   ├── bep.json                      ← JSON snapshot of the previous version (cache for commits)
│   └── standards/
│       └── {standard-id}.md          ← baseline of each .md at the time of the last commit
├── changelog/
│   ├── v0.0.json                     ← initial snapshot (terminus of the diff chain)
│   ├── v0.1.diff.json                ← inverse diff: how to go from v0.1 → v0.0
│   ├── v1.0.diff.json                ← inverse diff: how to go from v1.0 → v0.x
│   └── standards/
│       └── {standard-id}/
│           └── v0.3.md               ← .md snapshot only if it changed in that version
├── ids/
│   └── walls-detailed-design.ids
├── ids-reports/
│   └── walls-detailed-design-report.html
├── standards/
│   └── {uuid}.md
├── guides/
│   └── ifc-guide.pdf
├── memory.md                         ← collective project memory (not versioned)
└── skill.md                          ← LLM behavior for this project (not versioned)

---

Key design decisions

• Everything is flat with ID-based references — no deeply nested objects. teams have memberEmails: string[], not nested Member objects.
• Email is the member ID — naturally unique within a project context.
• Team ID is its originator code — 3 uppercase letters (e.g. "ARA") used in the file naming scheme.
• LBS node, discipline and document type IDs are also their naming codes (e.g. "BES", "P01", "ARQ", "M3D").
• Milestones are a flat array at the BEP root with a phaseId reference. Deliverables reference a milestone via milestoneId — the deliverable phase is derived from milestone.phaseId. dueDate on the deliverable is optional; if absent, milestone.date is used.
• LBS (Location Breakdown Structure) is a flat tree of LBSNode[] with lbsNodeIds?: string[] for children. Root nodes must be type: "zone". Nodes of type: "location" cannot have zone children. Deliverables reference an LBS node via lbsNodeId?: string; zone and location codes for naming are derived from the node's position in the tree.
• The naming code is derived by combining: project.code + team.id + zoneCode + locationCode + documentType.id + discipline.id + sequence number. zoneCode/locationCode are resolved from lbsNodeId. If absent → XXX/XXX; if root → ZZZ/ZZZ; if non-root zone → id/ZZZ; if location → ancestor-zone-id/id.
• .ids and .md files are referenced by relative path from bep.json (standard.contentPath, loin.milestones[].idsPath). The workflow diagram is a FlowDiagram JSON embedded directly in bep.json; it is used to generate the graph.
• bep.json always reflects the current state (latest version). History is reconstructed by applying inverse diffs backwards.
• Two-number versions {major}.{minor} — no full semver.
• notes[] is the human voice for humans — general footnote-style annotations, no special lifecycle. Structure: { id, message, memberEmail, createdAt } all required. Added and removed freely.
• flags[] is the LLM's voice toward the process — technical, objective, ephemeral observations with no lifecycle. Structure: { id, entity, entityId, severity, message, generatedAt }. Severities:
  • info — Technical observation with no impact. "Informational only. No impact on project execution."
  • warning — Latent risk that doesn't break the BEP but may materialize. "The BEP still works, but something could become a problem. Without attention, it may affect the project later."
  • blocking — Information gap that breaks BEP coherence; elements depending on this become orphaned or ill-defined. "Critical information is missing. Without resolving it, this element creates inconsistencies in the BEP and everything that depends on it."
• memory.md is the collective project memory — lives at the zip root, outside the version system, always in its latest state. The LLM updates it proactively (decisions made, reasons a flag was dismissed, client constraints, etc.) and when the user requests it.
• skill.md defines the LLM behavior for this project — prescriptive and stable, set by the BIM Manager at project start. Contains how to write standards, criteria for workflows and analysis, analyze_bep focus, editorial restrictions, project conventions. The difference with memory.md: skill.md says how to act; memory.md says what has happened.

The BEP data is designed to answer:

Question	Answer	BEP section
What is this document about?	Introduction to BIM, the BEP and why it's being done	Introduction
What project are we working on?	Project information and context	Project context
Who will participate?	Participant directory with specializations	Project context
What will each participant do?	Responsibility matrix	Project context
What will we do and why?	BIM uses + BIM objectives + client and project needs	BIM uses and objectives
What do we need to do it?	Human resource competencies + software + hardware	BIM uses and objectives
What is the model scope?	LOD and LOI matrix	Information requirements
How and with what guidelines will we do it?	Processes + workflows + standards	Standards, guides and workflows
How do we ensure success?	Key Performance Indicators (KPIs)	Indicators
Who delivers what and when?	TIDP + MIDP + Schedule + Project phases	Deliverables

---

What can be derived at runtime (no extra data)

• Naming code for any deliverable
• Responsibility matrix (crossing FlowNode RACI role IDs with roles, members and teams)
• TIDP per team (filtering deliverables by responsibleId)
• MIDP (all deliverables)
• Schedule with dependencies (predecessorId)
• ISO 19650 team diagram (graph of teams by isoRole)
• Any historical version (applying inverse diffs backwards from bep.json)

---

Versioning

Version scheme

The format is {major}.{minor} (e.g. 0.0, 0.4, 1.0, 2.3). No three-part semver.

Tool	Result	Approvers
commit_patch	1.3 → 1.4	Not required
commit_version	1.3 → 2.0 (resets minor to 0)	Required (approvedBy: string[])

• Every new BEP starts at v0.0. Versions 0.x, 1.x, etc. are WIP; 1.0, 2.0, etc. are official deliveries.

Diff model

Inverse diffs are used: each version stores how to go back to the previous state (not how to reach the next one).

bep.json (v1.3)  →  apply v1.3.diff  →  v1.2
v1.2             →  apply v1.2.diff  →  v1.1
v1.1             →  apply v1.1.diff  →  v1.0
v1.0             →  apply v1.0.diff  →  v0.x
...              →  apply v0.1.diff  →  v0.0  (load changelog/v0.0.json)

Advantage: reading the current version is always trivial (it's bep.json); older versions are reconstructed by applying diffs backwards.

baseline/

The baseline/ folder contains the last committed state and is the reference for detecting pending changes and discarding them.

baseline/bep.json — JSON snapshot of the previous version. Used to generate the inverse diff without having to reconstruct history:

inverseDiff = compare(bep.json, baseline/bep.json)
              → "how to go from the new version back to the previous one"

baseline/standards/{id}.md — baseline of each .md at the time of the last commit. Used to detect changes in standard content and restore the .md to the committed state.

Folder separation:

• Root → live current state (bep.json, standards/)
• baseline/ → last committed reference (for diffs, change detection and discard)
• changelog/ → immutable history (terminus + inverse diffs + historical snapshots)

baseline/standards/ sync invariant

baseline/standards/{id}.md must always match standards/{uuid}.md after any operation that modifies .md files. If this sync breaks, false positives will be reported and incorrect content will be restored.

.md file snapshots (standards)

standards/{uuid}.md files are not JSON and cannot be diffed. They are managed with copy-on-write:

• On commit, each standards/{uuid}.md is compared against the latest snapshot in changelog/standards/{id}/.
• If it changed (or no prior snapshot exists), it is saved as changelog/standards/{id}/v{new-version}.md.
• To resolve a standard's content at a historical version: find the snapshot with the highest version ≤ target version.
• If no snapshot ≤ target version exists, the file is assumed unchanged since the beginning and the current file is returned.

baseline/standards/{id}.md is updated on every commit alongside baseline/bep.json.

---

Subprojects

core/ — @dotbep/core

Publishable library with all business logic: Zod schema, entity CRUD with referential integrity, version history (inverse diffs, snapshots), deliverable naming and LBS utilities.

front/ — @dotbep/front

Lit viewer that renders the BEP in the browser. Integrates with the MCP via WebSocket to update in real time as the user edits the BEP from Claude Desktop.

mcp/ — @dotbep/mcp

MCP server with ~116 tools for BEP authoring via natural language. Includes an HTTP/WS server that serves the frontend viewer. Connects to Claude Desktop pointing to mcp/dist/index.js.