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.sh (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.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
• 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):

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. If stale files 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

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.