hermes/agent-framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
gitea
2026-06-11 22:25:09 -04:00
parent 8897852cc0
commit c629661b28
9 changed files with 120 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
prompts/onboarding.md
+61 -18
View File
@@ -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."
- 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."