> ## 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

> The structured plan that drives everything — from brainstorm to pull request.

# 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:

```text theme={"dark"}
brainstorm → wish → work → review → ship
```

| Stage    | Skill         | Input              | Output                             |
| -------- | ------------- | ------------------ | ---------------------------------- |
| Explore  | `/brainstorm` | Rough idea         | Design document with decisions     |
| Plan     | `/wish`       | Design document    | `WISH.md` with criteria and groups |
| Execute  | `/work`       | Approved `WISH.md` | Code changes, tests, docs          |
| Validate | `/review`     | Completed work     | SHIP, FIX-FIRST, or BLOCKED        |
| Ship     | automatic     | SHIP verdict       | Pull request                       |

## Anatomy of a WISH.md

Every wish contains these sections:

### Header

```markdown theme={"dark"}
# Wish: Add Dark Mode Toggle

| Field | Value |
|-------|-------|
| **Status** | APPROVED |
| **Slug** | `dark-mode-toggle` |
| **Date** | 2026-03-24 |
```

The **status** tracks the wish lifecycle:

| Status        | Meaning                         |
| ------------- | ------------------------------- |
| `DRAFT`       | Being written, not yet approved |
| `APPROVED`    | Ready for execution             |
| `IN_PROGRESS` | Currently being worked on       |
| `REVIEW`      | Work complete, under review     |
| `DONE`        | Shipped and merged              |
| `BLOCKED`     | Cannot proceed — needs input    |

### Scope

Defines clear boundaries — what's **in** and what's **out**:

```markdown theme={"dark"}
## 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:

```markdown theme={"dark"}
## 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:

```markdown theme={"dark"}
## 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.

<Warning>
  **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.
</Warning>

**The error you'll see:**

```text theme={"dark"}
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:**

<Steps>
  <Step title="Confirm the edit was intentional">
    If the WISH.md change was accidental, revert it — the error will clear on the next dispatch.
  </Step>

  <Step title="Reset the wish state">
    If the edit was intentional, wipe the cached state and recreate it from the current `WISH.md`:

    ```bash theme={"dark"}
    genie reset <slug>
    ```

    In non-interactive contexts (CI, agent shells), add `--yes` to skip the confirmation prompt. See [`genie reset`](/genie/cli/dispatch#genie-reset) for the full flag list.
  </Step>

  <Step title="Re-dispatch">
    Any previously in-progress groups are lost with the reset — re-run `/work` (or re-dispatch manually) against the refreshed plan.
  </Step>
</Steps>

<Note>
  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.
</Note>

## File Locations

| Location        | Path                                  | Purpose              |
| --------------- | ------------------------------------- | -------------------- |
| Wish document   | `.genie/wishes/<slug>/WISH.md`        | The plan             |
| Design document | `.genie/brainstorms/<slug>/DESIGN.md` | Pre-wish exploration |
| Execution state | PostgreSQL `tasks` table              | Progress tracking    |

## CLI Commands

Wishes become tasks in the database — see the [Task CLI reference](/genie/cli/tasks) for full task management commands.

```bash theme={"dark"}
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

<AccordionGroup>
  <Accordion title="Keep wishes small">
    A wish should be completable in one session. If it has more than 6 execution groups, consider splitting into multiple wishes.
  </Accordion>

  <Accordion title="Write testable criteria">
    Each success criterion should be verifiable by a command or assertion. Avoid subjective criteria like "code is clean."
  </Accordion>

  <Accordion title="Declare dependencies explicitly">
    If Group 3 needs Group 1's output, say `depends-on: Group 1`. Genie uses this to schedule execution order.
  </Accordion>

  <Accordion title="Scope aggressively">
    The OUT section is as important as IN. Explicitly listing what you won't do prevents scope creep.
  </Accordion>
</AccordionGroup>