gitea
502f47eb21
- 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
155 lines
8.2 KiB
Markdown
155 lines
8.2 KiB
Markdown
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 the agent-framework 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 the agent-framework 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 the agent-framework 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 the agent-framework 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 the agent-framework 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." |