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. ~/.agent-framework/AGENT.md — global framework router
2. ~/.agent-framework/ONBOARDING.md — human reference for drop-in vs from-scratch scenarios
3. {project}/.agent-framework/AGENT.md (if it exists)
4. {project}/.agent-framework/RULES.md (if it exists)

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. Check if ~/.agent-framework/prompts/workflow.md exists and compare its content with the current global framework's workflow.md.
2. If the project's ~/.agent-framework/ has a workflow.md that differs from the current global version, the project needs an upgrade.
3. If the project's ~/.agent-framework/ is missing new prompt files (e.g., doc_review.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.

Step 1: Discovery

1. Check if {project}/.agent-framework/ exists. If not, create it.
2. Ensure exactly two files exist inside it:
   • AGENT.md (project-level router)
   • RULES.md (project-specific constraints)
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.
   • RULES.md should contain only hard, non-negotiable constraints for this project.
4. Read the global ~/.agent-framework/AGENT.md and the new project-level AGENT.md + RULES.md.
5. Explore the project root at a high level (ls, key directories, README if present).
6. Produce a short onboarding report.

Output

Create or update the following inside {project}/.agent-framework/:

• 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

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:

1. Compare the project's ~/.agent-framework/ files with the global ~/.agent-framework/ files.
2. Identify any missing files in the project's framework directory:
   • New prompt files (e.g., doc_review.md)
   • Updated workflow.md (state machine changes)
   • New contract files
3. Add the missing files from the global framework into the project's framework directory.
4. Do NOT overwrite existing project-specific files (AGENT.md, RULES.md).
5. Report what was upgraded and what was already up to date.

Example upgrade scenario:

• User says: "Upgrade the agent-framework for this project"
• Agent detects that prompts/doc_review.md is missing from the project's framework
• Agent copies prompts/doc_review.md from the global framework into the project's framework
• Agent reports: "Upgraded: Added prompts/doc_review.md. Your framework is now up to date."