work

name	work
description	Execute an approved wish plan — orchestrate subagents per task group with fix loops, validation, and review handoff.

/work — Execute Wish Plan

The engineer's skill, invoked via genie work <agent> <ref> dispatch. Orchestrate execution of an approved wish from .genie/wishes/<slug>/WISH.md. The orchestrator never executes directly — always dispatch via subagent.

Context Injection

This skill receives its execution context from the dispatch layer:

• Wish path — .genie/wishes/<slug>/WISH.md in the shared worktree
• Group context — which execution group(s) to work on
• Injected section — the specific group definition extracted from the wish

If context is injected, use it directly. Do not re-parse the wish for information already provided.

Flow

1. Load wish: read .genie/wishes/<slug>/WISH.md from the shared worktree, confirm scope.
2. Pick next task: select next unblocked pending execution group (or use injected group context).
3. Task checkout (v4): if a PG task exists for this group, claim it before starting:

   genie task checkout #<seq>
   

4. Self-refine: dispatch /refine on the task prompt (text mode) with WISH.md as context anchor. Read output from /tmp/prompts/<slug>.md. Fallback: proceed with original prompt if refiner fails (non-blocking).
5. Dispatch worker: send the task to a fresh subagent session (see Dispatch).
6. Progress update (v4): log progress as task comments during execution:

   genie task comment #<seq> "Building group N..."
   

7. Local review: run /review against the wish spec for this group's acceptance criteria before signaling done. On FIX-FIRST, dispatch fix subagent (max 2 loops).
8. Quality review: dispatch review subagent for quality pass (security, maintainability, perf). On FIX-FIRST, dispatch fix subagent (max 1 loop).
9. Validate: run the group validation command, record evidence.
10. Group done (v4): move the task to review stage:

    genie task move #<seq> --to review --comment "Group N complete"
    

11. Signal completion: notify the leader via genie agent send 'Group N complete — all criteria met' --to <leader>.
12. Repeat steps 2-11 until all groups done.
13. Wish done (v4): mark the parent task done:

    genie task done #<parent-seq> --comment "All groups shipped"
    

14. Handoff: All work tasks complete. Run /review.

When to Use

• An approved wish exists and is ready for execution
• Orchestrator needs to dispatch implementation tasks to subagents
• After /review returns SHIP on the plan

Dispatch

All dispatch uses the genie agent spawn command. The orchestrator spawns subagents for each role — never executes work directly.

# Spawn an engineer for the task
genie agent spawn engineer

# Spawn a reviewer (always separate from engineer)
genie agent spawn reviewer

# Spawn a fixer for FIX-FIRST gaps
genie agent spawn fixer

Need	Method
Implementation task	genie agent spawn engineer
Review task	genie agent spawn reviewer (never same agent as engineer)
Fix task	genie agent spawn fixer (separate from reviewer)
Quick validation	Bash tool directly — no subagent needed

Coordinate via genie agent send '<message>' --to <agent>. Use genie agent send '<message>' --broadcast for team-wide updates.

Context Curation

When dispatching an engineer for a group, the team-lead MUST extract the relevant context from WISH.md and paste it directly into the dispatch prompt. Do NOT tell the engineer to "read WISH.md" — curate the context for them.

Why: Reading WISH.md wastes engineer context window on metadata, other groups, and scope sections irrelevant to their task. Curated context = better focus, fewer hallucinations about scope, and faster execution.

What to extract and paste into the dispatch prompt:

1. Group goal — one sentence describing what this group achieves
2. Group deliverables — the numbered list of concrete outputs
3. Acceptance criteria — the checkbox list the engineer must satisfy
4. Validation command — the exact command to run to verify the work (e.g., bun run check)
5. Depends-on — any groups that must complete first (for context on what the engineer can assume exists)

Example dispatch prompt structure:

Execute Group N of wish "<slug>".

Goal: <one sentence>

Deliverables:
1. <deliverable 1>
2. <deliverable 2>

