hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate TDD and Grill with Docs into Design, Implementation, and Verification workflows

Browse Source
This commit is contained in:
gitea
2026-06-10 14:46:11 -04:00
parent 59b6339765
commit 3cdb95e083
6 changed files with 151 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ONBOARDING.md
+47 -90
View File
@@ -1,109 +1,66 @@
# Onboarding a Project
## Quick Checklist
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.
- [ ] 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`
## The Exploration Ritual
## Autopilot Mode
The agent's first task in any project is to perform an "Initial Exploration" to establish context.
The framework now includes an **Autopilot** mode driven by the `orchestrate.md` prompt.
### 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`
### 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`:
```markdown
## 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."*
### 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.
---
## Scenario A: Existing Project (Drop-In)
## The Lifecycle of a Project
### 1. Create the Project Framework Directory
```bash
mkdir -p /path/to/project/.agent-framework
```
Once onboarded, the project moves through these phases. The agent should use the provided prompts to transition between them.
### 2. Create the Two Required Files
### Phase 1: Research
**Template**: `prompts/research.md`
**Output**: `SPEC.md`
**Trigger**: *"Research {task-description}"*
#### AGENT.md (project level)
```markdown
# AGENT.md (project-name)
### Phase 2: Implementation
**Template**: `prompts/implement.md`
**Output**: Code changes + test results
**Trigger**: *"Implement the {task-name} task"*
This project uses the global framework at ~/.agent-framework/.
### Phase 3: Bug Finding
**Template**: `prompts/bug_finder.md`
**Output**: `BUG_REPORT.md`
**Trigger**: *"Find bugs in the {task-name} task"*
Additional project rules are in RULES.md.
### Phase 4: Adversarial Verification
**Template**: `prompts/adversarial_bug_find.md`
**Output**: `ADVERSARIAL_BUG_REPORT.md`
**Trigger**: *"Perform adversarial bug find for {task-name}"*
## Mode
Autopilot: Enabled.
```
### Phase 5: Referee
**Template**: `prompts/referee.md`
**Output**: `VERDICT.md`
**Trigger**: *"Review the {task-name} task"*
#### RULES.md (project level)
Start with any hard constraints you already know for this project.
## Prompt Rendering Convention
### 3. Run the Initial Exploration Ritual
Give the agent this prompt in a fresh session:
All prompts are stored as template files in `~/.agent-framework/prompts/`. They use `{placeholder}` syntax.
```
You have been given a new project at this path:
/path/to/project/
### 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.
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.
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.