docs: architecture section, FAQ, cross-references, vault-memory update
README.md:
- Added §1.5 'Architecture: Framework vs Project' with directory tree
and lifecycle flow diagram
- Added §2.5 FAQ covering coexistence, hooks, loops, multi-project
- Updated install section already done in prior commit
AGENTS.md:
- Added 'Script Cross-References' table mapping install.sh →
onboard-project.sh → status.py --create-task
scripts/install-hooks.sh:
- Updated header to reference onboard-project.sh as caller
- Added 'Next step' line pointing to --create-task
vault-memory CONTEXT.md:
- Updated test count (518→611)
- Added new scripts (detect_models.py, onboard-project.sh)
- Documented install/onboard flow and split architecture
This commit is contained in:
Lap Tran
@@ -136,6 +136,21 @@ Modes:
|
||||
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/`.
|
||||
|
||||
@@ -51,6 +51,73 @@ If a project was set up under the old model (with copies of framework files), it
|
||||
|
||||
---
|
||||
|
||||
## 1.5 Architecture: Framework vs Project
|
||||
|
||||
Automaton uses a **split architecture** — one shared framework, many project `./.automaton/` directories:
|
||||
|
||||
```
|
||||
~/.automaton/ ← Framework (installed once per machine)
|
||||
├── scripts/ ← shared tooling: status.py, loop-runner.py
|
||||
├── prompts/ ← shared LLM prompts
|
||||
├── plugins/ ← shared harness plugins
|
||||
├── templates/ ← shared task & loop templates
|
||||
├── .automaton/tasks/ ← framework housekeeping tasks (self-improvement)
|
||||
└── .automaton/loops/ ← framework loops (self-improvement loop)
|
||||
|
||||
~/projects/my-app/
|
||||
└── .automaton/ ← Project (onboarded once per project)
|
||||
├── tasks/ ← YOUR project's tasks
|
||||
├── models.json ← YOUR project's model config
|
||||
├── config.md ← YOUR project's VRAM config
|
||||
├── project-name.md ← YOUR project's display name
|
||||
└── loops/ ← YOUR project's loops
|
||||
```
|
||||
|
||||
**Key rules:**
|
||||
|
||||
- The agent is **scope-aware**: if you're inside `~/.automaton/`, it operates in **framework mode** (reads framework tasks). If you're inside a project dir, it operates in **project mode** (reads project tasks). They never interfere.
|
||||
- All framework scripts (`status.py`, etc.) live in `~/.automaton/scripts/` and are shared — never copied into projects.
|
||||
- Framework prompts live in `~/.automaton/prompts/` — projects reference them by path at runtime.
|
||||
- Git hooks are **per-project**. Each project installs its own via `bash ~/.automaton/scripts/install-hooks.sh <project-path>`.
|
||||
- The self-improvement loop targets **only** the framework itself. Your project won't get framework-level tasks in its board.
|
||||
- You can work on both at the same time in different terminals — independent `.automaton/` directories, shared tooling.
|
||||
|
||||
### Lifecycle overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ 1. Install Framework (once per machine) │
|
||||
│ curl .../install.sh | bash -s -- <git-url> │
|
||||
│ → clones to ~/.automaton/ │
|
||||
│ → VRAM detection, guards, venv, self-improvement │
|
||||
└────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼────────────────────────────┐
|
||||
│ 2. Onboard Project (once per project) │
|
||||
│ bash ~/.automaton/scripts/onboard-project.sh <dir> │
|
||||
│ → creates .automaton/ skeleton │
|
||||
│ → probes models, writes config.md │
|
||||
│ → git init + hooks │
|
||||
└────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼────────────────────────────┐
|
||||
│ 3. Create Task (per feature) │
|
||||
│ python3 ~/.automaton/scripts/status.py │
|
||||
│ --create-task my-feature --project . │
|
||||
└────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼────────────────────────────┐
|
||||
│ 4. Work Through Phases (per task) │
|
||||
│ status.py --transition research --task my-feature │
|
||||
│ → agent writes SPEC.md │
|
||||
│ status.py --transition implement --task my-feature │
|
||||
│ → agent writes code + IMPLEMENTATION.md │
|
||||
│ ... → complete │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Project Setup (Per project)
|
||||
|
||||
Once the framework is installed globally, you must "onboard" every individual project you work on.
|
||||
@@ -113,6 +180,43 @@ The self-improvement loop installed by default targets the **framework itself**
|
||||
|
||||
---
|
||||
|
||||
## 2.5 FAQ
|
||||
|
||||
### Can I work on the framework and a project at the same time?
|
||||
Yes. They have separate `.automaton/` directories. Open two terminals:
|
||||
```
|
||||
Terminal 1: cd ~/.automaton → framework mode
|
||||
Terminal 2: cd ~/projects/my-app → project mode
|
||||
```
|
||||
The agent detects scope from your current directory. Each can have its own tasks, loops, and config. They share the same `~/.automaton/scripts/` binaries.
|
||||
|
||||
### Why doesn't `install.sh` need a Git URL when run from the repo?
|
||||
Because the framework is already cloned. `install.sh` skips cloning when `~/.automaton/` exists and runs all the setup steps (VRAM detection, pip deps, self-improvement loop, guards). The Git URL is only required for a fresh install via `curl | bash`.
|
||||
|
||||
### Do I need to run `install.sh` again after pulling updates?
|
||||
No. `git pull` inside `~/.automaton/` updates the code. The self-improvement loop and guards persist across updates. If you want to re-register guards (e.g. after switching harnesses), run `bash ~/.automaton/scripts/register-guards.sh`.
|
||||
|
||||
### How do git hooks work per project?
|
||||
Each project installs its own hooks via:
|
||||
```bash
|
||||
bash ~/.automaton/scripts/install-hooks.sh /path/to/project
|
||||
```
|
||||
The pre-commit hook blocks commits when no task is in `implement` or `doc_review` phase. The pre-push hook catches `--no-verify` bypasses. They're independent per repo.
|
||||
|
||||
### Can I have multiple projects onboarded at once?
|
||||
Yes. Each project gets its own `.automaton/` directory. Run `onboard-project.sh` once per project. The shared scripts in `~/.automaton/scripts/` enforce the state machine on whichever project you point `--project` at.
|
||||
|
||||
### What about loops on my project?
|
||||
The self-improvement loop runs only on the framework. To add a loop to your project:
|
||||
```bash
|
||||
python3 ~/.automaton/scripts/status.py --create-loop my-loop \
|
||||
--from-template self-improvement --project /path/to/project
|
||||
python3 ~/.automaton/scripts/status.py --install-schedule my-loop \
|
||||
--interval 3600 --project /path/to/project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Autopilot Workflow
|
||||
The framework features an **Autopilot** mode that allows the agent to drive a project to completion with minimal intervention.
|
||||
|
||||
|
||||
@@ -1,2 +1,2 @@
|
||||
#!/usr/bin/env bash
|
||||
python3 "/Users/laptran/.automaton/scripts/status.py" --cleanup-done --days 7 --project "/private/var/folders/f5/yv0dzbnx47x3yp8sc_2519gh0000gn/T/pytest-of-laptran/pytest-128/test_uninstall_via_disabled_re0"
|
||||
python3 "/Users/laptran/.automaton/scripts/status.py" --cleanup-done --days 7 --project "/private/var/folders/f5/yv0dzbnx47x3yp8sc_2519gh0000gn/T/pytest-of-laptran/pytest-129/test_uninstall_via_disabled_re0"
|
||||
|
||||
@@ -3,9 +3,14 @@
|
||||
#
|
||||
# Usage: bash ~/.automaton/scripts/install-hooks.sh [project-path]
|
||||
#
|
||||
# Called automatically by onboard-project.sh. Can also be run manually
|
||||
# after framework updates to refresh hooks.
|
||||
#
|
||||
# Installs pre-commit and pre-push hooks. The pre-commit hook blocks
|
||||
# commits when no task is in implement/doc_review. The pre-push hook
|
||||
# blocks pushes in the same condition, catching --no-verify bypasses.
|
||||
#
|
||||
# Next step: python3 ~/.automaton/scripts/status.py --create-task --project .
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
|
||||
Reference in New Issue
Block a user