Projects and Tasks

Watchfire uses YAML files to define projects and tasks. This file-based approach makes it easy to version control your task definitions and inspect state at any time.

Project Configuration

Each project has a project.yaml file in .watchfire/:

project_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: my-project
default_agent: codex
sandbox: auto
auto_merge: true
auto_delete_branch: true
auto_start_tasks: true
definition: |
  This project is a web application that...
next_task_number: 5

Project Settings

Setting	Default	Description
default_agent	(optional)	Project-level default agent backend for new sessions
sandbox	auto	Sandbox mechanism (auto-detects platform backend)
auto_merge	true	Merge worktree on task completion
auto_delete_branch	true	Delete branch after successful merge
auto_start_tasks	true	Start agent when task set to ready
definition	(empty)	Project context for the AI agent

Agent Selection

default_agent is a first-class project setting. Set it when you want a project to prefer one backend by default, such as codex, claude-code, opencode, gemini, or copilot.

The field is optional. When Watchfire needs to decide which backend to run for a task or session, it resolves the effective agent in this order:

1. task.agent
2. project.default_agent
3. Global default agent from Watchfire settings
4. claude-code

This means you only need to set default_agent when the project should override the global default. If both the task and project omit an agent, Watchfire still falls back automatically.

Project Definition

The definition field provides context for AI agents working on your project. It should describe:

• What the project does
• Tech stack and conventions
• Key architectural decisions
• File structure overview

Agents read this definition to understand the codebase before working on tasks.

Directory Structure

Each project's .watchfire/ directory contains:

.watchfire/
├── project.yaml            # Project configuration
├── tasks/                  # Task YAML files
├── memory.md               # Persistent project knowledge across agent sessions
├── secrets/                # Secrets and setup instructions
│   └── instructions.md
└── worktrees/              # Git worktrees (one per active task)
    └── <task_number>/

Agent Memory

Watchfire provides a memory.md file in .watchfire/ that agents can read and update to persist project-specific knowledge across sessions. Agents use this to store conventions, user preferences, recurring patterns, and workflow notes so that future sessions don't start from scratch. The file is automatically available to agents working in any task for the project.

Task Schema

Tasks are stored as individual YAML files in .watchfire/tasks/:

task_id: a1b2c3d4
task_number: 1
title: "Setup project structure"
agent: codex
prompt: |
  Create the initial project structure with a Next.js app,
  Tailwind CSS, and TypeScript configuration.
acceptance_criteria: |
  - Next.js app boots successfully
  - Tailwind CSS is configured
  - TypeScript strict mode enabled
status: draft
success: null
failure_reason: ""
position: 1
agent_sessions: 0
created_at: "2026-01-15T10:30:00Z"
updated_at: "2026-01-15T10:30:00Z"

Task Fields

Field	Type	Description
task_id	string	8-character alphanumeric identifier
task_number	int	Sequential number, used for file naming
title	string	Short description of the task
agent	string (optional)	Override backend for this task only
prompt	string	Detailed instructions for the agent
acceptance_criteria	string	How to verify the task is complete
status	enum	draft, ready, or done
success	bool/null	null (pending), true, or false
failure_reason	string	Explanation if success: false
position	int	Order within the task list

Task Agent Override

Use agent on a task when one task should run on a different backend than the rest of the project.

title: "Refactor docs search"
agent: gemini
status: ready

If agent is omitted, the task inherits from the same fallback chain described above:

1. project.default_agent
2. Global default agent
3. claude-code

Task Lifecycle

Tasks flow through three statuses:

Draft

A task in draft status is being written or refined. It is not ready for an agent to work on. In Wildfire mode, the Refine phase picks up draft tasks and improves their prompts and acceptance criteria.

Ready

A task in ready status is queued for execution. If auto_start_tasks is enabled, setting a task to ready will automatically start an agent. When multiple tasks are ready, the agent picks the next one by:

1. Sort by position (ascending)
2. If equal, sort by task_number (ascending)
3. Pick first

Done

A task in done status has been completed (or failed). Check the success field:

• success: true — Task completed successfully
• success: false — Task failed or was blocked. Check failure_reason for details.

Multi-Project Management

The daemon manages multiple projects simultaneously:

Aspect	Behavior
Projects index	~/.watchfire/projects.yaml lists all registered projects
Registration	Projects added via watchfire init or the GUI
Concurrency	One active task per project, multiple projects in parallel