watchfire definition

Edit the project definition in your default editor.

Usage

watchfire define
watchfire def                  # alias
watchfire definition retrofit  # fold completed tasks back into the definition
watchfire defn retrofit        # alias

Description

watchfire define opens the project definition in $EDITOR for editing. The project definition describes your project — its structure, tech stack, goals, and conventions — and is injected into every agent session to provide context, regardless of which backend is running (Claude Code, Codex, opencode, Gemini, or Copilot).

A well-written definition helps agents produce better, more consistent code by giving them the information they need about your project upfront.

Subcommands

definition retrofit

Fold completed tasks back into the definition (Torch, v10.0.0). Tasks are temporary; the definition is durable — after a run of shipped tasks, the definition no longer describes what the project has become. Retrofit runs the retrofit-definition agent mode: the agent reads every task completed since the last retrofit and updates the definition to match reality.

watchfire definition retrofit
watchfire definition retrofit --archive        # offer to archive the folded tasks
watchfire definition retrofit --archive --yes  # skip the confirm

Flag	Description
--archive	After the retrofit, archive (soft-delete) exactly the folded tasks
--yes	Skip the archive confirmation
--sandbox / --no-sandbox	Override the project's sandbox setting for this run

A last_retrofit_task_number watermark on project.yaml tracks how far the definition has been folded, so each retrofit only considers tasks completed since the previous one. Archiving is always confirm-gated (unless --yes) and touches exactly the folded window; archived tasks are flagged retrofit_archived and still count in Insights.

The same action is available in the GUI (Definition tab → "Retrofit from completed tasks") and the TUI (r on the Definition tab).

What the Definition Contains

The definition is stored in the definition field of .watchfire/project.yaml. A typical definition includes:

• Project name and purpose
• Technical stack and frameworks
• Architecture overview
• Coding conventions and constraints
• Goals or current priorities

Notes

• Uses the editor set in your $EDITOR environment variable
• Changes are saved directly to project.yaml
• The definition is included in agent context for all modes (chat, task, wildfire)
• To auto-generate a definition from your codebase, use watchfire generate

Examples

Bootstrap a definition for a new project

watchfire generate
watchfire define

watchfire generate drafts a definition from the codebase; watchfire define opens it in $EDITOR so you can tighten it before any tasks are generated. The edited version is what every agent session reads.

Edit the existing definition

watchfire def

The alias is identical to watchfire define. A typical edit narrows scope — add explicit non-goals, name the directories that are off-limits, list the test commands the agent should run.

Definition shape that produces useful tasks

definition: |
  Express API serving an internal admin tool. Goal of this
  cleanup pass: every route handler has a unit test, README
  documents local dev, eslint runs clean.

  Constraints:
  - No new runtime dependencies
  - Public API surface stays unchanged
  - Tests live next to source as *.test.ts

Concrete targets and explicit constraints are what keep watchfire generate and the Wildfire refine phase from drifting.

Common pitfalls

• $EDITOR not set — watchfire define errors out or falls back to a surprising editor. Fix: export EDITOR (e.g. export EDITOR=vim) in your shell profile before running.
• Empty or generic definition — Wildfire and watchfire generate produce vague tasks because they have nothing concrete to anchor on. Fix: see Generate phase produces empty or low-quality tasks.
• Definition not committed — .watchfire/ is gitignored by default, so the definition lives only on the machine that wrote it. Fix: if you want the definition shared, copy the relevant context into the project's README or check in a separate definition.md your team agrees on.