agent-framework/prompts/onboarding.md

You are in onboarding mode for the agent framework.

Your only job is to set up the minimal agent framework structure in the target project and perform the initial exploration ritual. Do not start any real tasks.

## Read These Files

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

{task-description}

## Onboarding Ritual (Strict Sequence)

### 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 `.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 `.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}/.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)
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 ~/.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 `.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 `~/.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: `~/.automaton/scripts/vram_detect.sh`.
4. If available, run it to get VRAM recommendations:
   ```
   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 `~/.automaton/config.md`:
   ```
   ## VRAM Configuration
   - **Auto-detect**: Yes
   - **Target context**: {recommended_k}k tokens
   - **Headroom**: 25%
   - **Max peak context per sub-task**: {max_peak_kb/1000}k tokens
   ```
7. If VRAM detection failed or is not available, add a minimal section:
   ```
   ## VRAM Configuration
   - **Auto-detect**: Yes
   ```
8. Report the VRAM configuration status in the onboarding report.

## Output

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:

- Confirmation that the framework files were created/read
- Summary of the project rules
- What process this project expects
- Key observations from the project structure
- Any missing pieces the human should provide next
- **Upgrade status**: Whether the project's framework files are up to date with the global framework
- **VRAM Configuration**: Whether VRAM config was auto-detected and applied (if available), or needs manual setup

When the ritual is complete, output "CONTRACT_MET" and stop.

## Stop Condition (MANDATORY)
You are not allowed to end this session until you have produced the ONBOARDING_REPORT.md and output the exact phrase "CONTRACT_MET".
Do not begin any research, implementation, or bug-finding tasks.

## Important
- Keep everything minimal. Only create the two required files.
- Never copy the entire global framework into the project.
- This is a one-time setup. After this session the normal research → implement flow takes over.

---

## Project Upgrade

When a user asks to "upgrade automaton for this project," the agent should:

### Upgrade Process

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.

2. **Identify three categories of files:**
   - **Customized** — The file exists in both, but they differ. The project has customized it. **Keep the project's version.**
   - **Outdated** — The file exists in both, but they are identical. The project hasn't customized it, but the global version has changed. **Update from global.**
   - **New** — The file exists in the global framework but not in the project. **Add from global.**

3. **Apply upgrades:**
   - For **Outdated** files: Copy from the global framework to the project's framework (update the project's version).
   - For **New** files: Copy from the global framework to the project's framework (add the file).
   - For **Customized** files: **Do NOT overwrite** — keep the project's version and report it as "skipped (customized)."

4. **Report what was upgraded and what was already up to date.**

### Upgrade Report Format

The agent should report:
- **Upgraded**: Files that were updated from the global framework (Outdated → Upgraded)
- **Added**: New files added from the global framework (New → Added)
- **Skipped**: Files that were customized in the project and not overwritten (Customized → Skipped)
- **Already up to date**: Files that were already identical (shouldn't happen, but report for completeness)

### Example Upgrade Scenarios

**Scenario 1: New file added globally**
- User says: "Upgrade automaton for this project"
- Agent detects that `prompts/test_design.md` is missing from the project's framework
- Agent copies `prompts/test_design.md` from the global framework into the project's framework
- Agent reports: "Upgraded: Added prompts/test_design.md. Your framework is now up to date."

**Scenario 2: Global file changed, project hasn't customized it**
- User says: "Upgrade automaton for this project"
- Agent detects that `prompts/orchestrate.md` has changed in the global framework, and the project's version is identical to the old global version
- Agent copies `prompts/orchestrate.md` from the global framework into the project's framework
- Agent reports: "Upgraded: Updated prompts/orchestrate.md. Your framework is now up to date."

**Scenario 3: Global file changed, project has customized it**
- User says: "Upgrade automaton for this project"
- Agent detects that `prompts/orchestrate.md` has changed in the global framework, and the project's version differs from the global version
- Agent keeps the project's version of `prompts/orchestrate.md`
- Agent reports: "Skipped: prompts/orchestrate.md (customized in your project). Your framework is now up to date."

**Scenario 4: Multiple changes**
- User says: "Upgrade automaton for this project"
- Agent detects:
  - `prompts/test_design.md` is new → **Added**
  - `prompts/workflow.md` has changed, project hasn't customized → **Upgraded**
  - `.agent.md` has changed, project has customized → **Skipped (customized)**
- Agent reports: "Upgraded: Updated prompts/workflow.md. Added: Added prompts/test_design.md. Skipped: .agent.md (customized in your project). Your framework is now up to date."