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 Pipeline

Every wish flows through a five-stage pipeline: 
brainstorm → wish → work → review → ship
StageSkillInputOutput
Explore/brainstormRough ideaDesign document with decisions
Plan/wishDesign documentWISH.md with criteria and groups
Execute/workApproved WISH.mdCode changes, tests, docs
Validate/reviewCompleted workSHIP, FIX-FIRST, or BLOCKED
ShipautomaticSHIP verdictPull request

​
Anatomy of a WISH.md

Every wish contains these sections: 
# Wish: Add Dark Mode Toggle

| Field | Value |
|-------|-------|
| **Status** | APPROVED |
| **Slug** | `dark-mode-toggle` |
| **Date** | 2026-03-24 |
The status tracks the wish lifecycle:
StatusMeaning
DRAFTBeing written, not yet approved
APPROVEDReady for execution
IN_PROGRESSCurrently being worked on
REVIEWWork complete, under review
DONEShipped and merged
BLOCKEDCannot proceed — needs input

​
Scope

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

### IN
- Dark mode CSS variables
- Toggle component in settings
- Persistent preference in localStorage

### OUT
- System theme detection (future wish)
- Dark mode for marketing pages

​
Success Criteria

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

- [ ] Toggle renders in settings page
- [ ] CSS variables switch between light/dark
- [ ] Preference persists across sessions
- [ ] No FOUC on page load
- [ ] All existing tests pass

​
Execution Groups

Parallelizable work units. Each group is assigned to an agent: 
## Execution Groups

### Group 1: CSS Variables
**Agent:** engineer
**Deliverables:**
1. Define CSS custom properties for both themes
2. Update existing component styles to use variables

### Group 2: Toggle Component
**Agent:** engineer
**Deliverables:**
1. Build toggle component
2. Wire to localStorage
**depends-on:** Group 1
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 pipeline 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.

​
File Locations

LocationPathPurpose
Wish document.genie/wishes/<slug>/WISH.mdThe plan
Design document.genie/brainstorms/<slug>/DESIGN.mdPre-wish exploration
Execution statePostgreSQL tasks tableProgress tracking

​
CLI Commands

Wishes become tasks in the database — see the Task CLI reference for full task management commands. 
genie status <slug>          # Show wish progress
genie wish approve <slug>    # Approve a draft wish
genie wish reset <slug>      # Reset wish state
genie done <slug> <group>    # Mark a group complete

​
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.