Lap Tran
f32f98575b
CI / build (push) Has been cancelled
runnable-test-suite (parent) — complete. Three sub-tasks all complete: - make-tests-runnable: add requirements.txt pinning pytest==7.4.4, sweep all docs/prompts from bare 'python' to 'python3' (stock macOS/Windows ships python3), add idempotent .venv install block to scripts/install.sh, and add 'from __future__ import annotations' to 3 dashboard modules using PEP 604 union syntax at definition time so they import on Python 3.9+. The PEP 604 bug was caught by the streak verifier itself during implementation. - vram-detect-cross-platform: scripts/vram_detect.py now branches on platform.system() for Linux/Darwin/Windows. macOS path uses system_profiler SPDisplaysDataType (Apple Silicon unified memory via sysctl hw.memsize; Intel Macs via 'VRAM (Total):'). Windows uses wmic path win32_VideoController get AdapterRAM with PowerShell fallback. Linux /proc/meminfo and nvidia-smi/lspci paths unchanged (regression test locks them). Added 14 local-LLM context-window entries (llama-3.1, qwen2.5, mistral, deepseek-r1/v3, glm-4/4.5, gemma-2, phi-3/4) with source-cited model cards. Added _probe_ollama_model() that runs 'ollama list' as a last-resort fallback. run_command() now wraps PowerShell cmdlets on Windows (['powershell', '-NoProfile', '-NoLogo', '-Command', ...]). - vram-detect-cross-platform-tests: 11 new monkeypatched tests in tests/test_vram_detect.py covering Linux/Darwin/Windows branches for detect_ram and detect_gpu_vram, prefix-match for unknown model names, ollama probe, Windows PowerShell wrapper, and a LOCKED regression test for _detect_ram_linux(). All external subprocess/sysctl/wmic calls are mocked; no live hardware probes. Suite total: 235 passed, 0 errors. Verified on this box: gpu_vram_gb 0 -> 32 on Apple M5 (32GB unified memory), target context correctly jumped 12k -> 42k. Subtask-2 implementation was authored by local LLM (gemma-4-26B-A4B-it via headroom proxy @ localhost:8787). The 10-consecutive-clean-pass streak verifier ran as the independent checker model (article #2/#9/#13 in 'WTF Is a Loop? Part 2'). One anti-spin rail fired: local LLM produced inline branches where subtask-3 tests expected private _detect_ram_linux() helper; extracted helper to match the test contract without weakening tests. Parent + all 3 subtasks complete. Prior opencode-subagent implementation of subtask-2 preserved in git stash for reference.
144 lines
6.5 KiB
Markdown
144 lines
6.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 **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/
|
|
├── 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.
|
|
|
|
## 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
|
|
- 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]`.
|
|
|
|
## 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`.
|