# AGENTS.md — Automaton Framework

This file contains the information coding agents need to work effectively on the automaton framework itself.

## Project Overview

Automaton is a **contract-based, state-enforced workflow framework** for LLM agents. The framework enforces disciplined engineering workflows computationally via `.state` files, `status.py` phase gates, and approval gates — not just via prompts.

## Repository Layout

```
~/.automaton/
├── .agent.md              # Global router (autopilot mode, task routing)
├── .rules.md              # Global rules and failure modes
├── system-prompt.md       # Session startup prompt
├── config.md              # Global VRAM/model configuration
├── README.md              # Human-facing documentation
├── AGENTS.md              # This file
├── CHANGELOG.md           # Release notes
├── scripts/               # Bash/Python helper scripts
│   ├── install.sh
│   ├── update.sh
│   ├── upgrade.sh          # Upgrades projects to v2.0 (bootstraps .state files)
│   ├── migrate-project.sh
│   ├── status.py            # Phase enforcement, transitions, audits, claiming, can-edit
│   ├── vram_detect.py
│   ├── git-hooks/           # Git hooks for enforcement
│   │   └── pre-commit       # Blocks commits when no task in edit phase
│   └── dashboard.sh
├── prompts/               # Phase-specific LLM prompts
│   ├── orchestrate.md
│   ├── research.md
│   ├── implement.md
│   └── ...
├── contracts/             # Contract checklists and integration docs
│   └── harness-integration.md  # Harness integration contract
├── plugins/               # Agent harness plugins
│   └── automaton-guard/    # opencode pre-edit guard plugin
├── templates/             # Task templates
│   └── tasks/
│       ├── bad-impl/
│       ├── research-task/
│       └── subtask-parent/
├── automaton/             # Python dashboard package
│   └── dashboard/
│       ├── __main__.py
│       ├── config.py
│       ├── core/
│       └── ui/
├── design/                # Design docs for major features
│   ├── loops/             # Loop engineering system (v1 locked)
│   └── framework/         # Framework agent features (rule agents, Agent tab, model-divergence)
├── tests/                 # pytest suite
└── tasks/                 # Framework development tasks
```

## Build & Test Commands

*Install: `pip3 install -r requirements.txt`*

```bash
# Compile all Python files
python3 -m py_compile automaton/**/*.py automaton/dashboard/**/*.py

# Run the test suite
python3 -m pytest tests/ -v

# Run a single test file
python3 -m pytest tests/test_task.py -v

# Syntax-check shell scripts
bash -n scripts/*.sh

# Start the dashboard
python3 -m automaton.dashboard
```

## Conventions

- **Prompts** live in `prompts/` and use `{placeholder}` syntax.
- **Task paths** must always be written as `{project}/.automaton/tasks/{task-name}/`.
- **Scripts** should be written in Python if they need complex parsing or testing; Bash is OK for simple glue.
- **Tests** are required for any new Python code or significant script logic.
- **No orchestrator runtime** — keep the framework prompt-driven. Do not add an agent harness.
- **No Rust rewrite** — Python/Bash are the implementation languages.
- **State enforcement** — all phase transitions must go through `status.py --transition`. All task creation must go through `status.py --create-task`. All approvals must go through `status.py --approve`.

## State Enforcement (v2.0)

The framework enforces the state machine computationally:

- **`.state` file**: Each task has a `.state` file that is the single source of truth for its current phase
- **`status.py --transition`**: All phase transitions must go through this command; illegal transitions are refused
- **Approval gates**: Research, Decomposition, Design, and Test Design phases require explicit user approval before proceeding (`:awaiting_approval` → `:approved`)
- **`status.py --validate-folder`**: Detects out-of-order artifacts (phase skipping)
- **`status.py --audit`**: Comprehensive audit across all tasks for violations
- **`status.py --create-task`**: The only valid way to create task folders
- **`status.py --upgrade`**: Bootstraps `.state` files for pre-v2.0 tasks that lack them
- **FORBIDDEN actions in prompts**: Each phase prompt explicitly lists what agents cannot do
- **Untracked tasks**: Tasks without `.state` files are UNTRACKED. All commands (`--transition`, `--can-edit`, `--task`) refuse to operate on them. Run `--upgrade` to bootstrap `.state` files.

## State Enforcement — Loops (v1)

Loops add a parallel concept: each loop has a `.state.loop` JSON file at `{project}/.automaton/loops/<name>/.state.loop` (framework-internal: `~/.automaton/loops/<name>/`). It is the single source of truth for loop runtime state.

