agent-framework/README.md

# Agent Framework

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

## 1. Global Framework Installation (One-time setup)

Before you can use the framework in any project, you must install the core logic into your local environment.

**Run these commands in your terminal:**

```bash
# Clone the framework into the global config directory
git clone [INSERT_FRAMEWORK_REPO_URL_HERE] ~/.agent-framework

# Enter the directory
cd ~/.agent-framework

# Make the installation script executable and run it
chmod +x install.sh
./install.sh
```
*Note: This creates the "brain" of the framework (prompts, state machines, and rules) in your home directory.*

---

## 2. Project Setup (Per project)

Once the framework is installed globally, you must "onboard" every individual project you work on.

### Option A: The Agent-Driven Way (Recommended)
If you want the agent to handle the configuration for you, navigate to your project root and run:

> *"Onboard this project into the agent-framework."*

The agent will automatically:
1. Detect your project type (New, Existing, or Upgrade).
2. Create the `./.agent-framework/` directory.
3. Generate your `AGENT.md` and `RULES.md` files.
4. Initiate the "Exploration Ritual" to understand your codebase.

### Option B: The Manual Way
If you prefer to set it up manually, create a `.agent-framework/` directory in your project root and add:
- `AGENT.md`: Project-specific configuration (Mode, rules, etc.).
- `RULES.md`: Project-specific constraints and past failure modes.

---

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

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

## Contact & Support
[Insert Contact Info]