Adding direction documentation and GitHub Actions workflows to coordinate the autonomous AI agent with human oversight.
The Problem with Unconstrained Autonomy
An AI agent that can modify any file in a repository without constraint will eventually modify the wrong file. Not from malice, but from misunderstanding: a sufficiently broad objective ("optimize the subscription service") could justify almost any change to almost any file. Checkout logic, payment webhooks, authentication flows — all of these could plausibly be targets of optimization.
The control plane exists to make the boundaries explicit and machine-enforceable. The AI knows what it's allowed to change because those boundaries are documented. The CI system verifies compliance with those boundaries on every PR. Human approval is required for anything outside them.
TASKS.yaml as the Interface
The control plane is organized around a TASKS.yaml file that defines the queue of approved work. Each task has an ID, a status (ready/in_progress/done), an allowed_paths list (which files the task may modify), and a forbidden_paths list (which files it must not touch). The AI agent is only permitted to work on tasks with ready status, and only permitted to touch files within the task's allowed_paths.
A policy check script (scripts/policy_check.py) runs on every PR, reads the task ID from the PR title, validates the changed files against the task's allowed and forbidden paths, and fails the CI check if anything is out of scope. This makes scope violations immediately visible — no AI PR can merge without passing the policy gate.
The Overseer Agent
A separate overseer agent runs on a two-hour schedule. It reads the current project state (PLAN.md, TASKS.yaml, recent git history), evaluates whether the project is on track, and updates PLAN.md if significant state changes have occurred. The overseer is not an implementer — it never touches product code. It's an observer that maintains a living record of project status for both the human admin and the implementing agent to reference.
This creates a three-layer architecture: the human admin who approves the direction and manages TASKS.yaml, the overseer agent that monitors progress and flags deviations, and the implementing agent that executes approved tasks. Each layer has a different scope of authority and a different cadence of operation. The freeze flag cuts through all layers — when set, all agent activity halts regardless of task status.
Experiment Context
- Commit
- b78fe8a
- Mutation rationale
- feat: add direction documentation + automation control plane (closes #37)
- Last reviewed
- February 21, 2026