watchfire generate

Generate a project definition using a coding agent.

Alias: watchfire gen

Usage

watchfire generate

Description

watchfire generate spawns an agent session that analyzes your codebase and generates a project definition for project.yaml. This is useful when starting with an existing codebase and you want the agent to understand and document the project structure, conventions, and architecture.

The generated definition is saved to your project.yaml and serves as context for all future agent sessions.

Flags

Flag	Description
--sandbox <backend>	Override the sandbox backend. Valid values: auto, seatbelt, landlock, bubblewrap, none.
--no-sandbox	Shorthand for --sandbox none — disables sandboxing entirely.

Sandbox priority: CLI flag → project setting (project.yaml) → global default (settings.yaml).

These flags also apply to watchfire plan.

Agent Selection

Both watchfire generate and watchfire plan run on the project's default agent, falling back to the global default and finally to claude-code. Any of the supported backends (Claude Code, Codex, opencode, Gemini, Copilot) can perform definition and task generation. See Supported Agents.

Related: watchfire plan

To generate tasks from an existing project definition, use:

watchfire plan

This spawns an agent session that reads your project definition and creates a set of tasks in .watchfire/tasks/. It's useful for breaking down a project into actionable work items.

Examples

Generate a definition for a fresh project

watchfire init
watchfire generate
watchfire define

After init, generate walks the codebase and drafts a definition field in project.yaml. Always follow with watchfire define to tighten the draft — the edited version is what every future session reads.

Re-generate tasks after the definition changes

watchfire plan

plan reads the current project.definition and writes new task YAML files to .watchfire/tasks/. Run it after a meaningful definition edit so the task list reflects the new scope.

Skip the sandbox when bootstrapping

watchfire generate --no-sandbox

Useful on a brand-new machine where the sandbox configuration hasn't been verified yet — keep this flag scoped to the bootstrap step and re-enable the sandbox for normal task runs.

Common pitfalls

• Empty definition produces empty tasks — watchfire plan finishes but the new tasks are vague. Fix: tighten project.definition first — see Generate phase produces empty or low-quality tasks.
• Existing definition silently overwritten — watchfire generate rewrites project.definition from scratch. Fix: if you have a hand-authored definition you care about, edit it with watchfire define instead, or copy it elsewhere before re-running generate.
• Drafts pile up in .watchfire/tasks/ — watchfire plan adds new draft tasks but does not remove old ones. Fix: delete or refine stale drafts with watchfire task delete or let the Wildfire refine phase consolidate them.