hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor: rename framework files to dot-prefixed lowercase, fix onboarding references, validate VRAM detection

Browse Source 
- Rename AGENT.md -> .agent.md, RULES.md -> .rules.md, ONBOARDING.md -> .onboarding.md
- Rename BUG_REPORT.md -> .bug_report.md, ADVERSARIAL_BUG_REPORT.md -> .adversarial_bug_report.md, VERDICT.md -> .verdict.md
- Fix onboarding.md references to use new .onboarding.md path
- Fix stop-hook-pattern.md reference to use .onboarding.md
- Update README.md, config.md, install.sh, update.sh, prompts/*, references/*
- VRAM detection script validated and working
This commit is contained in:
gitea
2026-06-12 12:40:15 -04:00
parent c629661b28
commit 502f47eb21
22 changed files with 150 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ADVERSARIAL_BUG_REPORT.md → .adversarial_bug_report.md
View File
AGENT.md → .agent.md
+3 -3
View File
@@ -1,13 +1,13 @@
# AGENT.md
# .agent.md
## Autopilot
Autopilot: Enabled
> Note: For global framework settings (VRAM, model, system requirements), see `~/.agent-framework/config.md`.
> Note: For global framework settings (VRAM, model, system requirements), see `~/.automaton/config.md`.
## Routing
IF task type = research → load prompts/research.md + RULES.md
IF task type = research → load prompts/research.md + .rules.md
IF task type = design → load prompts/design.md + SPEC.md
IF task type = test_design → load prompts/test_design.md + SPEC.md + DESIGN.md
IF task type = implement → load prompts/implement.md + SPEC.md + DESIGN.md + TEST_PLAN.md + CONTRACT.md
BUG_REPORT.md → .bug_report.md
+3 -3
View File
@@ -88,9 +88,9 @@ A comprehensive bug finder review of the agent-framework identified **18 bugs**
### Bug 12: Orchestrator — Auto-detect VRAM doesn't handle missing detection script (MEDIUM — FIXED)
- **Severity**: Medium
- **Location**: `prompts/orchestrate.md`, "VRAM Detection" section
- **Description**: The Orchestrator's VRAM detection priority says "Auto-detect via script: Run {project}/.agent-framework/scripts/vram_detect.sh". If the script is not available, it falls back to "Auto-detect via API config." But the Orchestrator doesn't check if the detection script exists before trying to run it.
- **Reproduction**: User starts a new task. The Orchestrator tries to run `{project}/.agent-framework/scripts/vram_detect.sh` but the script doesn't exist.
- **Fix Applied**: Added: "Check if `{project}/.agent-framework/scripts/vram_detect.sh` exists. If it does, run it..." and "If the detection script does not exist, skip to the next detection method."
- **Description**: The Orchestrator's VRAM detection priority says "Auto-detect via script: Run {project}/.automaton/scripts/vram_detect.sh". If the script is not available, it falls back to "Auto-detect via API config." But the Orchestrator doesn't check if the detection script exists before trying to run it.
- **Reproduction**: User starts a new task. The Orchestrator tries to run `{project}/.automaton/scripts/vram_detect.sh` but the script doesn't exist.
- **Fix Applied**: Added: "Check if `{project}/.automaton/scripts/vram_detect.sh` exists. If it does, run it..." and "If the detection script does not exist, skip to the next detection method."
### Bug 13: Orchestrator — Auto-detect VRAM doesn't handle script failure (MEDIUM — FIXED)
- **Severity**: Medium
ONBOARDING.md → .onboarding.md
+4 -4
View File
@@ -9,9 +9,9 @@ The agent's first task in any project is to perform an "Initial Exploration" to
### Step 1: Discovery
The agent must:
1. Explore the project root using `ls` and `find`.
2. Read `.agent-framework/AGENT.md`
3. Read `.agent-framework/RULES.md`
4. Read the global `~/.agent-framework/AGENT.md`
2. Read `.automaton/.agent.md`
3. Read `.automaton/.rules.md`
4. Read the global `~/.automaton/.agent.md`
### Step 2: Reporting
The agent must report back with:
@@ -78,7 +78,7 @@ Instead of memorizing trigger phrases for each phase, you can just say **"orches
## Prompt Rendering Convention
All prompts are stored as template files in `~/.agent-framework/prompts/`. They use `{placeholder}` syntax.
All prompts are stored as template files in `~/.automaton/prompts/`. They use `{placeholder}` syntax.
### Placeholders
- `{project}`: Absolute path to the project root.
RULES.md → .rules.md
+1 -1
View File
@@ -1,4 +1,4 @@
# RULES.md
# .rules.md
- Add one rule per observed failure mode with a concrete example.
- Consolidate contradictions monthly. Remove stale rules.
VERDICT.md → .verdict.md
View File
README.md
+19 -19
View File
@@ -10,10 +10,10 @@ Before you can use the framework in any project, you must install the core logic
```bash
# Clone the framework into the global config directory
git clone [INSERT_FRAMEWORK_REPO_URL_HERE] ~/.agent-framework
git clone [INSERT_FRAMEWORK_REPO_URL_HERE] ~/.automaton
# Enter the directory
cd ~/.agent-framework
cd ~/.automaton
# Make the installation script executable and run it
chmod +x install.sh
@@ -26,7 +26,7 @@ chmod +x install.sh
When the framework is updated, you can update your global installation:
```bash
cd ~/.agent-framework
cd ~/.automaton
./update.sh
```
@@ -50,14 +50,14 @@ If you want the agent to handle the configuration for you, navigate to your proj
The agent will automatically:
1. Detect your project type (New, Existing, or Upgrade).
2. Create the `./.agent-framework/` directory.
3. Generate your `AGENT.md` and `RULES.md` files.
2. Create the `./.automaton/` directory.
3. Generate your `.agent.md` and `.rules.md` files.
4. Initiate the "Exploration Ritual" to understand your codebase.
### Option B: The Manual Way
If you prefer to set it up manually, create a `.agent-framework/` directory in your project root and add:
- `AGENT.md`: Project-specific configuration (Mode, rules, etc.).
- `RULES.md`: Project-specific constraints and past failure modes.
If you prefer to set it up manually, create a `.automaton/` directory in your project root and add:
- `.agent.md`: Project-specific configuration (Mode, rules, etc.).
- `.rules.md`: Project-specific constraints and past failure modes.
---
@@ -84,7 +84,7 @@ The default mode is **Autopilot: Enabled**. The Orchestrator automatically drive
- **Continue**: "orchestrate" or "continue" (the Orchestrator finds the most advanced task and drives it)
#### VRAM Configuration
For low-VRAM systems (8GB, 16GB), set your VRAM limits in `~/.agent-framework/config.md`:
For low-VRAM systems (8GB, 16GB), set your VRAM limits in `~/.automaton/config.md`:
```markdown
## VRAM Configuration
@@ -111,7 +111,7 @@ For low-VRAM systems (8GB, 16GB), set your VRAM limits in `~/.agent-framework/co
```
#### Model Configuration
When using a local LLM or a specific API model, set the model in `~/.agent-framework/config.md`:
When using a local LLM or a specific API model, set the model in `~/.automaton/config.md`:
```markdown
## Model Configuration
@@ -140,7 +140,7 @@ When you run "Decompose the X task", the Orchestrator will:
Sub-tasks run independently through the full lifecycle. The parent task is complete only when ALL sub-tasks pass.
#### Manual mode (opt-in)
Set `Autopilot: Disabled` in your project's `.agent-framework/AGENT.md` if you prefer to manually run each phase. The Orchestrator reports the current state and tells you the next command. Then run phases by saying things like:
Set `Autopilot: Disabled` in your project's `.automaton/.agent.md` if you prefer to manually run each phase. The Orchestrator reports the current state and tells you the next command. Then run phases by saying things like:
- "Research add user authentication" — starts a new task
- "Decompose the add-user-auth task" — breaks into VRAM-sized sub-tasks (optional)
- "Design the add-user-auth task" — designs the architecture (optional)
@@ -164,9 +164,9 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
- The parent task is NOT complete until ALL sub-tasks pass
## Key Components
- `AGENT.md`: Project-specific agent behavior (Autopilot mode, routing rules).
- `.agent.md`: Project-specific agent behavior (Autopilot mode, routing rules).
- `config.md`: Global framework settings (VRAM, model, system requirements).
- `RULES.md`: Living document of project constraints and past failure modes.
- `.rules.md`: Living document of project constraints and past failure modes.
- `prompts/`: Specialized system prompts for each phase (Research, Design, Test Design, Implement, Bug Finder, Adversarial Bug Finder, Doc Review, Referee, Decompose, etc.).
- `workflow.md`: The state machine governing the Autopilot lifecycle.
- `test_design.md`: Produces a TEST_PLAN.md — an explicit test specification before implementation.
@@ -178,15 +178,15 @@ When a task is decomposed, the Orchestrator creates sub-tasks under `tasks/{pare
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
1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
2. **Global framework** (default): `~/.automaton/` — 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.
**Precedence rule**: If a file exists in the project's `.automaton/` directory, the Orchestrator reads it from there. If it doesn't exist, the Orchestrator reads it from the global `~/.automaton/` 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
- **Project's `.automaton/`**: .agent.md (project-specific settings like Autopilot mode, rules override), .rules.md (project-specific constraints)
- **Global `~/.automaton/`**: All prompt files, contracts, scripts, config.md, workflow.md
### Upgrading
@@ -195,7 +195,7 @@ When you upgrade the global framework (e.g., after pushing bug fixes), existing
> "Upgrade the agent-framework for this project."
The agent will:
1. Compare the project's `.agent-framework/` files with the global `~/.agent-framework/` files
1. Compare the project's `.automaton/` files with the global `~/.automaton/` 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**
config.md
+1 -1
View File
@@ -39,7 +39,7 @@ Settings for the LLM model being used.
### Auto-detection
When `Model: auto`, the framework detects the model name from:
1. `AGENT.md` in the project (if specified there)
1. `.agent.md` in the project (if specified there)
2. API config files (`.env`, `config.yaml`, `config.json`, etc.)
3. Model name lookup by name (e.g., gpt-4o → 128k, claude-3-5-sonnet → 200k)
install.sh
+7 -7
View File
@@ -1,16 +1,16 @@
#!/bin/bash
set -e
FRAMEWORK_DIR="$HOME/.agent-framework"
FRAMEWORK_DIR="$HOME/.automaton"
if [ -d "$FRAMEWORK_DIR" ]; then
echo "agent-framework already installed at $FRAMEWORK_DIR"
echo "automaton already installed at $FRAMEWORK_DIR"
echo "Run './update.sh' to update."
exit 0
fi
echo "Cloning agent-framework to $FRAMEWORK_DIR..."
git clone https://gitea.yourdomain.com/you/agent-framework.git "$FRAMEWORK_DIR"
echo "Cloning automaton to $FRAMEWORK_DIR..."
git clone https://gitea.yourdomain.com/you/automaton.git "$FRAMEWORK_DIR"
echo ""
echo "=== VRAM / Context Detection ==="
@@ -38,7 +38,7 @@ if [ -f "$FRAMEWORK_DIR/scripts/vram_detect.sh" ]; then
echo ""
echo "=== Recommended VRAM Configuration ==="
echo "For low-VRAM systems (8GB, 16GB VRAM), add this to ~/.agent-framework/config.md:"
echo "For low-VRAM systems (8GB, 16GB VRAM), add this to ~/.automaton/config.md:"
echo ""
echo "## VRAM Configuration"
echo "- **Auto-detect**: Yes # Let the agent detect automatically"
@@ -49,11 +49,11 @@ if [ -f "$FRAMEWORK_DIR/scripts/vram_detect.sh" ]; then
echo "This ensures tasks are decomposed into sub-tasks that fit within your"
echo "available VRAM. For more information, see the README."
else
echo "Could not detect VRAM. You can manually set your VRAM configuration in ~/.agent-framework/config.md."
echo "Could not detect VRAM. You can manually set your VRAM configuration in ~/.automaton/config.md."
echo "See the README for details."
fi
else
echo "VRAM detection script not found. You can manually set your VRAM configuration in ~/.agent-framework/config.md."
echo "VRAM detection script not found. You can manually set your VRAM configuration in ~/.automaton/config.md."
echo "See the README for details."
fi
prompts/compaction.md
+5 -5
View File
@@ -1,9 +1,9 @@
You are performing a compaction pass on the agent's rules and skills.
## Read These Files
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
1. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
2. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.agent.md (global default) — project agent config
3. Any accumulated notes or previous .rules.md versions in the project
## Task
Consolidate and clean up the rules and routing logic.
@@ -11,12 +11,12 @@ Consolidate and clean up the rules and routing logic.
## Compaction Rules
- Remove duplicate or contradictory rules
- Merge related rules into the smallest number of clear statements
- Update AGENT.md routing logic if any new patterns have emerged
- Update .agent.md routing logic if any new patterns have emerged
- Keep every rule that still prevents a real observed failure mode
- Delete anything that has not been referenced in the last 5 tasks
## Output
Produce an updated RULES.md and AGENT.md.
Produce an updated .rules.md and .agent.md.
At the end, output:
"COMPACTION_COMPLETE — X rules removed, Y rules merged, Z rules added."
prompts/decompose.md
+17 -17
View File
@@ -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 (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 — 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
2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
3. ~/.automaton/config.md — Global framework configuration (VRAM, model settings)
4. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.agent.md (global default) — project agent config
5. {project}/.automaton/scripts/vram_detect.sh (if exists — project override) OR ~/.automaton/scripts/vram_detect.sh (global default) — VRAM detection
## Task
@@ -42,9 +42,9 @@ Each sub-task must fit within the target VRAM context window. Estimate the total
During a sub-task's lifecycle, the following files are loaded into context at various phases:
- **Research phase**: RULES.md + AGENT.md + task description
- **Design phase**: SPEC.md + RULES.md
- **Implement phase**: SPEC.md + DESIGN.md + TEST_PLAN.md + RULES.md + AGENT.md + CONTRACT.md
- **Research phase**: .rules.md + .agent.md + task description
- **Design phase**: SPEC.md + .rules.md
- **Implement phase**: SPEC.md + DESIGN.md + TEST_PLAN.md + .rules.md + .agent.md + CONTRACT.md
- **Bug Find phase**: SPEC.md + code (limited scope)
- **Adversarial Bug Find phase**: SPEC.md + code (limited scope)
- **Doc Review phase**: DESIGN.md
@@ -65,13 +65,13 @@ If a sub-task's estimated context exceeds the limit, break it into smaller sub-t
- A SPEC.md with 5 requirements, each with 2-3 acceptance criteria, is typically 500-1000 tokens
- A DESIGN.md with 3 sections and 5-10 bullet points is typically 1000-3000 tokens
- A TEST_PLAN.md with 5-10 test cases is typically 1000-2000 tokens
- RULES.md is typically 200-1000 tokens (varies per project)
- AGENT.md is typically 300-1000 tokens
- .rules.md is typically 200-1000 tokens (varies per project)
- .agent.md is typically 300-1000 tokens
- A CONTRACT.md is typically 200-500 tokens
**Quick estimate formula:**
```
Peak context ≈ SPEC.md tokens + DESIGN.md tokens + TEST_PLAN.md tokens + RULES.md tokens + AGENT.md tokens + CONTRACT.md tokens
Peak context ≈ SPEC.md tokens + DESIGN.md tokens + TEST_PLAN.md tokens + .rules.md tokens + .agent.md tokens + CONTRACT.md tokens
```
### Rule 7: Sub-Task Size Targets
@@ -97,12 +97,12 @@ Before decomposing, analyze the SPEC.md:
5. Identify configuration changes
6. Estimate the token budget for the full task (sum of all requirements' SPEC + DESIGN + TEST files)
7. **Detect VRAM limits**:
- Check `~/.agent-framework/config.md` for VRAM Configuration section
- If `Auto-detect: Yes`, run `{project}/.agent-framework/scripts/vram_detect.sh` to probe GPU VRAM, RAM, and model context window
- Check `~/.automaton/config.md` for VRAM Configuration section
- If `Auto-detect: Yes`, run `{project}/.automaton/scripts/vram_detect.sh` to probe GPU VRAM, RAM, and model context window
- If `Auto-detect: No`, use the manually specified values from config.md
- Report the detected VRAM limits
8. **Detect model context window**:
- Check `~/.agent-framework/config.md` for Model Configuration section
- Check `~/.automaton/config.md` for Model Configuration section
- If `Model: auto`, run the detection script to detect the model name and its context window
- If `Override context window: auto`, use the detected context window
- If both are specified, use the specified values
@@ -193,8 +193,8 @@ Produce a file called DECOMPOSITION.md at {project}/tasks/{task-name}/DECOMPOSIT
- SPEC.md: ~{x} tokens
- DESIGN.md: ~{x} tokens
- TEST_PLAN.md: ~{x} tokens
- RULES.md: ~{x} tokens
- AGENT.md: ~{x} tokens
- .rules.md: ~{x} tokens
- .agent.md: ~{x} tokens
- CONTRACT.md: ~{x} tokens
- **Peak context (Implement phase)**: ~{peak} tokens
- **Fits within VRAM**: Yes
@@ -210,8 +210,8 @@ Produce a file called DECOMPOSITION.md at {project}/tasks/{task-name}/DECOMPOSIT
- SPEC.md: ~{x} tokens
- DESIGN.md: ~{x} tokens
- TEST_PLAN.md: ~{x} tokens
- RULES.md: ~{x} tokens
- AGENT.md: ~{x} tokens
- .rules.md: ~{x} tokens
- .agent.md: ~{x} tokens
- CONTRACT.md: ~{x} tokens
- **Peak context (Implement phase)**: ~{peak} tokens
- **Fits within VRAM**: Yes
prompts/design.md
+1 -1
View File
@@ -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 (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — project-specific rules
2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
## Task
prompts/implement.md
+2 -2
View File
@@ -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 (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
2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
3. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.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
+27 -27
View File
@@ -4,11 +4,11 @@ Your only job is to set up the minimal agent framework structure in the target p
## Read These Files
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 — 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)
1. ~/.automaton/.agent.md — global framework router
2. ~/.automaton/.onboarding.md — human reference for drop-in vs from-scratch scenarios
3. {project}/.automaton/.agent.md (if it exists — project override)
4. {project}/.automaton/.rules.md (if it exists — project override)
5. ~/.automaton/scripts/vram_detect.sh (if exists — for VRAM detection)
## Task
@@ -19,40 +19,40 @@ 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. 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.
1. Compare the project's `.automaton/` files with the global `~/.automaton/` files.
2. If the project's `.automaton/` has a file that differs from the current global version, the project needs an upgrade.
3. If the project's `.automaton/` 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.
**Precedence**: The project's `.automaton/` files override the global `~/.automaton/` 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.
1. Check if {project}/.automaton/ exists. If not, create it.
2. Ensure exactly two files exist inside it:
- AGENT.md (project-level router — project override of the global framework)
- RULES.md (project-specific constraints — project override of the global framework)
- .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 project's AGENT.md + RULES.md, then read the global ~/.agent-framework/AGENT.md for comparison.
- .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 project's .agent.md + .rules.md, then read the global ~/.automaton/.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.
**Important**: The project's `.automaton/` directory should only contain .agent.md and .rules.md. All other framework files (prompts, contracts, scripts) are read from the global `~/.automaton/` 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`:
1. Read `~/.agent-framework/config.md` to check for VRAM Configuration section.
Check if VRAM configuration is available in `~/.automaton/config.md`:
1. Read `~/.automaton/config.md` to check for VRAM Configuration section.
2. If VRAM Configuration section exists, note the values.
3. If VRAM Configuration section does NOT exist, check if VRAM detection is available: `~/.agent-framework/scripts/vram_detect.sh`.
3. If VRAM Configuration section does NOT exist, check if VRAM detection is available: `~/.automaton/scripts/vram_detect.sh`.
4. If available, run it to get VRAM recommendations:
```
cd ~/.agent-framework && bash ~/.agent-framework/scripts/vram_detect.sh
cd ~/.automaton && bash ~/.automaton/scripts/vram_detect.sh
```
5. Parse the JSON output for `recommended_k`, `max_peak_context_kb`, and `headroom`.
6. Add a VRAM Configuration section to `~/.agent-framework/config.md`:
6. Add a VRAM Configuration section to `~/.automaton/config.md`:
```
## VRAM Configuration
- **Auto-detect**: Yes
@@ -69,9 +69,9 @@ Check if VRAM configuration is available in `~/.agent-framework/config.md`:
## Output
Create or update the following inside {project}/.agent-framework/:
- AGENT.md
- RULES.md
Create or update the following inside {project}/.automaton/:
- .agent.md
- .rules.md
Then produce a file called ONBOARDING_REPORT.md at {project}/tasks/onboarding/ONBOARDING_REPORT.md containing:
@@ -102,7 +102,7 @@ When a user asks to "upgrade the agent-framework for this project," the agent sh
### Upgrade Process
1. **Compare the project's `~/.agent-framework/` files with the global `~/.agent-framework/` files.**
1. **Compare the project's `~/.automaton/` files with the global `~/.automaton/` 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.
@@ -151,5 +151,5 @@ The agent should report:
- 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."
- `.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
+22 -22
View File
@@ -4,18 +4,18 @@ You are the Orchestrator Driver. Your job is to act as a **state machine** for t
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
1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
2. **Global framework** (default): `~/.automaton/` — 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.
**Precedence rule**: If a file exists in the project's `.automaton/` directory, the Orchestrator reads it from there. If it doesn't exist, the Orchestrator reads it from the global `~/.automaton/` 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/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)
1. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.agent.md (global default)
2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default)
3. ~/.automaton/config.md — Global framework configuration (VRAM, model settings)
4. {project}/.automaton/prompts/*.md (if exists — project overrides) OR ~/.automaton/prompts/*.md (global default)
5. {project}/.automaton/contracts/*.md (if exists — project overrides) OR ~/.automaton/contracts/*.md (global default)
6. {project}/.automaton/scripts/*.sh (if exists — project overrides) OR ~/.automaton/scripts/*.sh (global default)
7. Any existing files under {project}/tasks/
## VRAM Detection
@@ -24,9 +24,9 @@ When VRAM configuration is needed (during task decomposition, sub-task creation,
### Detection Priority
1. **Auto-detect via script**: Check if `{project}/.agent-framework/scripts/vram_detect.sh` exists. If it does, run it to probe GPU VRAM, RAM, and model context window. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`.
2. **Auto-detect via API config**: If the script is not available, try to detect the model name from `AGENT.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window. **Important**: Only read the specific lines needed (e.g., the model name line), not the entire file. Limit file reads to 10KB to prevent memory exhaustion.
3. **Manual override**: Check if `~/.agent-framework/config.md` has `Auto-detect: No` under VRAM Configuration. If so, use the manually specified values.
1. **Auto-detect via script**: Check if `{project}/.automaton/scripts/vram_detect.sh` exists. If it does, run it to probe GPU VRAM, RAM, and model context window. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`.
2. **Auto-detect via API config**: If the script is not available, try to detect the model name from `.agent.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window. **Important**: Only read the specific lines needed (e.g., the model name line), not the entire file. Limit file reads to 10KB to prevent memory exhaustion.
3. **Manual override**: Check if `~/.automaton/config.md` has `Auto-detect: No` under VRAM Configuration. If so, use the manually specified values.
4. **Fallback**: Use 8k tokens as default, with 25% headroom.
### How to Read VRAM Config from config.md
@@ -49,9 +49,9 @@ When model context window is needed, the Orchestrator MUST attempt to detect it
#### Detection Priority
1. **Auto-detect via script**: Check if `{project}/.agent-framework/scripts/vram_detect.sh` exists. If it does, run it to detect the model name and its context window. Parse the JSON output for `model_context_kb`.
2. **Auto-detect via config**: Check `~/.agent-framework/config.md` for the model name and override context window.
3. **Auto-detect via API config**: If the script is not available, try to detect the model name from `AGENT.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window. **Important**: Only read the specific lines needed (e.g., the model name line), not the entire file. Limit file reads to 10KB to prevent memory exhaustion.
1. **Auto-detect via script**: Check if `{project}/.automaton/scripts/vram_detect.sh` exists. If it does, run it to detect the model name and its context window. Parse the JSON output for `model_context_kb`.
2. **Auto-detect via config**: Check `~/.automaton/config.md` for the model name and override context window.
3. **Auto-detect via API config**: If the script is not available, try to detect the model name from `.agent.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window. **Important**: Only read the specific lines needed (e.g., the model name line), not the entire file. Limit file reads to 10KB to prevent memory exhaustion.
4. **Fallback**: Use 128k tokens as default (common for modern models).
#### How to Read Model Config from config.md
@@ -62,7 +62,7 @@ When model context window is needed, the Orchestrator MUST attempt to detect it
- **Override context window**: auto # Override auto-detection, or specify (e.g., 128k, 200k)
```
- If `Model: auto`, detect the model name from API config files or AGENT.md.
- If `Model: auto`, detect the model name from API config files or .agent.md.
- If `Override context window: auto`, use the detected context window.
- If both are specified, use the specified values.
@@ -99,7 +99,7 @@ The Orchestrator should run VRAM detection in the following scenarios:
3. **When sub-tasks are created** — to propagate VRAM config to sub-task folders.
4. **When a sub-task's VRAM_CONFIG.md is missing** — to create one with auto-detected values.
**VRAM Detection Caching**: When the Orchestrator is invoked multiple times (e.g., the user says "orchestrate" twice), it MUST cache the VRAM detection results and reuse them instead of running the detection script again. This prevents performance degradation from repeated GPU/RAM probing. The cache should be stored in a temporary file (e.g., `{project}/.agent-framework/.vram_cache.json`) and invalidated when a new task is created or Decomposition is triggered.
**VRAM Detection Caching**: When the Orchestrator is invoked multiple times (e.g., the user says "orchestrate" twice), it MUST cache the VRAM detection results and reuse them instead of running the detection script again. This prevents performance degradation from repeated GPU/RAM probing. The cache should be stored in a temporary file (e.g., `{project}/.automaton/.vram_cache.json`) and invalidated when a new task is created or Decomposition is triggered.
### Reporting Detection Results
@@ -155,7 +155,7 @@ Each task is a state machine. The Orchestrator determines the current state and
| **Referee** | Has `VERDICT.md` with `PASS` | **Complete** |
| **Referee** | Has `VERDICT.md` with `NEEDS_REVIEW` or `FAIL` | **Human Intervention** |
## Autopilot Mode (Autopilot: Enabled in AGENT.md)
## Autopilot Mode (Autopilot: Enabled in .agent.md)
In Autopilot mode, the Orchestrator MUST **drive the task all the way** to completion or until human intervention is needed. It does this by:
@@ -230,7 +230,7 @@ If the Orchestrator detects a `VERDICT.md` with `FAIL` or `NEEDS_REVIEW` for an
## Manual Mode (Autopilot: Disabled)
In manual mode, the Orchestrator only **reports** the current state and the next command. It does NOT execute phases. The user must manually run each phase. Manual mode is opt-in — set `Autopilot: Disabled` in AGENT.md.
In manual mode, the Orchestrator only **reports** the current state and the next command. It does NOT execute phases. The user must manually run each phase. Manual mode is opt-in — set `Autopilot: Disabled` in .agent.md.
## State Determination
@@ -341,8 +341,8 @@ tasks/parent-task/ → Parent task (Research → Decomposition
When a parent task reaches the **Decomposition** phase (has `SPEC.md` and `DECOMPOSITION.md`):
1. **Read `~/.agent-framework/config.md`** to get the VRAM configuration and check if auto-detect is enabled.
2. **If Auto-detect: Yes**, run `{project}/.agent-framework/scripts/vram_detect.sh` to detect VRAM limits. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`. Report the detection results.
1. **Read `~/.automaton/config.md`** to get the VRAM configuration and check if auto-detect is enabled.
2. **If Auto-detect: Yes**, run `{project}/.automaton/scripts/vram_detect.sh` to detect VRAM limits. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`. Report the detection results.
3. **If Auto-detect: No**, use the manually specified values from config.md.
4. **Read `DECOMPOSITION.md`** to extract all sub-task names, dependencies, and their estimated token budgets.
5. **Verify VRAM constraints**:
@@ -373,7 +373,7 @@ Each sub-task follows the full lifecycle independently:
### VRAM-Aware Sub-Task Splitting
If a sub-task's estimated peak context exceeds the VRAM limit from AGENT.md:
If a sub-task's estimated peak context exceeds the VRAM limit from .agent.md:
1. Split the sub-task into smaller sub-tasks.
2. Each new sub-task should fit within the VRAM limit.
3. Update the DECOMPOSITION.md to reflect the new sub-tasks.
prompts/research.md
+5 -5
View File
@@ -6,13 +6,13 @@ Your only job is to produce a clean, unambiguous specification. Do not write cod
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
1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
2. **Global framework** (default): `~/.automaton/` — 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.
**Precedence rule**: If a file exists in the project's `.automaton/` directory, read it from there. If it doesn't exist, read it from the global `~/.automaton/` 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
1. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
2. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.agent.md (global default) — project agent config
## Task
prompts/test_design.md
+1 -1
View File
@@ -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 (if exists — project override) OR ~/.agent-framework/RULES.md (global default) — Project constraints
3. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — Project constraints
## Task
references/session-starter.md
+5 -5
View File
@@ -6,11 +6,11 @@ Copy and paste this at the very beginning of every new agent session (before giv
Read the following files in order, then wait for my instructions:
1. ~/.agent-framework/AGENT.md (global framework router)
2. {project}/.agent-framework/AGENT.md (project-level router, if it exists)
3. {project}/.agent-framework/RULES.md (if it exists)
1. ~/.automaton/.agent.md (global framework router)
2. {project}/.automaton/.agent.md (project-level router, if it exists)
3. {project}/.automaton/.rules.md (if it exists)
After reading these files, acknowledge with: "AGENT.md and RULES.md loaded. Ready."
After reading these files, acknowledge with: ".agent.md and .rules.md loaded. Ready."
---
@@ -23,4 +23,4 @@ After reading these files, acknowledge with: "AGENT.md and RULES.md loaded. Read
- "Implement the fix-alert-test task"
- "Onboard this project to the agent framework"
This guarantees the agent always follows the routing rules in `AGENT.md`.
This guarantees the agent always follows the routing rules in `.agent.md`.
references/stop-hook-pattern.md
+1 -1
View File
@@ -54,6 +54,6 @@ Only then output "CONTRACT_MET".
- prompts/implement.md
- prompts/research.md
- prompts/bug_finder.md (optional)
- Update ONBOARDING.md to document this pattern under "Define Clear End States"
- Update .onboarding.md to document this pattern under "Define Clear End States"
This turns the voluntary "CONTRACT_MET" into a hard mechanical requirement.
scripts/vram_detect.sh
+19 -19
View File
@@ -172,7 +172,7 @@ detect_model_context() {
# Try to detect from config.md (global framework model settings)
local project_dir="${1:-.}"
local config_md="${HOME}/.agent-framework/config.md"
local config_md="${HOME}/.automaton/config.md"
local model_from_config=""
local override_context=""
if [[ -f "$config_md" ]]; then
@@ -200,13 +200,13 @@ detect_model_context() {
return
fi
# Try to detect from AGENT.md (project-level model override)
local agent_md="${project_dir}/.agent-framework/AGENT.md"
# Try to detect from .agent.md (project-level model override)
local agent_md="${project_dir}/.automaton/.agent.md"
if [[ -f "$agent_md" ]]; then
local model_line
model_line=$(grep -i "model" "$agent_md" 2>/dev/null | grep -v "#" | grep -v "target" | grep -v "headroom" | grep -v "peak" | grep -v "Auto-detect" | head -1)
if [[ -n "$model_line" ]]; then
echo "Found model in AGENT.md: $model_line"
echo "Found model in .agent.md: $model_line"
# Extract model name from the line
local model
model=$(echo "$model_line" | sed -E 's/.*[:=[:space:]]+//i' | tr -d '[:space:]')
@@ -237,13 +237,13 @@ detect_model_context() {
"config.yml"
"config.json"
"settings.yaml"
".agent-framework/config.yaml"
".agent-framework/config.json"
".automaton/config.yaml"
".automaton/config.json"
)
for config_file in "${config_files[@]}"; do
local abs_file=""
for candidate in "${project_dir}/${config_file}" "${project_dir}/.agent-framework/${config_file}"; do
for candidate in "${project_dir}/${config_file}" "${project_dir}/.automaton/${config_file}"; do
if [[ -f "$candidate" ]]; then
abs_file="$candidate"
break
@@ -272,7 +272,7 @@ detect_model_context() {
fi
done
echo "Model: Unknown (could not detect from AGENT.md or config files)"
echo "Model: Unknown (could not detect from .agent.md or config files)"
echo "0"
}
@@ -283,22 +283,22 @@ calculate_overhead() {
# Count tokens for the framework files that are loaded during orchestration
# These are the files loaded during the most common phase (orchestration):
# AGENT.md + RULES.md + workflow.md + orchestrate.md
# .agent.md + .rules.md + workflow.md + orchestrate.md
# Note: other phase files (decompose.md, implement.md, etc.) are only loaded during
# their specific phases, so they don't contribute to the peak context during orchestration.
local framework_files=(
"${project_dir}/.agent-framework/AGENT.md"
"${project_dir}/.agent-framework/RULES.md"
"${project_dir}/.agent-framework/prompts/workflow.md"
"${project_dir}/.agent-framework/prompts/orchestrate.md"
"${project_dir}/.automaton/.agent.md"
"${project_dir}/.automaton/.rules.md"
"${project_dir}/.automaton/prompts/workflow.md"
"${project_dir}/.automaton/prompts/orchestrate.md"
)
# Fallback: check home directory if project dir doesn't have framework
if [[ ! -f "${project_dir}/.agent-framework/AGENT.md" ]]; then
if [[ ! -f "${project_dir}/.automaton/.agent.md" ]]; then
framework_files=(
"${HOME}/.agent-framework/AGENT.md"
"${HOME}/.agent-framework/RULES.md"
"${HOME}/.agent-framework/prompts/workflow.md"
"${HOME}/.agent-framework/prompts/orchestrate.md"
"${HOME}/.automaton/.agent.md"
"${HOME}/.automaton/.rules.md"
"${HOME}/.automaton/prompts/workflow.md"
"${HOME}/.automaton/prompts/orchestrate.md"
)
fi
@@ -325,7 +325,7 @@ recommend_context() {
local overhead_tokens="$4"
# Read VRAM config from config.md if it exists
local config_md="${HOME}/.agent-framework/config.md"
local config_md="${HOME}/.automaton/config.md"
local auto_detect="Yes"
local target_context_kb=0
local override_headroom=25
system-prompt.md
+3 -3
View File
@@ -2,9 +2,9 @@ You are working inside the minimal agent framework.
At the very start of every session, you must:
1. Read ~/.agent-framework/AGENT.md (global router)
2. Read the current project's .agent-framework/AGENT.md (if it exists)
3. Read the current project's .agent-framework/RULES.md (if it exists)
1. Read ~/.automaton/.agent.md (global router)
2. Read the current project's .automaton/.agent.md (if it exists)
3. Read the current project's .automaton/.rules.md (if it exists)
After reading these files, respond with: "Framework context loaded. Ready for task."
update.sh
+4 -4
View File
@@ -1,15 +1,15 @@
#!/bin/bash
set -e
FRAMEWORK_DIR="$HOME/.agent-framework"
FRAMEWORK_DIR="$HOME/.automaton"
if [ ! -d "$FRAMEWORK_DIR" ]; then
echo "ERROR: agent-framework not installed at $FRAMEWORK_DIR"
echo "ERROR: automaton not installed at $FRAMEWORK_DIR"
echo "Run './install.sh' first."
exit 1
fi
echo "Updating agent-framework at $FRAMEWORK_DIR..."
echo "Updating automaton at $FRAMEWORK_DIR..."
cd "$FRAMEWORK_DIR"
# Check if it's a git repo
@@ -41,4 +41,4 @@ git pull origin main
echo ""
echo "Update complete."
echo "You can check for breaking changes at: https://gitea.yourdomain.com/hermes/agent-framework"
echo "You can check for breaking changes at: https://gitea.yourdomain.com/hermes/automaton"