103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
|
# 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`.
|