Skip to main content

​
Wishes

A wish is Genie’s unit of work. It’s a structured document (WISH.md) that defines what to build, how to validate it, and how to break it into parallelizable execution groups.

​
The Workflow

Every wish flows through a five-stage workflow:

​
Anatomy of a WISH.md

Every wish contains these sections:
The status tracks the wish lifecycle:

​
Scope

Defines clear boundaries — what’s in and what’s out:

​
Success Criteria

Checkboxes that define “done”. These are what /review validates against:

​
Execution Groups

Parallelizable work units. Each group is assigned to an agent:
Groups with depends-on run sequentially. Independent groups run in parallel — this is how Genie achieves speed.

​
Wish State

Genie tracks execution state in PostgreSQL via the task system. A wish becomes a parent task, and each execution group becomes a child task with dependency edges. The task system records:
  • Which groups are complete
  • Which agents are assigned
  • Current workflow stage
  • Timestamps and error states
State is stored in the tasks and task_dependencies tables — no file locks needed, and concurrency is handled natively by PostgreSQL.

​
Drift Detection

When state is first created, Genie stashes a SHA-256 signature of the wish’s group structure (group names + sorted depends-on per group) on the parent task. Any later dispatch recomputes that signature from the current WISH.md and compares. If they diverge, Genie fails loud instead of silently dispatching against a stale plan.
What triggers it: editing WISH.md to add a group, remove a group, or change a group’s depends-on after the wish has already been initialized in the database. Prose edits (summary, decisions, context) leave the signature untouched.
The error you’ll see:
Each diff line appears only when non-empty — you may see just additions, just removals, or just dependency changes. Recovery:
1

Confirm the edit was intentional

If the WISH.md change was accidental, revert it — the error will clear on the next dispatch.
2

Reset the wish state

If the edit was intentional, wipe the cached state and recreate it from the current WISH.md:
In non-interactive contexts (CI, agent shells), add --yes to skip the confirmation prompt. See genie reset for the full flag list.
3

Re-dispatch

Any previously in-progress groups are lost with the reset — re-run /work (or re-dispatch manually) against the refreshed plan.
Pre-existing state from before this feature landed has no stored signature and is treated as “valid, never validated” — it won’t false-alarm on the next dispatch, but the first genie reset <slug> will enrol it into drift tracking.

​
File Locations

​
CLI Commands

Wishes become tasks in the database — see the Task CLI reference for full task management commands.

​
Best Practices

A wish should be completable in one session. If it has more than 6 execution groups, consider splitting into multiple wishes.
Each success criterion should be verifiable by a command or assertion. Avoid subjective criteria like “code is clean.”
If Group 3 needs Group 1’s output, say depends-on: Group 1. Genie uses this to schedule execution order.
The OUT section is as important as IN. Explicitly listing what you won’t do prevents scope creep.