Acceptance Criteria:
- [ ] <criterion 1>
- [ ] <criterion 2>

Validation: <command>

Depends-on: <group refs or "none">

Anti-pattern: "Implement Group 2. Read WISH.md for details." — this forces the engineer to parse an entire wish document, navigate to the right section, and risk being distracted by other groups' scope. The team-lead has already read the wish; don't make the engineer re-read it.

State Management

• Workers signal completion via genie agent send to the leader when a group is done.
• Leader tracks wish-group state via genie wish status <slug> and marks groups complete via genie wish done <slug>#<group> (and, when PG tasks exist, genie task done #<seq>).
• Workers do NOT call genie task done — that is the leader's responsibility after verifying the work.
• If a group gets stuck, the leader can use genie wish reset <ref> to retry.

Escalation

When a subagent fails or fix loop limit (2) is exceeded:

• Mark task BLOCKED in wish.
• Create follow-up task with concrete gaps.
• Continue with next unblocked task.
• Include blocked items in final handoff.

Task Lifecycle Integration (v4)

When PG tasks exist for the wish, use genie task commands to track execution:

Event	Command
Start working on group	genie task checkout #<seq>
Progress update	genie task comment #<seq> "<status>"
Group complete	genie task move #<seq> --to review --comment "Group N complete"
All groups done	genie task done #<parent-seq> --comment "All groups shipped"
Group blocked	genie task block #<seq> --reason "<reason>"

Graceful degradation: If no PG task exists for the wish (e.g., PG unavailable or wish was created before v4), skip all genie task commands and fall back to current behavior. Task integration is optional — the core flow must never break due to missing tasks.

Example: Full Dispatch Cycle

Wish fix-dispatch-initial-prompt has 1 execution group. The orchestrator runs /work:

# 1. Dispatch wave (spawns engineers automatically)
genie work fix-dispatch-initial-prompt
# Output: 🚀 Dispatching Wave 1 — 1 group(s)
#         ✅ Group "1" set to in_progress
#         🔧 Dispatching work to engineer for "fix-dispatch-initial-prompt#1"

# 2. Monitor (ALWAYS sleep 60 between checks)
sleep 60 && genie wish status fix-dispatch-initial-prompt
# Output: Group 1: 🔄 in_progress

# 3. Check again
sleep 60 && genie wish status fix-dispatch-initial-prompt
# Output: Group 1: ✅ done — Progress: 1/1 done

# 4. All groups done → local review
genie agent spawn reviewer
genie agent send 'Review wish fix-dispatch-initial-prompt. Run bun test and check all 5 call sites.' --to reviewer
# Reviewer returns: SHIP

# 5. Create PR
git add -A && git commit -m "fix: pass initialPrompt to handleWorkerSpawn in all dispatch commands"
git push origin HEAD
gh pr create --base dev --title "fix: pass initialPrompt to dispatch" --body "Fixes #745. Wish: fix-dispatch-initial-prompt"

For multi-wave wishes, call genie work <slug> again after each wave completes — it dispatches the next wave automatically.

Rules

• Never execute directly — always dispatch subagents.
• Never expand scope during execution.
• Never skip validation commands.
• Never overwrite WISH.md from workers — refined prompts are runtime context only.
• Keep work auditable: capture commands + outcomes.
• Run local /review per group before signaling done — never skip the review gate.

Turn close (required)

Every session MUST end by writing a terminal outcome to the turn-session contract. This is how the orchestrator reconciles executor state — skipping it leaves the row open and blocks auto-resume.

• genie done — work completed, acceptance criteria met
• genie blocked --reason "<why>" — stuck, needs human input or an unblocking signal
• genie failed --reason "<why>" — aborted, irrecoverable error, or cannot proceed

Rules:

• Call exactly one close verb as the last action of the session.
• blocked / failed require --reason.
• genie done inside an agent session (GENIE_AGENT_NAME set) closes the current executor; it does not require a wish ref.