automaton/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/.rules.md — global framework rules
3. ~/.automaton/.onboarding.md — human reference for drop-in vs from-scratch scenarios
4. {project}/.automaton/.agent.md (if it exists — project override)
5. {project}/.automaton/.rules.md (if it exists — project override)
6. ~/.automaton/scripts/vram_detect.py (if exists — for VRAM detection)

## Task

{task-description}

## Onboarding Ritual (Strict Sequence)

### 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. Projects can provide additive extensions under `.automaton/extensions/` — these extend, never replace, the framework files.

### 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.py`.
4. If available, run it to get VRAM recommendations:
   ```
   cd ~/.automaton && python ~/.automaton/scripts/vram_detect.py
   ```
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.

### Step 2b: State Enforcement Check (v2.0)

Verify that the project is set up for v2.0 state enforcement:
1. Check that `~/.automaton/scripts/status.py` exists and is executable.
2. Run `python ~/.automaton/scripts/status.py --list --project {project}` to verify it finds the project's task directory.
3. If the project has existing tasks, run `python ~/.automaton/scripts/status.py --audit --project {project}` to check for violations or manually created tasks that need `.state` files.
4. If the project has existing tasks without `.state` files, run `python ~/.automaton/scripts/status.py --upgrade --project {project}` to bootstrap `.state` files from artifact heuristics.

### Step 2c: Pre-Commit Hook Installation

Install the automaton pre-commit hook to block commits when no task is in an edit-allowed phase:
1. Check if `{project}/.git/hooks/` exists (the project uses git).
2. If it does, create a symlink: `ln -sf ~/.automaton/scripts/git-hooks/pre-commit {project}/.git/hooks/pre-commit`
3. If `{project}/.git/hooks/pre-commit` already exists and is not our symlink, warn the user and ask whether to replace it.
4. Verify the hook: `python ~/.automaton/scripts/status.py --can-edit --project {project}` should return exit code 1 (DENIED) since no tasks exist yet.
5. Note in the onboarding report whether the hook was installed.

### Step 2d: Backlog Check

Check for outstanding design work that may need attention:
1. Read `~/.automaton/design/loops/BACKLOG.md` for loop engineering work queue items.
2. Read `~/.automaton/design/framework/BACKLOG.md` for framework-level agent features (rule agents, Agent tab redesign, model-divergence enforcement).
3. Note in the onboarding report whether there are unchecked `- [ ]` items in either backlog that the project owner may want to pick up manually or via the self-improvement loop (`work_source.area = "loops"` or `"framework"`).

## Output

Create or update the following inside {project}/.automaton/:
- .agent.md
- .rules.md

Then produce a file called ONBOARDING_REPORT.md at {project}/.automaton/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
- **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.

---

## Migration Check

When a user asks to "upgrade automaton for this project" or during onboarding, the agent should first check if the project has stale copies of framework files (from the old model where files were copied into the project) or tasks in the deprecated location.

### Migration Detection

1. Check if `{project}/.automaton/` contains any files beyond `.agent.md` and `.rules.md`:
   - `prompts/` directory with files matching global prompts
   - `contracts/` directory with files matching global contracts
   - `scripts/` directory with files matching global scripts
   - Any other files that exist in `~/.automaton/`

2. Check for tasks at the deprecated `{project}/tasks/` location:
   - If `{project}/tasks/` exists but `{project}/.automaton/tasks/` does not, tasks need to be moved.

3. If stale files or deprecated task location are found, offer to run migration:
   - Run `~/.automaton/scripts/migrate-project.sh {project}` if available
   - Or manually:
     - Files identical to global → delete (framework provides them)
     - Files different from global → move to `.automaton/extensions/`
     - `.agent.md` and `.rules.md` → keep as-is
     - `{project}/tasks/` → move to `{project}/.automaton/tasks/`

### After Migration

No further upgrade steps are needed. The framework is always read from `~/.automaton/` at runtime. Simply updating the global framework (`cd ~/.automaton && ./update.sh`) automatically applies all changes to every project.