# 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 **prompt-driven, contract-based workflow framework** for LLM agents. It is intentionally not an agent harness: the framework provides prompts, conventions, scripts, and a dashboard, but enforcement is soft and relies on agent discipline.

## 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
│   ├── migrate-project.sh
│   ├── vram_detect.py
│   └── dashboard.sh
├── prompts/               # Phase-specific LLM prompts
│   ├── orchestrate.md
│   ├── research.md
│   ├── implement.md
│   └── ...
├── contracts/             # Contract checklists
├── templates/             # Task templates
│   └── tasks/
│       ├── bad-impl/
│       ├── research-task/
│       └── subtask-parent/
├── automaton/             # Python dashboard package
│   └── dashboard/
│       ├── __main__.py
│       ├── config.py
│       ├── core/
│       └── ui/
├── tests/                 # pytest suite
└── tasks/                 # Framework development tasks
```

## Build & Test Commands

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

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

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

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

# Start the dashboard
python -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.

## Adding or Updating Prompts

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

## 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:
- `python -m py_compile`
- `python -m pytest tests/`
- `bash -n scripts/*.sh`

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