automaton/prompts/workflow.md

Workflow State Machine

This file defines the linear progression of a task in automaton. The Orchestrator uses this to determine the next phase.

Single Source of Truth: .state File

The .state file in each task folder is the canonical indicator of a task's current phase. It takes precedence over artifact-based heuristic.

• Location: tasks/{task-name}/.state
• Content: A single phase name (e.g., research, research:awaiting_approval, implement, complete)
• Atomic writes: Written to .state.tmp first, then renamed to .state
• If .state is missing: Fall back to artifact-based heuristic and write .state with the inferred phase

.state.approvals Log

Each task has a .state.approvals file recording all user approvals:

• Location: tasks/{task-name}/.state.approvals
• Format: One line per approval: {phase}:approved|{ISO-8601-timestamp}|{approver}
• Append-only: Approvals are never deleted
• Metadata: Not a phase deliverable, excluded from artifact checks

.state.lock (Multi-Agent Mode Only)

When Mode: multi-agent is set in .agent.md, a .state.lock file tracks which agent has claimed the task:

• Location: tasks/{task-name}/.state.lock
• Format: agent: {id}, phase: {current}, claimed: {timestamp}, expires: {timestamp}
• Atomic writes: Same .tmp pattern as .state
• Default timeout: 30 minutes (configurable in .agent.md)
• Metadata: Not a phase deliverable, excluded from artifact checks

Task Lifecycle

Current State	Signal	Next Phase	Action
New Task	status.py --create-task {name} --project {project} creates folder with .state = new	Research	Generate SPEC.md
Research	Has .state = research	research:awaiting_approval	Present SPEC.md draft for user sign-off
research:awaiting_approval	Has .state = research:awaiting_approval	research:approved	User says "APPROVED", call status.py --approve
research:approved	Has .state = research:approved	Decomposition (optional) or Design (optional) or Implement	Transition via status.py --transition
Decomposition	Has .state = decomposition	decomposition:awaiting_approval	Present DECOMPOSITION.md draft for user sign-off
decomposition:awaiting_approval	Has .state = decomposition:awaiting_approval	decomposition:approved	User says "APPROVED", call status.py --approve
decomposition:approved	Has .state = decomposition:approved	Sub-task Research	Orchestrator creates sub-task folders
Design	Has .state = design	design:awaiting_approval	Present DESIGN.md draft for user sign-off
design:awaiting_approval	Has .state = design:awaiting_approval	design:approved	User says "APPROVED", call status.py --approve
design:approved	Has .state = design:approved	Test Design (optional) or Implement	Transition via status.py --transition
Test Design	Has .state = test_design	test_design:awaiting_approval	Present TEST_PLAN.md draft for user sign-off
test_design:awaiting_approval	Has .state = test_design:awaiting_approval	test_design:approved	User says "APPROVED", call status.py --approve
test_design:approved	Has .state = test_design:approved	Implement	Transition via status.py --transition
Implementation	Has .state = implement	Bug Find	Generate BUG_REPORT.md
Bug Find	Has .state = bug_find	Adversarial Bug Find	Generate ADVERSARIAL_BUG_REPORT.md
Adversarial Bug Find	Has .state = adversarial_bug_find	Doc Review	Generate DOC_REVIEW.md
Doc Review	Has .state = doc_review	Referee	Generate VERDICT.md
Referee	Has .state = referee	Complete / Human Intervention	Finalize or request user intervention

Phases Without Approval Gates

The following phases do not have :awaiting_approval sub-states because they do not require interactive user sign-off:

• implement, bug_find, adversarial_bug_find, doc_review, referee
• These transition directly to the next phase upon producing their artifact and calling status.py --transition

Task Creation (via status.py)

New tasks MUST be created via status.py --create-task {name} --project {project}. This creates the folder, .state = new, and an empty .state.approvals file.

Manual task folder creation (mkdir tasks/my-task) is flagged as a violation by status.py --audit and status.py --validate-folder.

Tasks without .state files are UNTRACKED. All commands (--transition, --can-edit, --task, --approve) refuse to operate on them. Run status.py --upgrade --project {project} to bootstrap .state files for pre-v2.0 tasks.

Task creation from bugs

When the Orchestrator detects a VERDICT.md with FAIL or NEEDS_REVIEW, it uses status.py --create-task --project {project} to create fix/review/tiebreak tasks. The Orchestrator also copies relevant artifacts (SPEC.md, BUG_REPORT.md, etc.) and sets .state to the appropriate phase (e.g., bug_find for fix tasks).

Enforcement via status.py

Phase-Gated Transitions

All transitions go through status.py --transition {phase} --project {project}:

• Only legal transitions are allowed (defined in LEGAL_TRANSITIONS)
• :awaiting_approval phases can only transition to :approved via status.py --approve --project {project}
• Required artifacts must exist and be non-empty before transitioning
• Forbidden artifacts (from future phases) block transitions

Folder Validation

status.py --validate-folder --task {name} --project {project} checks for:

• Out-of-order artifacts (artifacts from future phases)
• Missing .state file (manually created task)
• Phase-artifact inconsistency

Audit

status.py --audit --project {project} checks all tasks for:

• Category 1: Out-of-order artifacts
• Category 2: State-artifact inconsistency
• Category 3: Unauthorized git modifications (if git repo)
• Category 4: Manually created task folders (no .state)

Approval Gates

status.py --approve --task {name} --project {project} transitions from :awaiting_approval to :approved:

• Records approval in .state.approvals with timestamp and approver
• Refuses if not in an :awaiting_approval sub-state
• Refuses for phases that don't require approval

Autopilot Rules

1. Linear Progression: Never skip a phase. Each transition must go through status.py --transition --project {project}.
2. Approval Gates: Research, Decomposition, Design, and Test Design phases require explicit user approval before proceeding. The autopilot MUST pause at :awaiting_approval sub-states.
3. Artifact Check: A phase is only considered "complete" if its corresponding artifact exists, is non-empty, AND the .state file reflects the completed phase.
4. Folder Validation: Before each phase transition, run status.py --validate-folder --project {project}. Do not proceed past violations.
5. Human Intervention: If the Referee marks a task as FAIL, NEEDS_REVIEW, or identifies "Tie-Breaks", the Autopilot pauses and waits for user input.
6. Task Creation: Always use status.py --create-task --project {project} to create new tasks. Never create task folders manually.
7. Forbidden Actions: Respect the ALLOWED/FORBIDDEN sections in each phase prompt. Even in autopilot, the Orchestrator must not perform forbidden actions.