agent-framework/ONBOARDING.md

Onboarding a Project

This document defines the Agent Protocol for initializing a new project. When the agent is asked to "Onboard a project," it must follow these steps.

The Exploration Ritual

The agent's first task in any project is to perform an "Initial Exploration" to establish context.

Step 1: Discovery

The agent must:

1. Explore the project root using ls and find.
2. Read .agent-framework/AGENT.md
3. Read .agent-framework/RULES.md
4. Read the global ~/.agent-framework/AGENT.md

Step 2: Reporting

The agent must report back with:

• Confirmation that the framework files were found and read.
• A summary of the project rules.
• The expected workflow for this project.
• Key observations from the project structure.

---

The Lifecycle of a Project

Once onboarded, the project moves through these phases. The agent should use the provided prompts to transition between them.

Easier workflow with "orchestrate"

Instead of memorizing trigger phrases for each phase, you can just say "orchestrate" or "continue" and the Orchestrator will:

• In Autopilot mode: automatically drive the task all the way to completion
• In manual mode: tell you the next step and give you the command

Phase 1: Research

Template: prompts/research.md Output: SPEC.md Trigger: "Research {task-description}" (or just "orchestrate" in manual mode) Interaction: Agent will grill you for requirements, edge cases, and constraints. Present draft for review. Get your sign-off before finalizing.

Phase 1b: Design (Optional)

Template: prompts/design.md Output: DESIGN.md Trigger: "Design the {task-name} task" (or just "orchestrate" in manual mode) Interaction: Agent will grill you for design decisions, trade-offs, and constraints. Present draft for review. Get your sign-off before finalizing.

Phase 2: Implementation

Template: prompts/implement.md Output: Code changes + test results Trigger: "Implement the {task-name} task" (or just "orchestrate" in manual mode)

Phase 3: Bug Finding

Template: prompts/bug_finder.md Output: BUG_REPORT.md Trigger: "Find bugs in the {task-name} task" (or just "orchestrate" in manual mode)

Phase 4: Adversarial Verification

Template: prompts/adversarial_bug_find.md Output: ADVERSARIAL_BUG_REPORT.md Trigger: "Perform adversarial bug find for {task-name}" (or just "orchestrate" in manual mode)

Phase 5: Documentation Review

Template: prompts/doc_review.md Output: DOC_REVIEW.md Trigger: "Review docs for the {task-name} task" (or just "orchestrate" in manual mode)

Phase 6: Referee

Template: prompts/referee.md Output: VERDICT.md Trigger: "Review the {task-name} task" (or just "orchestrate" in manual mode)

Prompt Rendering Convention

All prompts are stored as template files in ~/.agent-framework/prompts/. They use {placeholder} syntax.

Placeholders

• {project}: Absolute path to the project root.
• {task-name}: The task folder name (kebab-case).
• {task-description}: A brief, clear summary of the current work.

When the agent receives a trigger command, it must:

1. Read the corresponding template file.
2. Replace all {placeholders} with the actual project values.
3. Execute the rendered prompt.