The git URL is required because the framework uses it for self-updates and the self-improvement loop. Choose carefully -- it cannot be changed later without reinstalling.
*Note: This creates the "brain" of the framework (prompts, state machines, and rules) in your home directory. A self-improvement loop is created and scheduled by default (see Loop Engineering below).*
**Upgrading existing projects:** The framework reads prompts, contracts, and scripts from `~/.automaton/` at runtime. Projects only override `.agent.md` and `.rules.md`. This means updating the global framework (`git pull`) automatically applies to all projects. No per-project upgrade is needed.
If a project was set up under the old model (with copies of framework files), it needs migration first. Tell the agent: "Upgrade automaton for this project" to run the migration.
The self-improvement loop installed by default targets the **framework itself** (`work_source.project: ~/.automaton/`), not your project. It ticks hourly against `status.py --audit` on `~/.automaton/` to keep the framework healthy. This is by design — it improves the framework you depend on while you work on your project.
- **Leave it running** if you want the framework maintained in the background (recommended).
- **Disable it** if you want zero background activity: `python3 ~/.automaton/scripts/status.py --pause-loop self-improvement --project ~/.automaton/`
- **Want a loop on your project too?** Create a separate one targeted at the project root:
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.
- **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 `.automaton/.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:
Automaton can run unattended workflow loops: each loop has an OS-level schedule (launchd / cron / schtasks) and is constrained by 6 brake gates enforced in `status.py`. The single source of truth for loop runtime state is `.state.loop` per loop at `{project}/.automaton/loops/<name>/.state.loop`.
```bash
# Create a loop from a template (only way to bootstrap)
Loop states: `running`, `halted`, `paused`, `complete`. Halt reasons: `iterations_exhausted`, `budget_exhausted`, `verifier_failed`, `drift_detected`, `human_intervention`. The per-tick engine is `scripts/loop-runner.py --mode tick`; it gates first, spawns Implement / Verify / Orchestrate role sessions, and writes `.state.loop` atomically. Concurrent ticks on the same loop and concurrent `--pause-loop` / `--approve --loop` writes are serialized via a cross-process file lock on `<loop_path>/.state.lock` (POSIX `fcntl.flock`, Windows `msvcrt.locking`); see `design/loops/technical.md` §7 "Lock serialization". See `design/loops/technical.md` §7 for the full 11-step flow.
The runner resolves prompt files from `loop.json` `roles.*.prompt` (e.g. `loop-implement.md`), substitutes content-level tokens (`{task_brief}`, `{acceptance_criteria}`, `{next_hint}`, `{artifact_content}`, etc.), writes the resolved prompt to `outputs/tickN-<role>-prompt.md`, and passes it to the harness.
### Configuration (`loop.json`)
| Field | Description |
|-------|-------------|
| `name` | Loop name (kebab-case) |
| `schedule.interval_seconds` | Tick interval for daemon mode |
| `brakes.max_iterations` | Max ticks before halt |
The framework installs a self-improvement loop by default at install time. This loop ticks against `status.py --audit` on the framework's own repo, picking up audit violations and resolving them unattended. It runs every 3600 seconds (1 hour) with `max_iterations: 10` and a score plateau window of 3.
The loop uses a git worktree at `~/.automaton/loops/self-improvement/worktree/` and is scoped to `scripts/`, `prompts/`, `tests/`, and `design/` directories.
**Important**: Always pass `--project` to ensure correct scoping when multiple projects exist. Without it, `status.py` resolves the project from the current directory and errors if not in a project.
### Untracked Tasks
Tasks without `.state` files are UNTRACKED — all commands (`--transition`, `--can-edit`, `--task`, `--approve`) refuse to operate on them. This prevents agents from working on tasks created before v2.0 state enforcement.
The framework enforces the state machine computationally. No phase can be skipped, no approval can be bypassed, and no code edits can happen without a task in an edit-allowed phase. This is enforced through three layers:
1. **Harness pre-edit hook** (`--can-edit`) — blocks edits before they happen. Supported by opencode via the `automaton-guard` plugin.
2. **Git pre-commit hook** — blocks commits when no task is in `implement` or `doc_review` phase. Works for ALL harnesses.
In multi-agent mode, agents claim tasks and discover work via `status.py --claim` and `--next-available`. In single-agent mode (the default), these commands are no-ops.
**Precedence rule**: If a file exists in the project's `.automaton/` directory, the Orchestrator reads it from there. If it doesn't exist, the Orchestrator reads it from the global `~/.automaton/` directory.
This automatically applies changes to all projects — no per-project file update needed.
#### Upgrading an existing project to v2.0
If a project was created before v2.0 state enforcement (`.state` files), it needs an upgrade to bootstrap `.state` files and install the pre-commit hook:
