Redesign file system to avoid conflicts: layered approach with project overrides and global defaults, proper upgrade process

README.md

@@ -174,5 +174,32 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
 - `scripts/vram_detect.sh`: Auto-detects GPU VRAM, RAM, model context window, and framework overhead.
 - `contracts/vram_config.md`: Contract for VRAM-aware task decomposition.
 
+## Layered File System
+
+The framework uses a **layered approach** to file management, with a clear precedence:
+
+1. **Project overrides** (highest precedence): `{project}/.agent-framework/` — contains project-specific customizations
+2. **Global framework** (default): `~/.agent-framework/` — contains the base framework files
+
+**Precedence rule**: If a file exists in the project's `.agent-framework/` directory, the Orchestrator reads it from there. If it doesn't exist, the Orchestrator reads it from the global `~/.agent-framework/` directory.
+
+### What files belong in each layer?
+
+- **Project's `.agent-framework/`**: AGENT.md (project-specific settings like Autopilot mode, rules override), RULES.md (project-specific constraints)
+- **Global `~/.agent-framework/`**: All prompt files, contracts, scripts, config.md, workflow.md
+
+### Upgrading
+
+When you upgrade the global framework (e.g., after pushing bug fixes), existing projects may need their framework files upgraded. Tell the agent:
+
+> "Upgrade the agent-framework for this project."
+
+The agent will:
+1. Compare the project's `.agent-framework/` files with the global `~/.agent-framework/` files
+2. **Customized files** — If the project has customized a file (differs from global), **keep the project's version**
+3. **Outdated files** — If the project's file is identical to the old global version, **update from global**
+4. **New files** — If the global framework has new files, **add them to the project**
+5. Report what was upgraded, added, and skipped
+
 ## Contact & Support
 [Insert Contact Info]