# Workflow State Machine

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

## Task Lifecycle

| Current State | Signal (Artifact) | Next Phase | Action |
| :--- | :--- | :--- | :--- |
| **New Task** | Orchestrator creates `tasks/{task-name}/` with **no files** | Research | Generate `SPEC.md` |
| **Research** | Has `SPEC.md` | Decomposition (optional) or Design (optional) or Implement | Generate `DECOMPOSITION.md` or `DESIGN.md` or code |
| **Decomposition** | Has `SPEC.md` and `DECOMPOSITION.md` | Sub-task Research | Orchestrator creates sub-task folders |
| **Design** | Has `DESIGN.md` | Test Design (optional) or Implement | Generate `TEST_PLAN.md` or code |
| **Test Design** | Has `TEST_PLAN.md` | Implement | Generate code and tests |
| **Implementation** | Has `IMPLEMENTATION.md` | Bug Find | Generate `BUG_REPORT.md` |
| **Bug Find** | Has `BUG_REPORT.md` | Adversarial Bug Find | Generate `ADVERSARIAL_BUG_REPORT.md` |
| **Adversarial Bug Find** | Has `ADVERSARIAL_BUG_REPORT.md` | Doc Review | Generate `DOC_REVIEW.md` |
| **Doc Review** | Has `DOC_REVIEW.md` | Referee | Generate `VERDICT.md` |
| **Referee** | Has `VERDICT.md` | Complete / Review | Finalize or request user intervention |

## Task Creation (Orchestrator Responsibility)

The Orchestrator is responsible for creating new task folders automatically — users **never** create task folders manually.

### New tasks from user input
When the Orchestrator detects a new task description:
1. Generate a kebab-case task name from the description
2. Create `{project}/tasks/{task-name}/` (empty — no artifact files)
3. Move the task to the **Research** phase

The Orchestrator also scans for tasks that have `VERDICT.md` with `PASS` and removes them from the active task list (they can be archived but not auto-deleted).

**Key principle**: `IMPLEMENTATION.md` is the artifact produced by the **implementation phase**, not the Orchestrator. The Orchestrator only creates the empty folder; the first real artifact is `SPEC.md` from research.

### Task creation from bugs
When the Orchestrator detects a `VERDICT.md` with `FAIL` or `NEEDS_REVIEW`, the behavior depends on the mode:

**In Manual Mode**: The Orchestrator MUST create new tasks and report them for the user to run:

1. **From `FAIL` verdict**: For each item listed under "Findings" that failed, create a new task:
   - Task name: `{original-task-name}-fix-{issue}` (e.g., `add-user-auth-fix-null-handling`)
   - The Orchestrator creates the folder with an empty `IMPLEMENTATION.md`
   - The task starts at the **Bug Find** phase (skip research — the spec already exists)
   - The Orchestrator copies the original `SPEC.md`, `BUG_REPORT.md`, and `ADVERSARIAL_BUG_REPORT.md` into the new task folder

2. **From `NEEDS_REVIEW` verdict**: For each item listed under "Remaining Issues", create a new task:
   - Task name: `{original-task-name}-review-{issue}` (e.g., `add-user-auth-review-perf`)
   - The Orchestrator creates the folder with an empty `IMPLEMENTATION.md`
   - The task starts at the **Bug Find** phase
   - The Orchestrator copies the original `SPEC.md`, `BUG_REPORT.md`, and `ADVERSARIAL_BUG_REPORT.md` into the new task folder

3. **From "Tasks for Review / Tie-Breaks"**: For each item listed, create a new task:
   - Task name: `{original-task-name}-tiebreak-{issue}` (e.g., `add-user-auth-tiebreak-auth-gateway`)
   - The Orchestrator creates the folder with an empty `IMPLEMENTATION.md`
   - The task starts at the **Research** phase (the tie-break may require spec changes)
   - The Orchestrator copies the original `SPEC.md`, `BUG_REPORT.md`, and `ADVERSARIAL_BUG_REPORT.md` into the new task folder

**In Autopilot Mode**: The Orchestrator should NOT auto-create fix/review/tiebreak tasks — it should pause and report that human intervention is required. The user must decide whether to create fix tasks and how to proceed.

**Note**: When a task starts at the **Bug Find** phase (fix tasks), the Orchestrator skips the Research phase. The implementation agent should first review the existing bugs and spec before fixing them. The Orchestrator signals this by checking for `BUG_REPORT.md` and `ADVERSARIAL_BUG_REPORT.md` in the new task folder.

## Autopilot Rules

1. **Linear Progression**: Never skip a phase (except Design and Test Design, which are optional).
2. **Artifact Check**: A phase is only considered "complete" if its corresponding artifact exists and is non-empty.
3. **Automatic Transition**: Upon completion of an artifact, the Orchestrator must immediately identify and propose the next phase in the lifecycle.
4. **Human Intervention**: If the Referee marks a task as `FAIL`, `NEEDS_REVIEW`, or identifies "Tie-Breaks", the Autopilot pauses and waits for user input — the Orchestrator does NOT auto-create fix/review/tiebreak tasks in Autopilot mode; the user must decide whether to create fix tasks and how to proceed. (In manual mode, the Orchestrator auto-creates these tasks.)