# SPEC: Additive Extension Model for Project Upgrades

## Overview

Replace the current diff/merge upgrade process with a simpler additive extension model. Projects should never copy framework files. Instead, they provide overrides via `.agent.md`, `.rules.md`, and an optional `extensions/` directory. Updating the framework becomes a simple `git pull` with no project-level file comparison.

## Motivation

The current design has a design-vs-reality gap:

| Design Intent | Reality |
|---|---|
| Projects only have `.agent.md` + `.rules.md` | Projects have full copies of framework files |
| Additive overrides only | Diff/merge required on upgrade |
| Simple `git pull` update | Complex file-by-file comparison |

The root cause: `orchestrate.md` reads prompts/contracts/scripts from the **project first**, then falls back to global. This encourages copying files into the project, which breaks the clean separation.

## Required Changes

### 1. `prompts/orchestrate.md`

Remove the project-first fallback for prompts, contracts, and scripts. The Orchestrator should:
- Always read base prompts/contracts/scripts from `~/.automaton/` (global)
- Check `{project}/.automaton/extensions/` for additive extensions (not replacements)
- Specific extension files to check:
  - `{project}/.automaton/extensions/prompts/*.md` - loaded after the corresponding global prompt
  - `{project}/.automaton/extensions/contracts/*.md` - loaded after global contracts
  - `{project}/.automaton/extensions/scripts/*.sh` - loaded before global scripts (to allow pre-processing)
- The read order for `.agent.md` stays layered (project override is correct for routing)

### 2. `prompts/onboarding.md`

- Remove the "Project Upgrade" section (lines 99-155) that performs diff/merge
- Simplify to: if `.agent.md` or `.rules.md` are missing, create minimal defaults
- Add documentation for the `extensions/` directory pattern
- Remove any instructions that copy framework files into the project

### 3. `scripts/update.sh`

- Simplify: remove the reset hard HEAD step. Just `git pull` with a clean working tree check.
- Ensure it only touches `~/.automaton/`, never project directories

### 4. `README.md`

- Update the "Upgrading existing projects" section to describe the new additive model
- Document the `extensions/` directory pattern

## Acceptance Criteria

- [ ] `prompts/orchestrate.md` reads prompts/contracts/scripts from `~/.automaton/` first, not from project
- [ ] `prompts/orchestrate.md` checks `{project}/.automaton/extensions/` for additive extensions
- [ ] `prompts/onboarding.md` no longer has diff/merge upgrade logic
- [ ] `prompts/onboarding.md` creates minimal `.agent.md` and `.rules.md` if missing
- [ ] `prompts/onboarding.md` documents the `extensions/` directory
- [ ] `scripts/update.sh` does a simple `git pull` without resetting local changes
- [ ] `README.md` describes the new upgrade model
- [ ] No existing prompt/contract/script behavior is broken (regression check)

## Non-Goals

- Moving the dashboard (`automaton/dashboard/`) - it already reads from `~/.automaton/` at runtime
- Changing how `config.md` is read (already always global per `orchestrate.md` line 15)
- Changing the task directory structure

## Notes

- The `invest-copilot` project has a full copy of the framework in its `.automaton/` - this task should include a migration path to clean it up
- The extension model should be documented in `references/extensions.md` as well