Status:
accepted · ADR-11 · Filed 2026-04-17Decision
CLAUDE.md is reborn as a thin, project-agnostic BIOS file (v2.0.0). It contains NO hardcoded paths, NO PID, NO persona, NO communication style. All paths derive from two env vars:$PROJECT_ROOT (parent of all projects) and $PRISM_ROOT (Prism’s own repo, conventionally $PROJECT_ROOT/Prism). User projects resolve as $PROJECT_ROOT/{project_name}. SOR templates live at $PRISM_ROOT/templates/. Each user project holds a replica of CLAUDE.md (and AGENTS.md, PRISM.md) carrying a bios_version header. On prism_start, the server compares replica version to SOR; major-version mismatch prompts user to run prism_sync_bios. A manual force-sync verb exists for recovery when a user breaks a replica. PID is resolved dynamically via prism_start + project dir name, not hardcoded in the BIOS.
Rationale
The legacy CLAUDE.md (v1.0.0) carried hardcoded paths (X:\DFW\DFWP, C:\DATA\DFW\DFWP) and a hardcoded PID (PID-BFG9N) from the DFWP era. This broke the moment Frank’s work expanded beyond a single project and machine. Symptoms in the live exhibit: the file could not be reused across PrismGR (Windows, C:\Data\PrismGR) and Prism (Mac, /Users/fpn/projects/Prism) without hand-editing; it carried identity for a project that isn’t this one; and its ‘Project Root’ field was doing double duty as both an env pointer and a literal path. Root cause: CLAUDE.md was being used as both BIOS (load-before-everything) and application constitution (project-specific facts) — two jobs that want opposite update cadences. BIOS should be stable, small, OS-agnostic, one file for all projects. Application facts belong in PRISM.md, AGENTS.md, and project metadata inside Prism. The $PROJECT_ROOT/$PRISM_ROOT split mirrors the sprint-1 PRISM_ROOT refactor CC already shipped, extending the same principle to the BIOS layer. SOR/replica with version-pin is the least fragile distribution model: replicas are disposable, SOR is canon, drift is visible instead of silent, and a force-sync verb handles recovery.
Alternatives Considered
Symlink replicas to SOR — rejected because it breaks across OS boundaries, git clones, and WSL/Mac sync; Claude Desktop on Windows handles symlinks unreliably. Keep CLAUDE.md project-specific with a PID — rejected because it forces every project to duplicate BIOS content with only the PID differing, creating a drift surface. Move templates to$PROJECT_ROOT/.prism/ — rejected because it implies templates are OS-level cache rather than a Prism product artifact; hidden-dir placement is surprising. Defer the sync verb and rely only on version-header warnings — rejected because when a user breaks a replica there must be a one-command recovery path.