This clones the framework to `~/.automaton/`, runs VRAM detection, installs pre-edit guards, creates the self-improvement loop, and sets up the Python virtualenv.
### Option B: Clone first
```bash
git clone <your-git-url> ~/.automaton
bash ~/.automaton/scripts/install.sh
```
The script detects that `~/.automaton` already exists, skips the clone, and runs all setup steps (VRAM detection, guards, loop, virtualenv).
### Both methods do the same thing
The git URL is required on fresh install 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.
└── .automaton/ ← Project (onboarded once per project)
├── tasks/ ← YOUR project's tasks
├── models.json ← YOUR project's model config
├── config.md ← YOUR project's VRAM config
├── project-name.md ← YOUR project's display name
└── loops/ ← YOUR project's loops
```
**Key rules:**
- The agent is **scope-aware**: if you're inside `~/.automaton/`, it operates in **framework mode** (reads framework tasks). If you're inside a project dir, it operates in **project mode** (reads project tasks). They never interfere.
- All framework scripts (`status.py`, etc.) live in `~/.automaton/scripts/` and are shared — never copied into projects.
- Framework prompts live in `~/.automaton/prompts/` — projects reference them by path at runtime.
- Git hooks are **per-project**. Each project installs its own via `bash ~/.automaton/scripts/install-hooks.sh <project-path>`.
- The self-improvement loop targets **only** the framework itself. Your project won't get framework-level tasks in its board.
- You can work on both at the same time in different terminals — independent `.automaton/` directories, shared tooling.
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:
### Can I work on the framework and a project at the same time?
Yes. They have separate `.automaton/` directories. Open two terminals:
```
Terminal 1: cd ~/.automaton → framework mode
Terminal 2: cd ~/projects/my-app → project mode
```
The agent detects scope from your current directory. Each can have its own tasks, loops, and config. They share the same `~/.automaton/scripts/` binaries.
### Why doesn't `install.sh` need a Git URL when run from the repo?
Because the framework is already cloned. `install.sh` skips cloning when `~/.automaton/` exists and runs all the setup steps (VRAM detection, pip deps, self-improvement loop, guards). The Git URL is only required for a fresh install via `curl | bash`.
### Do I need to run `install.sh` again after pulling updates?
No. `git pull` inside `~/.automaton/` updates the code. The self-improvement loop and guards persist across updates. If you want to re-register guards (e.g. after switching harnesses), run `bash ~/.automaton/scripts/register-guards.sh`.
The pre-commit hook blocks commits when no task is in `implement` or `doc_review` phase. The pre-push hook catches `--no-verify` bypasses. They're independent per repo.
### Can I have multiple projects onboarded at once?
Yes. Each project gets its own `.automaton/` directory. Run `onboard-project.sh` once per project. The shared scripts in `~/.automaton/scripts/` enforce the state machine on whichever project you point `--project` at.
### What about loops on my project?
The self-improvement loop runs only on the framework. To add a loop to your project:
Pi Dev has the `automaton-guard-pi` plugin (installed by `register-guards.sh`) which blocks edits outside allowed phases. However, Pi Dev does **not** auto-load automaton's system prompt (unlike opencode). For the agent to understand tasks and phases, provide context manually.
**Before starting a Pi Dev session**, run the context printer:
```bash
bash ~/.automaton/scripts/pi-automaton.sh
```
Or if symlinked to `~/bin/`:
```bash
pi-automaton
```
Copy the output and paste it as your first message to the Pi Dev agent. This tells the agent about:
- The automaton workflow framework and phase lifecycle
- Active tasks in the current project
- The default model and VRAM configuration
- Project-specific rules from `AGENTS.md`
- Which commands to use for transitions and task creation
The `automaton-guard-pi` plugin still blocks edits outside `implement`/`doc_review` even without this context — the context printer just makes the agent *aware* of why it's being blocked and how to use the framework correctly.
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:
