agent-framework/prompts/workflow.md

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 (non-empty)	Decomposition (optional) or Design (optional) or Implement	Generate DECOMPOSITION.md or DESIGN.md or code
Decomposition	Has SPEC.md and DECOMPOSITION.md (both non-empty)	Sub-task Research	Orchestrator creates sub-task folders
Design	Has DESIGN.md (non-empty)	Test Design (optional) or Implement	Generate TEST_PLAN.md or code
Test Design	Has TEST_PLAN.md (non-empty)	Implement	Generate code and tests
Implementation	Has IMPLEMENTATION.md (non-empty)	Bug Find	Generate BUG_REPORT.md
Bug Find	Has BUG_REPORT.md (non-empty)	Adversarial Bug Find	Generate ADVERSARIAL_BUG_REPORT.md
Adversarial Bug Find	Has ADVERSARIAL_BUG_REPORT.md (non-empty)	Doc Review	Generate DOC_REVIEW.md
Doc Review	Has DOC_REVIEW.md (non-empty)	Referee	Generate VERDICT.md
Referee	Has VERDICT.md (non-empty)	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

4. From sub-task FAIL verdict: For each sub-task that FAILs or NEEDS_REVIEW, create a new task:

   • Task name: {parent-task-name}-fix-{sub-task-name} (e.g., add-user-auth-fix-auth-gateway)
   • The Orchestrator creates the folder with an empty IMPLEMENTATION.md
   • The task starts at the Bug Find phase
   • The Orchestrator copies the sub-task's SPEC.md, BUG_REPORT.md, and ADVERSARIAL_BUG_REPORT.md (if they exist) into the new task folder

5. From sub-task "Tasks for Review / Tie-Breaks": For each sub-task that has tie-breaks, create a new task:

   • Task name: {parent-task-name}-tiebreak-{sub-task-name} (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 Orchestrator copies the sub-task's SPEC.md, BUG_REPORT.md, and ADVERSARIAL_BUG_REPORT.md (if they exist) 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.)