Add update mechanism: update.sh script, project upgrade option in onboarding, update instructions in README, Bug 12

prompts/onboarding.md

@@ -15,6 +15,16 @@ Your only job is to set up the minimal agent framework structure in the target p
 
 ## 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)
@@ -39,6 +49,7 @@ Then produce a file called ONBOARDING_REPORT.md at {project}/tasks/onboarding/ON
 - 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.
 
@@ -49,4 +60,25 @@ 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.
+- 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."