namastexlabs/work

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