Implement Autopilot mode: state machine, adversarial bug finding, and proactive orchestration

README.md

@@ -1,67 +1,36 @@
-# agent-framework
+# Agent Framework
 
-Minimal, prompt-driven agent framework for Claude Code / Codex / any CLI agent.
+A contract-based operating system for LLM agents, designed to enforce disciplined engineering workflows.
 
-Radical simplicity. One focused session per task. Context hygiene first.
+## Core Philosophy
+The framework prevents agents from "hallucinating" features or jumping into code without a plan. It enforces a strict separation between **Planning (Research)** and **Execution (Implementation)**, mediated by a **Verification** loop.
 
-## Install (One-time)
+## The Autopilot Workflow
+The framework features an **Autopilot** mode that allows the agent to drive a project to completion with minimal intervention.
 
-```bash
-git clone https://gitea.yourdomain.com/you/agent-framework.git ~/.agent-framework
-```
+### Lifecycle of a Task
+1.  **Research**: Produce a `SPEC.md` (Contract). No code allowed.
+2.  **Implement**: Write code and tests based *only* on the `SPEC.md`.
+3.  **Bug Find**: Aggressive search for bugs and spec deviations.
+4.  **Adversarial Bug Find**: Deep search for complex logic errors, race conditions, and performance issues.
+5.  **Referee**: Objective evaluation of all bugs and the final verdict.
 
-That's it. The framework now lives at `~/.agent-framework`.
+### How to use Autopilot
+Add `Autopilot: Enabled` to your project's `.agent-framework/AGENT.md` and use the following command:
 
-## Per-Project Setup
+> *"Initialize Autopilot for this project. Scan the tasks/ directory and report the current status of all tasks and the recommended next actions."*
 
-Every project only needs two files:
+The agent will then:
+- Scan the `tasks/` directory.
+- Identify the current phase of every task based on existing artifacts.
+- Recommend the next command to progress each task.
+- Automatically move to the next phase once the current one's artifacts are produced.
 
-```bash
-mkdir -p /path/to/project/.agent-framework
-```
+## Key Components
+- `AGENT.md`: Project-specific configuration and mode selection.
+- `RULES.md`: Living document of project constraints and past failure modes.
+- `prompts/`: Specialized system prompts for each phase (Research, Implement, Bug Finder, etc.).
+- `workflow.md`: The state machine governing the Autopilot lifecycle.
 
-Create:
-
-- `.agent-framework/AGENT.md` — project router (points to global framework)
-- `.agent-framework/RULES.md` — project-specific hard constraints
-
-Then run the onboarding prompt:
-
-> "Onboard this project to the agent framework"
-
-## Usage
-
-All work happens through prompts in `~/.agent-framework/prompts/`:
-
-### Core Phases
-- Research → `prompts/research.md` (produces SPEC.md)
-- Design → `prompts/design.md` (produces DESIGN.md) — recommended for greenfield projects
-- Implement → `prompts/implement.md`
-
-### Quality Phases (Optional)
-- Bug finding → `prompts/bug_finder.md`
-- Disprove → `prompts/disprover.md`
-- Referee → `prompts/referee.md`
-
-### Other
-- Onboarding → `prompts/onboarding.md`
-- Compaction → `prompts/compaction.md`
-- Orchestrate → `prompts/orchestrate.md`
-
-See `ONBOARDING.md` for detailed drop-in vs from-scratch scenarios and the full philosophy.
-
-## Principles
-
-- Less is more
-- Separate research from implementation (fresh sessions)
-- AGENT.md is a lightweight if/else router, not a dump
-- Clear contracts and stop conditions
-- Multi-agent verification loop when quality matters
-
-## Updating
-
-Pull the latest changes anytime:
-
-```bash
-cd ~/.agent-framework && git pull
-```
+## Installation
+Clone the repository and set up your project following the instructions in `ONBOARDING.md`.