automaton/.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 ~/.automaton/.agent.md (global router)
3. Read ~/.automaton/.rules.md (global framework rules)
4. Read the project's .automaton/.agent.md
5. Read the project's .automaton/.rules.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. State transition: new → research → research:awaiting_approval (awaiting your sign-off) → research:approved (after you say "APPROVED")

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. State transition: design → design:awaiting_approval → design:approved

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. State transition: test_design → test_design:awaiting_approval → test_design:approved

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. No approval gate — transitions directly to bug_find.

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) State transition: bug_find (no approval gate)

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) State transition: adversarial_bug_find (no approval gate)

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) State transition: doc_review (no approval gate)

Phase 6: Referee

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

State Enforcement (v2.0)

All phase transitions are enforced by status.py:

• Tasks are created with python ~/.automaton/scripts/status.py --create-task {name} --project {project}
• Phases are transitioned with python ~/.automaton/scripts/status.py --transition {phase} --task {name} --project {project}
• Approvals are granted with python ~/.automaton/scripts/status.py --approve --task {name} --project {project}
• Folders are validated with python ~/.automaton/scripts/status.py --validate-folder --task {name} --project {project}
• All tasks are audited with python ~/.automaton/scripts/status.py --audit --project {project}
• Pre-v2.0 tasks are upgraded with python ~/.automaton/scripts/status.py --upgrade --project {project}

The .state file in each task folder is the single source of truth for the task's current phase. Never create task directories manually — always use status.py --create-task. Tasks without .state files are UNTRACKED and all commands refuse to operate on them. Run status.py --upgrade to bootstrap .state files for existing tasks.

Important: Always pass --project {project} to ensure correct scoping. Without it, status.py resolves the project from the current working directory, which can target the wrong project when multiple projects exist on the same machine.

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:

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

Backlog

Design backlogs are the framework's outstanding-work store when no active tasks exist. Each design area has its own BACKLOG.md:

• ~/.automaton/design/loops/BACKLOG.md — loop engineering v1.1+ and deferred items.
• ~/.automaton/design/framework/BACKLOG.md — framework-level agent features (rule agents, Agent tab redesign, model-divergence enforcement).

The self-improvement loop consumes these automatically when configured with work_source.kind = "backlog" and work_source.area set to the relevant design area ("loops" or "framework"). For manual work, read the topmost - [ ] item and create a task via status.py --create-task.