hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1d36c0e4ad55fd1792b059f9e53904e9b70596ad
automaton/.onboarding.md
T
gitea 05c76852a2
CI / build (push) Has been cancelled
Details
v2.0: state enforcement, project scoping, harness integration 
State Enforcement (v2.0):
- .state file as single source of truth for task phase
- Approval gates for research, decomposition, design, test_design
- status.py --transition refuses illegal phase transitions
- status.py --validate-folder detects out-of-order artifacts
- status.py --audit checks all tasks for violations
- status.py --create-task is the only valid way to create tasks
- Pre-v2.0 tasks without .state are UNTRACKED -- all commands refuse them
- New --upgrade command bootstraps .state files for existing tasks

Project Scoping:
- --project flag added to all status.py commands across 16+ files
- _find_project_dir errors instead of silently falling back to ~/.automaton/
- --scope-check marks framework files OUT_OF_SCOPE when working on a project
- Dashboard handlers use stored project_root instead of re-detecting from CWD
- Prompts reference ~/.automaton/scripts/vram_detect.py (not {project}/.automaton/)

Harness Integration:
- status.py --can-edit now supports project-level checks (no --task required)
- --can-edit --file checks file scope without --task
- --json output for machine-readable harness integration
- opencode plugin (plugins/automaton-guard/plugin.ts) intercepts edit/write
- Git pre-commit hook (scripts/git-hooks/pre-commit) blocks commits without task
- Formal integration contract (contracts/harness-integration.md)

Other:
- upgrade.sh delegates to status.py --upgrade instead of manual heuristics
- Phase prompts reference --project {project} for multi-project scoping
- 200 tests passing (14 new)
2026-06-15 14:16:46 -04:00

5.7 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink