automaton/AGENTS.md

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

# 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.