From 0437cbae6cfccb35a29f92379b817eb66860dfb9 Mon Sep 17 00:00:00 2001 From: Lap Tran Date: Fri, 26 Jun 2026 16:51:39 -0400 Subject: [PATCH] docs: architecture section, FAQ, cross-references, vault-memory update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 15 +++++ README.md | 104 +++++++++++++++++++++++++++++++++++ scripts/automaton-cleanup.sh | 2 +- scripts/install-hooks.sh | 5 ++ 4 files changed, 125 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 70ccf66..a275a3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/`. diff --git a/README.md b/README.md index e7238b8..05e94cf 100644 --- a/README.md +++ b/README.md @@ -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 `. +- 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 -- │ + │ → clones to ~/.automaton/ │ + │ → VRAM detection, guards, venv, self-improvement │ + └────────────────────────┬────────────────────────────┘ + │ + ┌────────────────────────▼────────────────────────────┐ + │ 2. Onboard Project (once per project) │ + │ bash ~/.automaton/scripts/onboard-project.sh │ + │ → 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. diff --git a/scripts/automaton-cleanup.sh b/scripts/automaton-cleanup.sh index 6621a26..7819a21 100755 --- a/scripts/automaton-cleanup.sh +++ b/scripts/automaton-cleanup.sh @@ -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" diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh index 33fe035..e15cd8d 100755 --- a/scripts/install-hooks.sh +++ b/scripts/install-hooks.sh @@ -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