agent-framework/ONBOARDING.md

Onboarding a Project

Quick Checklist

• Create .agent-framework/ directory in project root
• Create AGENT.md (project level)
• Create RULES.md (project level)
• Run exploration ritual with agent (fresh session)
• Agent reads global + project AGENT.md and RULES.md
• Create first tasks/{task-name}/ folder
• Start research phase using prompts/research.md

Autopilot Mode

The framework now includes an Autopilot mode driven by the orchestrate.md prompt.

How Autopilot Works

1. State Detection: The agent scans your tasks/ directory and detects the current progress of each task based on the artifacts produced (e.g., SPEC.md, IMPLEMENTATION.md, etc.).
2. Proactive Driving: Instead of waiting for you to tell it what to do next, the agent will recommend the exact command needed to progress to the next phase.
3. Verification Loop: Every task follows a strict lifecycle: Research \rightarrow Implement \rightarrow Bug Find \rightarrow Adversarial Bug Find \rightarrow Referee.

Using Autopilot

To enable Autopilot, add the following to your project's AGENT.md:

## Mode
Autopilot: Enabled.
- The agent should use the Orchestrator to drive tasks to completion.
- When a task is completed, the agent should automatically scan for the next pending task.

When you want the agent to drive the project, 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."

---

Scenario A: Existing Project (Drop-In)

1. Create the Project Framework Directory

mkdir -p /path/to/project/.agent-framework

2. Create the Two Required Files

AGENT.md (project level)

# AGENT.md (project-name)

This project uses the global framework at ~/.agent-framework/.

Additional project rules are in RULES.md.

## Mode
Autopilot: Enabled.

RULES.md (project level)

Start with any hard constraints you already know for this project.

3. Run the Initial Exploration Ritual

Give the agent this prompt in a fresh session:

You have been given a new project at this path:
/path/to/project/

Your first actions must be:
1. Explore the project root using ls and find.
2. Read .agent-framework/AGENT.md
3. Read .agent-framework/RULES.md
4. Read ~/.agent-framework/AGENT.md

Report back with:
- Confirmation the framework files were found and read
- Summary of the project rules
- What process this project expects
- Key observations from the project structure

Do not start any task yet.

---

Scenario B: Starting From Scratch

Follow the same steps as Scenario A, but start by asking the agent to design the initial architecture:

"Help me design the initial architecture for a new project. Here's what I have in mind: {your idea}"

Phase Prompts (Template Files)

Phase	Template	Output	Trigger
Research	research.md	SPEC.md	"Research {task-description}"
Implementation	implement.md	Code + Tests	"Implement the {task-name} task"
Bug Find	bug_finder.md	BUG_REPORT.md	"Find bugs in the {task-name} task"
Adversarial	adversarial_bug_find.md	ADVERSARIAL_BUG_REPORT.md	"Perform adversarial bug find for {task-name}"
Referee	referee.md	VERDICT.md	"Review the {task-name} task"

Core Principles

• Context Is Everything: Separate research from implementation. Use fresh sessions per task.
• Sycophancy Management: Use the multi-agent validation loop (Bug Finder \rightarrow Adversarial \rightarrow Referee) to ensure objective results.
• Clear End States: Tests are mandatory. A task is not complete until all acceptance criteria in the SPEC.md (or CONTRACT.md) are met.
• Rules + Skills: Keep RULES.md specific to this project. Use the global framework for general behavior.