watchfire definition

Edit the project definition in your default editor.

Usage

watchfire define
watchfire def        # 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.

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.