gitea
502f47eb21
- Rename AGENT.md -> .agent.md, RULES.md -> .rules.md, ONBOARDING.md -> .onboarding.md - Rename BUG_REPORT.md -> .bug_report.md, ADVERSARIAL_BUG_REPORT.md -> .adversarial_bug_report.md, VERDICT.md -> .verdict.md - Fix onboarding.md references to use new .onboarding.md path - Fix stop-hook-pattern.md reference to use .onboarding.md - Update README.md, config.md, install.sh, update.sh, prompts/*, references/* - VRAM detection script validated and working
3.7 KiB
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:
- Explore the project root using
lsandfind. - Read
.automaton/.agent.md - Read
.automaton/.rules.md - Read the global
~/.automaton/.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 1c: Test Design (Optional)
Template: prompts/test_design.md
Output: TEST_PLAN.md
Trigger: "Design tests for the {task-name} task" (or just "orchestrate" in manual mode)
Interaction: Agent will grill you for test coverage, edge cases, and test strategy. 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)
Note: The implementer follows the TEST_PLAN.md (if present) and implements code with tests using TDD.
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 ~/.automaton/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:
- Read the corresponding template file.
- Replace all
{placeholders}with the actual project values. - Execute the rendered prompt.