When the framework is updated, you can update your global installation:
```bash
cd ~/.agent-framework
./update.sh
```
This will:
- Fetch the latest changes from the repository
- Check for uncommitted changes and warn you
- Pull the latest updates
**Upgrading existing projects:** When the framework is updated, existing projects may need their framework files upgraded (new phases added, new prompts, etc.). To upgrade an existing project, tell the agent: "Upgrade the agent-framework for this project." The agent will check for missing files and update them.
2.**Decomposition** (optional): Break the task into sub-tasks sized for your VRAM. **Interactive** — agent analyzes the spec and proposes sub-tasks with token budget estimates, gets sign-off. See [VRAM Configuration](#vram-configuration) below.
3.**Design** (optional): Produce a `DESIGN.md` (Architecture). No code allowed. **Interactive** — agent grills you for design decisions and gets sign-off.
3.**Test Design** (optional): Produce a `TEST_PLAN.md` (Test specification). No code allowed. **Interactive** — agent grills you for test coverage and edge cases, then presents draft test cases for review and sign-off.
4.**Implement**: Write code and tests based *only* on the `SPEC.md`, `DESIGN.md` (if present), and `TEST_PLAN.md` (if present). Follow TDD (Red/Green/Refactor). The TEST_PLAN.md (if present) serves as the test specification the implementer follows.
5.**Bug Find**: Aggressive search for bugs and spec deviations.
6.**Adversarial Bug Find**: Deep search for complex logic errors, race conditions, and performance issues.
7.**Doc Review**: Review documentation against DESIGN.md plan and fix missing docs.
8.**Referee**: Objective evaluation of all bugs, docs, and the final verdict.
**Auto-detection**: When `Auto-detect: Yes`, the Orchestrator runs `scripts/vram_detect.sh` to probe:
- GPU VRAM (via `nvidia-smi`)
- System RAM (via `free`)
- Model context window (from config.md or API config files)
- Framework overhead (by counting token load in loaded prompts)
**Manual override**: When `Auto-detect: No`, use the manually specified values:
```markdown
## VRAM Configuration
- **Auto-detect**: No
- **Target VRAM context**: 8k
- **Headroom**: 30%
- **Max peak context per sub-task**: 5.6k
```
#### Model Configuration
When using a local LLM or a specific API model, set the model in `~/.agent-framework/config.md`:
```markdown
## Model Configuration
- **Model**: auto # Use auto-detection from API config files
- **Override context window**: auto # Override auto-detection, or specify (e.g., 128k, 200k)
```
**Auto-detection**: When `Model: auto`, the framework detects the model name from API config files (`.env`, `config.yaml`, etc.) and looks up its context window.
**Manual override**: When you know your model name, specify it:
```markdown
## Model Configuration
- **Model**: gpt-4o
- **Override context window**: 128k
```
When you run "Decompose the X task", the Orchestrator will:
1. Analyze the task's SPEC.md
2. Detect VRAM limits (auto or manual)
3. Break it into sub-tasks, each sized to fit within your VRAM limit
4. Estimate the token budget for each sub-task
5. Create sub-task folders under `tasks/{parent-task}/subtasks/{sub-task}/`
6. Propagate VRAM config to each sub-task
Sub-tasks run independently through the full lifecycle. The parent task is complete only when ALL sub-tasks pass.
Set `Autopilot: Disabled` in your project's `.agent-framework/AGENT.md` if you prefer to manually run each phase. The Orchestrator reports the current state and tells you the next command. Then run phases by saying things like:
2.**Global framework** (default): `~/.agent-framework/` — contains the base framework files
**Precedence rule**: If a file exists in the project's `.agent-framework/` directory, the Orchestrator reads it from there. If it doesn't exist, the Orchestrator reads it from the global `~/.agent-framework/` directory.
