From c629661b28c3b7d7f5a264da1b1a5bfbd018b887 Mon Sep 17 00:00:00 2001 From: laptran Date: Thu, 11 Jun 2026 22:25:09 -0400 Subject: [PATCH] Redesign file system to avoid conflicts: layered approach with project overrides and global defaults, proper upgrade process --- README.md | 27 +++++++++++++++ prompts/compaction.md | 4 +-- prompts/decompose.md | 6 ++-- prompts/design.md | 2 +- prompts/implement.md | 4 +-- prompts/onboarding.md | 79 ++++++++++++++++++++++++++++++++---------- prompts/orchestrate.md | 20 +++++++---- prompts/research.md | 11 ++++-- prompts/test_design.md | 2 +- 9 files changed, 120 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index fb70e31..0d57d7f 100644 --- a/README.md +++ b/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] diff --git a/prompts/compaction.md b/prompts/compaction.md index 35c1f49..617ad89 100644 --- a/prompts/compaction.md +++ b/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 -2. {project}/.agent-framework/AGENT.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 (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 diff --git a/prompts/decompose.md b/prompts/decompose.md index c795106..5dffa27 100644 --- a/prompts/decompose.md +++ b/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) -5. {project}/.agent-framework/scripts/vram_detect.sh (if exists — for VRAM detection) +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 — project override) OR ~/.agent-framework/scripts/vram_detect.sh (global default) — VRAM detection ## Task diff --git a/prompts/design.md b/prompts/design.md index 9f596c6..2d3cc2a 100644 --- a/prompts/design.md +++ b/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 diff --git a/prompts/implement.md b/prompts/implement.md index d2bdd6e..fb17e21 100644 --- a/prompts/implement.md +++ b/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 -3. {project}/.agent-framework/AGENT.md (if exists) +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 — 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) diff --git a/prompts/onboarding.md b/prompts/onboarding.md index ac7b370..8b4ae43 100644 --- a/prompts/onboarding.md +++ b/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) -4. {project}/.agent-framework/RULES.md (if it exists) +3. {project}/.agent-framework/AGENT.md (if it exists — project override) +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. -2. If the project's `~/.agent-framework/` has a `workflow.md` 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. +1. Compare the project's `.agent-framework/` files with the global `~/.agent-framework/` files. +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 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) - - RULES.md (project-specific constraints) + - AGENT.md (project-level router — project override of the global framework) + - 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. -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. +### Upgrade Process -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." \ No newline at end of file +- 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." \ No newline at end of file diff --git a/prompts/orchestrate.md b/prompts/orchestrate.md index b6123ad..6b3b2a1 100644 --- a/prompts/orchestrate.md +++ b/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 -2. {project}/.agent-framework/RULES.md +The Orchestrator reads files using a **layered approach** 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. + +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) -5. {project}/.agent-framework/prompts/workflow.md — The State Machine -6. Any existing files under {project}/tasks/ -7. {project}/.agent-framework/scripts/vram_detect.sh — VRAM detection script (if exists) +4. {project}/.agent-framework/prompts/*.md (if exists — project overrides) OR ~/.agent-framework/prompts/*.md (global default) +5. {project}/.agent-framework/contracts/*.md (if exists — project overrides) OR ~/.agent-framework/contracts/*.md (global default) +6. {project}/.agent-framework/scripts/*.sh (if exists — project overrides) OR ~/.agent-framework/scripts/*.sh (global default) +7. Any existing files under {project}/tasks/ ## VRAM Detection diff --git a/prompts/research.md b/prompts/research.md index cdc8053..315b4cc 100644 --- a/prompts/research.md +++ b/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 -2. {project}/.agent-framework/AGENT.md — project agent config (if exists) +The Orchestrator reads files using a **layered approach** 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, 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 diff --git a/prompts/test_design.md b/prompts/test_design.md index bb81ef0..ac77f45 100644 --- a/prompts/test_design.md +++ b/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