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

- 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

.agent.md

@@ -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

@@ -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.
+- **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}/.agent-framework/scripts/vram_detect.sh` but the script doesn't exist.
+- **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}/.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."
+- **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

@@ -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`
+2. Read `.automaton/.agent.md`
-3. Read `.agent-framework/RULES.md`
+3. Read `.automaton/.rules.md`
-4. Read the global `~/.agent-framework/AGENT.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

@@ -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.

README.md

@@ -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.
+2. Create the `./.automaton/` directory.
-3. Generate your `AGENT.md` and `RULES.md` files.
+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:
+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.).
+- `.agent.md`: Project-specific configuration (Mode, rules, etc.).
-- `RULES.md`: Project-specific constraints and past failure modes.
+- `.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
+1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
-2. **Global framework** (default): `~/.agent-framework/` — contains the base framework files
+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)
+- **Project's `.automaton/`**: .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
+- **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

@@ -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

@@ -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..."
+echo "Cloning automaton to $FRAMEWORK_DIR..."
-git clone https://gitea.yourdomain.com/you/agent-framework.git "$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

@@ -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
+1. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.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
+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
+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

@@ -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
+2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default) — project-specific rules
-3. ~/.agent-framework/config.md — Global framework configuration (VRAM, model settings)
+3. ~/.automaton/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
+4. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.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
+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
+- **Research phase**: .rules.md + .agent.md + task description
-- **Design phase**: SPEC.md + RULES.md
+- **Design phase**: SPEC.md + .rules.md
-- **Implement phase**: SPEC.md + DESIGN.md + TEST_PLAN.md + RULES.md + AGENT.md + CONTRACT.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)
+- .rules.md is typically 200-1000 tokens (varies per project)
-- AGENT.md is typically 300-1000 tokens
+- .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
+   - Check `~/.automaton/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
+   - 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
+  - .rules.md: ~{x} tokens
-  - AGENT.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
+  - .rules.md: ~{x} tokens
-  - AGENT.md: ~{x} tokens
+  - .agent.md: ~{x} tokens
   - CONTRACT.md: ~{x} tokens
 - **Peak context (Implement phase)**: ~{peak} tokens
 - **Fits within VRAM**: Yes

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 (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

@@ -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
+2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.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
+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

@@ -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
+1. ~/.automaton/.agent.md — global framework router
-2. ~/.agent-framework/ONBOARDING.md — human reference for drop-in vs from-scratch scenarios
+2. ~/.automaton/.onboarding.md — human reference for drop-in vs from-scratch scenarios
-3. {project}/.agent-framework/AGENT.md (if it exists — project override)
+3. {project}/.automaton/.agent.md (if it exists — project override)
-4. {project}/.agent-framework/RULES.md (if it exists — project override)
+4. {project}/.automaton/.rules.md (if it exists — project override)
-5. ~/.agent-framework/scripts/vram_detect.sh (if exists — for VRAM detection)
+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.
+1. Compare the project's `.automaton/` files with the global `~/.automaton/` files.
-2. If the project's `.agent-framework/` has a file that differs from the current global version, the project needs an upgrade.
+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 `.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.
+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)
+   - .agent.md (project-level router — project override of the global framework)
-   - RULES.md (project-specific constraints — 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.
+   - .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.
+   - .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.
+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`:
+Check if VRAM configuration is available in `~/.automaton/config.md`:
-1. Read `~/.agent-framework/config.md` to check for VRAM Configuration section.
+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/:
+Create or update the following inside {project}/.automaton/:
-- AGENT.md
+- .agent.md
-- RULES.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.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 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

@@ -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
+1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
-2. **Global framework** (default): `~/.agent-framework/` — contains the base framework files
+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)
+1. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.agent.md (global default)
-2. {project}/.agent-framework/RULES.md (if exists — project override) OR ~/.agent-framework/RULES.md (global default)
+2. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.rules.md (global default)
-3. ~/.agent-framework/config.md — Global framework configuration (VRAM, model settings)
+3. ~/.automaton/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)
+4. {project}/.automaton/prompts/*.md (if exists — project overrides) OR ~/.automaton/prompts/*.md (global default)
-5. {project}/.agent-framework/contracts/*.md (if exists — project overrides) OR ~/.agent-framework/contracts/*.md (global default)
+5. {project}/.automaton/contracts/*.md (if exists — project overrides) OR ~/.automaton/contracts/*.md (global default)
-6. {project}/.agent-framework/scripts/*.sh (if exists — project overrides) OR ~/.agent-framework/scripts/*.sh (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`.
+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.
+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.
+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`.
+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 `~/.agent-framework/config.md` for the model name and override context window.
+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.
+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.
+1. **Read `~/.automaton/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.
+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

@@ -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
+1. **Project overrides** (highest precedence): `{project}/.automaton/` — contains project-specific customizations
-2. **Global framework** (default): `~/.agent-framework/` — contains the base framework files
+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
+1. {project}/.automaton/.rules.md (if exists — project override) OR ~/.automaton/.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
+2. {project}/.automaton/.agent.md (if exists — project override) OR ~/.automaton/.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 (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

@@ -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)
+1. ~/.automaton/.agent.md (global framework router)
-2. {project}/.agent-framework/AGENT.md (project-level router, if it exists)
+2. {project}/.automaton/.agent.md (project-level router, if it exists)
-3. {project}/.agent-framework/RULES.md (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

@@ -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

@@ -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)
+    # Try to detect from .agent.md (project-level model override)
-    local agent_md="${project_dir}/.agent-framework/AGENT.md"
+    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"
+        ".automaton/config.yaml"
-        ".agent-framework/config.json"
+        ".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}/.automaton/.agent.md"
-        "${project_dir}/.agent-framework/RULES.md"
+        "${project_dir}/.automaton/.rules.md"
-        "${project_dir}/.agent-framework/prompts/workflow.md"
+        "${project_dir}/.automaton/prompts/workflow.md"
-        "${project_dir}/.agent-framework/prompts/orchestrate.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}/.automaton/.agent.md"
-            "${HOME}/.agent-framework/RULES.md"
+            "${HOME}/.automaton/.rules.md"
-            "${HOME}/.agent-framework/prompts/workflow.md"
+            "${HOME}/.automaton/prompts/workflow.md"
-            "${HOME}/.agent-framework/prompts/orchestrate.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

@@ -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)
+1. Read ~/.automaton/.agent.md (global router)
-2. Read the current project's .agent-framework/AGENT.md (if it exists)
+2. Read the current project's .automaton/.agent.md (if it exists)
-3. Read the current project's .agent-framework/RULES.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

@@ -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"