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]

prompts/compaction.md

@@ -1,8 +1,8 @@
 You are performing a compaction pass on the agent's rules and skills.
 
 ## Read These Files
-1. {project}/.agent-framework/RULES.md
+1. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
-2. {project}/.agent-framework/AGENT.md
+2. {project}/.agent-framework/AGENT.md (if exists — project override) OR ~/.agent-framework/AGENT.md (global default) — project agent config
 3. Any accumulated notes or previous RULES.md versions in the project
 
 ## Task

prompts/decompose.md

@@ -5,10 +5,10 @@ Your only job is to take a completed SPEC.md and break it into the smallest poss
 ## Read These Files
 
 1. {project}/tasks/{task-name}/SPEC.md
-2. {project}/.agent-framework/RULES.md
+2. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
 3. ~/.agent-framework/config.md — Global framework configuration (VRAM, model settings)
-4. {project}/.agent-framework/AGENT.md (if exists — for model override)
+4. {project}/.agent-framework/AGENT.md (if exists — project override) OR ~/.agent-framework/AGENT.md (global default) — project agent config
-5. {project}/.agent-framework/scripts/vram_detect.sh (if exists — for VRAM detection)
+5. {project}/.agent-framework/scripts/vram_detect.sh (if exists — project override) OR ~/.agent-framework/scripts/vram_detect.sh (global default) — VRAM detection
 
 ## Task
 

prompts/design.md

@@ -5,7 +5,7 @@ Your job is to create a clear, actionable design for the project based on the sp
 ## Read These Files
 
 1. {project}/tasks/{task-name}/SPEC.md
-2. {project}/.agent-framework/RULES.md
+2. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
 
 ## Task
 

prompts/implement.md

@@ -3,8 +3,8 @@ You are in implementation mode.
 ## Read These Files
 
 1. {project}/tasks/{task-name}/SPEC.md
-2. {project}/.agent-framework/RULES.md
+2. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
-3. {project}/.agent-framework/AGENT.md (if exists)
+3. {project}/.agent-framework/AGENT.md (if exists — project override) OR ~/.agent-framework/AGENT.md (global default) — project agent config
 4. {project}/tasks/{task-name}/{task-name}_CONTRACT.md (if exists)
 5. {project}/tasks/{task-name}/DESIGN.md (if exists)
 6. {project}/tasks/{task-name}/TEST_PLAN.md (if exists)

prompts/onboarding.md

@@ -6,8 +6,8 @@ Your only job is to set up the minimal agent framework structure in the target p
 
 1. ~/.agent-framework/AGENT.md — global framework router
 2. ~/.agent-framework/ONBOARDING.md — human reference for drop-in vs from-scratch scenarios
-3. {project}/.agent-framework/AGENT.md (if it exists)
+3. {project}/.agent-framework/AGENT.md (if it exists — project override)
-4. {project}/.agent-framework/RULES.md (if it exists)
+4. {project}/.agent-framework/RULES.md (if it exists — project override)
 5. ~/.agent-framework/scripts/vram_detect.sh (if exists — for VRAM detection)
 
 ## Task
@@ -19,24 +19,28 @@ Your only job is to set up the minimal agent framework structure in the target p
 ### Step 0: Check if Framework Needs Upgrade
 
 Before proceeding, check if the project is running an older version of the framework:
-1. Check if `~/.agent-framework/prompts/workflow.md` exists and compare its content with the current global framework's workflow.md.
+1. Compare the project's `.agent-framework/` files with the global `~/.agent-framework/` files.
-2. If the project's `~/.agent-framework/` has a `workflow.md` that differs from the current global version, the project needs an upgrade.
+2. If the project's `.agent-framework/` has a file that differs from the current global version, the project needs an upgrade.
-3. If the project's `~/.agent-framework/` is missing new prompt files (e.g., `doc_review.md`, `test_design.md`), the project needs an upgrade.
+3. If the project's `.agent-framework/` is missing files that exist in the global framework (e.g., new prompt files like `doc_review.md`, `test_design.md`), the project needs an upgrade.
 4. If an upgrade is needed, report it to the user and offer to upgrade the project's framework files.
 
+**Precedence**: The project's `.agent-framework/` files override the global `~/.agent-framework/` files. The Orchestrator reads from the project's directory first, then falls back to the global directory.
+
 ### Step 1: Discovery
 
 1. Check if {project}/.agent-framework/ exists. If not, create it.
 2. Ensure exactly two files exist inside it:
-   - AGENT.md (project-level router)
+   - AGENT.md (project-level router — project override of the global framework)
-   - RULES.md (project-specific constraints)
+   - RULES.md (project-specific constraints — project override of the global framework)
 3. If the files are missing or empty, create minimal versions:
    - AGENT.md should point to the global framework and list any project-specific additions. By default, Autopilot is Enabled — the Orchestrator will drive tasks through all phases automatically. Set Autopilot: Disabled if you want to manually run each phase.
    - RULES.md should contain only hard, non-negotiable constraints for this project.
-4. Read the global ~/.agent-framework/AGENT.md and the new project-level AGENT.md + RULES.md.
+4. Read the project's AGENT.md + RULES.md, then read the global ~/.agent-framework/AGENT.md for comparison.
 5. Explore the project root at a high level (ls, key directories, README if present).
 6. Produce a short onboarding report.
 
+**Important**: The project's `.agent-framework/` directory should only contain AGENT.md and RULES.md. All other framework files (prompts, contracts, scripts) are read from the global `~/.agent-framework/` directory. The project's directory is the override layer — if a file exists in both, the project's version takes precedence.
+
 ### Step 2: VRAM Configuration
 
 Check if VRAM configuration is available in `~/.agent-framework/config.md`:
@@ -96,17 +100,56 @@ Do not begin any research, implementation, or bug-finding tasks.
 
 When a user asks to "upgrade the agent-framework for this project," the agent should:
 
-1. Compare the project's `~/.agent-framework/` files with the global `~/.agent-framework/` files.
+### Upgrade Process
-2. Identify any missing files in the project's framework directory:
-   - New prompt files (e.g., `doc_review.md`, `test_design.md`)
-   - Updated `workflow.md` (state machine changes)
-   - New contract files
-3. Add the missing files from the global framework into the project's framework directory.
-4. Do NOT overwrite existing project-specific files (AGENT.md, RULES.md).
-5. Report what was upgraded and what was already up to date.
 
