Lap Tran
4b3d92c9a2
Design docs in design/framework/ covering:
- Model-divergence enforcement (conflict matrix, modes, auto-assignment)
- Rule Proposer agent (daily scan, proposes rules to RULE_PROPOSALS.md)
- Rule Reviewer agent (monthly consolidation, different LLM than Proposer)
- Agent tab redesign (phase roles + scheduled jobs, remove fake types)
- Schedules, conflict-of-interest, success criteria
Cross-references updated in AGENTS.md, README.md, CHANGELOG.md,
.onboarding.md, prompts/onboarding.md, design/loops/{README,BACKLOG}.md,
memory/v1-1-hardening-session.md.
Also restores scripts/automaton-cleanup.sh stub (was corrupted by
pytest test leak writing temp path into real stub).
123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# 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`.
|