agent-framework/README.md

# Agent Framework

A contract-based operating system for LLM agents, designed to enforce disciplined engineering workflows.

## 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.

## The Autopilot Workflow
The framework features an **Autopilot** mode that allows the agent to drive a project to completion with minimal intervention.

### 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.

### How to use Autopilot
Add `Autopilot: Enabled` to your project's `.agent-framework/AGENT.md` and use the following command:

> *"Initialize Autopilot for this project. Scan the tasks/ directory and report the current status of all tasks and the recommended next actions."*

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.

## 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.

## Installation
Clone the repository and set up your project following the instructions in `ONBOARDING.md`.