Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
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 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: 
Wish "dark-mode-toggle" group structure has changed since state was created.
  + added: Group 3
  - removed: Group 2
  ~ changed deps: Group 1

Run `genie reset dark-mode-toggle` to recreate state from the current WISH.md.
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:
genie reset <slug>
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

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.