102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# 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.*
|
|
|
|
### Updating the Framework
|
|
|
|
When the framework is updated, you can update your global installation:
|
|
|
|
```bash
|
|
cd ~/.agent-framework
|
|
./update.sh
|
|
```
|
|
|
|
This will:
|
|
- Fetch the latest changes from the repository
|
|
- Check for uncommitted changes and warn you
|
|
- Pull the latest updates
|
|
|
|
**Upgrading existing projects:** When the framework is updated, existing projects may need their framework files upgraded (new phases added, new prompts, etc.). To upgrade an existing project, tell the agent: "Upgrade the agent-framework for this project." The agent will check for missing files and update them.
|
|
|
|
---
|
|
|
|
## 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. **Interactive** — agent grills you for requirements and gets sign-off.
|
|
2. **Design** (optional): Produce a `DESIGN.md` (Architecture). No code allowed. **Interactive** — agent grills you for design decisions and gets sign-off.
|
|
3. **Implement**: Write code and tests based *only* on the `SPEC.md` (and `DESIGN.md` if present).
|
|
4. **Bug Find**: Aggressive search for bugs and spec deviations.
|
|
5. **Adversarial Bug Find**: Deep search for complex logic errors, race conditions, and performance issues.
|
|
6. **Doc Review**: Review documentation against DESIGN.md plan and fix missing docs.
|
|
7. **Referee**: Objective evaluation of all bugs, docs, and the final verdict.
|
|
|
|
### How to use Autopilot
|
|
|
|
#### Autopilot mode
|
|
Add `Autopilot: Enabled` to your project's `.agent-framework/AGENT.md` and just say:
|
|
- **Start a new task**: "Research add user authentication" (the Orchestrator creates the task and drives it all the way to completion)
|
|
- **Continue**: "orchestrate" or "continue" (the Orchestrator finds the most advanced task and drives it)
|
|
|
|
#### Manual mode
|
|
Set `Autopilot: Disabled` (or leave it unset) in `AGENT.md`. The Orchestrator reports the current state and tells you the next command. Then run phases by saying things like:
|
|
- "Research add user authentication" — starts a new task
|
|
- "Design the add-user-auth task" — designs the architecture (optional)
|
|
- "Implement the add-user-auth task" — implements the task
|
|
- "Find bugs in the add-user-auth task" — finds bugs
|
|
- "Perform adversarial bug find for add-user-auth" — deep bug search
|
|
- "Review docs for the add-user-auth task" — reviews documentation
|
|
- "Review the add-user-auth task" — referee evaluates
|
|
- "orchestrate" — asks the Orchestrator what to do next
|
|
|
|
## 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, Design, Implement, Bug Finder, Adversarial Bug Finder, Doc Review, Referee, etc.).
|
|
- `workflow.md`: The state machine governing the Autopilot lifecycle.
|
|
|
|
## Contact & Support
|
|
[Insert Contact Info]
|