-Example upgrade scenario:
+1. **Compare the project's `~/.agent-framework/` files with the global `~/.agent-framework/` files.**
+   - For each file in the global framework, check if it exists in the project's framework.
+   - If it exists in both, compare their content.
+
+2. **Identify three categories of files:**
+   - **Customized** — The file exists in both, but they differ. The project has customized it. **Keep the project's version.**
+   - **Outdated** — The file exists in both, but they are identical. The project hasn't customized it, but the global version has changed. **Update from global.**
+   - **New** — The file exists in the global framework but not in the project. **Add from global.**
+
+3. **Apply upgrades:**
+   - For **Outdated** files: Copy from the global framework to the project's framework (update the project's version).
+   - For **New** files: Copy from the global framework to the project's framework (add the file).
+   - For **Customized** files: **Do NOT overwrite** — keep the project's version and report it as "skipped (customized)."
+
+4. **Report what was upgraded and what was already up to date.**
+
+### Upgrade Report Format
+
+The agent should report:
+- **Upgraded**: Files that were updated from the global framework (Outdated → Upgraded)
+- **Added**: New files added from the global framework (New → Added)
+- **Skipped**: Files that were customized in the project and not overwritten (Customized → Skipped)
+- **Already up to date**: Files that were already identical (shouldn't happen, but report for completeness)
+
+### Example Upgrade Scenarios
+
+**Scenario 1: New file added globally**
 - User says: "Upgrade the agent-framework for this project"
 - Agent detects that `prompts/test_design.md` is missing from the project's framework
 - Agent copies `prompts/test_design.md` from the global framework into the project's framework
 - Agent reports: "Upgraded: Added prompts/test_design.md. Your framework is now up to date."
+
+**Scenario 2: Global file changed, project hasn't customized it**
+- User says: "Upgrade the agent-framework for this project"
+- Agent detects that `prompts/orchestrate.md` has changed in the global framework, and the project's version is identical to the old global version
+- Agent copies `prompts/orchestrate.md` from the global framework into the project's framework
+- Agent reports: "Upgraded: Updated prompts/orchestrate.md. Your framework is now up to date."
+
+**Scenario 3: Global file changed, project has customized it**
+- User says: "Upgrade the agent-framework for this project"
+- Agent detects that `prompts/orchestrate.md` has changed in the global framework, and the project's version differs from the global version
+- Agent keeps the project's version of `prompts/orchestrate.md`
+- Agent reports: "Skipped: prompts/orchestrate.md (customized in your project). Your framework is now up to date."
+
+**Scenario 4: Multiple changes**
+- User says: "Upgrade the agent-framework for this project"
+- Agent detects:
+  - `prompts/test_design.md` is new → **Added**
+  - `prompts/workflow.md` has changed, project hasn't customized → **Upgraded**
+  - `AGENT.md` has changed, project has customized → **Skipped (customized)**
+- Agent reports: "Upgraded: Updated prompts/workflow.md. Added: Added prompts/test_design.md. Skipped: AGENT.md (customized in your project). Your framework is now up to date."

prompts/orchestrate.md

@@ -2,13 +2,21 @@ You are the Orchestrator Driver. Your job is to act as a **state machine** for t
 
 ## Read These Files
 
-1. {project}/.agent-framework/AGENT.md — Check if Autopilot is enabled
+The Orchestrator reads files using a **layered approach** with a clear precedence:
-2. {project}/.agent-framework/RULES.md
+
+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.
+
+Specifically:
+1. {project}/.agent-framework/AGENT.md (if exists — project override) OR ~/.agent-framework/AGENT.md (global default)
+2. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default)
 3. ~/.agent-framework/config.md — Global framework configuration (VRAM, model settings)
-4. {project}/.agent-framework/AGENT.md (if exists — for model override)
+4. {project}/.agent-framework/prompts/*.md (if exists — project overrides) OR ~/.agent-framework/prompts/*.md (global default)
-5. {project}/.agent-framework/prompts/workflow.md — The State Machine
+5. {project}/.agent-framework/contracts/*.md (if exists — project overrides) OR ~/.agent-framework/contracts/*.md (global default)
-6. Any existing files under {project}/tasks/
+6. {project}/.agent-framework/scripts/*.sh (if exists — project overrides) OR ~/.agent-framework/scripts/*.sh (global default)
-7. {project}/.agent-framework/scripts/vram_detect.sh — VRAM detection script (if exists)
+7. Any existing files under {project}/tasks/
 
 ## VRAM Detection
 

prompts/research.md

@@ -4,8 +4,15 @@ Your only job is to produce a clean, unambiguous specification. Do not write cod
 
 ## Read These Files
 
-1. {project}/.agent-framework/RULES.md — project-specific rules
+The Orchestrator reads files using a **layered approach** with a clear precedence:
-2. {project}/.agent-framework/AGENT.md — project agent config (if exists)
+
+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, read it from there. If it doesn't exist, read it from the global `~/.agent-framework/` directory.
+
+1. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
+2. {project}/.agent-framework/AGENT.md (if exists — project override) OR ~/.agent-framework/AGENT.md (global default) — project agent config
 
 ## Task
 

prompts/test_design.md

@@ -6,7 +6,7 @@ Your only job is to produce a comprehensive, explicit test specification for the
 
 1. {project}/tasks/{task-name}/SPEC.md — Requirements and acceptance criteria
 2. {project}/tasks/{task-name}/DESIGN.md — Architecture and data model (if exists)
-3. {project}/.agent-framework/RULES.md — Project constraints
+3. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — Project constraints
 
 ## Task