- **`.state.loop`**: `status ∈ {running, halted, paused, complete}`, `halt_reason ∈ {iterations_exhausted, budget_exhausted, verifier_failed, drift_detected, human_intervention}`, `iteration_count`, `last_tick_at`, `score_history`, `current_task`, `worktree_path`.
- **`--create-loop NAME [--from-template T]`**: The only valid way to bootstrap a loop dir + `.state.loop` + `loop.json`.
- **`--check-gate NAME`**: Runs all 6 brake gates (status, iterations, budget, task phase, worktree drift, score plateau). First failure halts the loop and best-effort disables the OS schedule unit.
- **`--approve --loop NAME`**: The only way to clear a halt. Increments `resumed_count`. No auto-approve path in v1.
- **`--transition`**: Refuses to transition any task owned by a HALTED loop until `--approve --loop` clears the halt.
- **Untracked loops**: Loop dirs without `.state.loop` are UNTRACKED. All `--loop` commands refuse; `--audit` flags them.
- **`.state.lock` (v1.1)**: Cross-process file lock serializes read-modify-write cycles on `.state.loop`. POSIX `fcntl.flock`, Windows `msvcrt.locking`. Per-loop granularity (`<loop_path>/.state.lock`), blocking acquire, no timeout in v1.1. The runner holds the lock across the entire tick (gate → harness → state write). `--pause-loop`, `--resume-loop`, `--approve --loop`, `--check-gate` in status.py each acquire the lock around their read-modify-write blocks. `--create-loop` is unwrapped. The runner sets `$AUTOMATON_NO_LOOP_LOCK=1` in the `--check-gate` subprocess env ONLY (avoids self-deadlock on the parent's held flock); harness subprocesses do NOT inherit the env var. See `design/loops/technical.md` §7 "Lock serialization".
- **Loop runner**: `scripts/loop-runner.py --mode tick --loop <name> --project <p>` is the per-tick engine. Called by the `automaton-loop-tick.{sh,bat}` stub that `--install-schedule` generates. It calls `--check-gate` first; any non-ok gate exits 0 (clean scheduler exit). Also supports `--mode daemon` (Python sleep loop) and `--json` machine-readable output. See `design/loops/technical.md` §7 for the 11-step tick flow.

## Harness Integration

`status.py --can-edit` provides a pre-edit gate that any agent harness can call before allowing file modifications. This is the primary enforcement layer. See `contracts/harness-integration.md` for the full integration contract.

The framework provides three enforcement layers:

1. **Harness pre-edit hook** (`--can-edit`) — blocks edits before they happen. Supported by opencode via the `automaton-guard` plugin at `plugins/automaton-guard/`.
2. **Git pre-commit hook** (`scripts/git-hooks/pre-commit`) — blocks commits when no task is in an edit-allowed phase. Works for ALL harnesses.
3. **Prompt-based rules** (ALLOWED/FORBIDDEN sections) — advisory only, relies on agent discipline.

Modes:
- `--can-edit --project {p}` — Is editing allowed on this project? (checks for tasks in implement/doc_review)
- `--can-edit --project {p} --file {path}` — Same, plus file scope check
- `--can-edit --project {p} --task {t}` — Is this specific task in an edit-allowed phase?
- `--can-edit --project {p} --task {t} --file {path}` — Same, plus file scope check
- `--can-edit --project {p} --loop {name} [--loop-worktree] --file {path}` — Loop worktree scope check: is the file inside this loop's declared `blast_radius.file_scope`? `--loop-worktree` treats the path as worktree-relative; otherwise the absolute path must be inside the project/framework root.
- Add `--json` for machine-readable output

## Adding or Updating Prompts

1. Edit the relevant file in `prompts/`.
2. Run `python3 -m pytest tests/test_prompt_paths.py` to ensure task paths are canonical.
3. Update `CHANGELOG.md` under `[unreleased]`.

## Script Cross-References

The framework provides three lifecycle scripts that should be referenced from each other:

| Script | Purpose | Called when | Next step |
|---|---|---|---|
| `scripts/install.sh` | Install framework on a fresh machine | `curl \| bash` or `git clone + bash` | → `scripts/onboard-project.sh` |
| `scripts/onboard-project.sh` | Bootstrap automaton in a project | After framework install, per project | → `status.py --create-task` |
| `scripts/install-hooks.sh` | Install git hooks per project | After onboarding, or manually | see `onboard-project.sh` |

- `install.sh` outputs "Next: onboard-project.sh" at the end.
- `onboard-project.sh` outputs "Next: status.py --create-task" at the end.
- `install-hooks.sh` is called by `onboard-project.sh` automatically.
- `update.sh` does NOT call `onboard-project.sh` — it only updates the framework.

## Adding a New Script

1. Place the script in `scripts/`.
2. Make it executable if it is entry-point code (`chmod +x`).
3. Add tests in `tests/` if the script is Python.
4. Update `README.md` and any prompts that reference it.

## Dashboard Development

- The dashboard is a **web application** served by a Python HTTP server.
- Static assets are in `automaton/dashboard/html/`.
- Core logic is in `automaton/dashboard/core/`.
- The dashboard is scope-aware: framework mode when run from `~/.automaton/`, project mode otherwise.

## CI

Gitea CI runs on every push:
- `python3 -m py_compile`
- `python3 -m pytest tests/`
- `bash -n scripts/*.sh`

See `.gitea/workflows/ci.yml`.