namastexlabs/wizard

/wizard — First-Run Onboarding

Walk a new user (or their agent) through the complete Genie setup in five phases. Each phase has clear entry/exit criteria so the wizard can be interrupted and resumed.

When to Use

• First time running Genie in a new project
• User explicitly invokes /wizard
• Bootstrap script directed the agent here after install
• No .genie/ directory or AGENTS.md exists in the current repo

Flow

Phase 1: Environment Check

Entry: User invokes /wizard or agent is directed here after install.

Steps:

1. Verify genie CLI is installed and accessible in PATH:

   command -v genie && genie --version
   

2. Check if the current directory is a git repository (git rev-parse --git-dir).
3. Check if .genie/ directory exists (has Genie been scaffolded?).
4. Check if AGENTS.md exists (has identity been shaped?).
5. Check if CLAUDE.md exists (project instructions present?).

Exit criteria: All checks pass, or we know exactly what to set up.

Display status:

Wizard Phase 1/5: Environment Check
  genie CLI    ✅ v4.x.x
  git repo     ✅
  .genie/      ⬜ not found — will scaffold
  AGENTS.md    ⬜ not found — will create
  CLAUDE.md    ✅ found

If genie is not installed, stop and direct the user to install it first:

genie is not installed. Run:
  curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash

If not in a git repo, stop and ask the user to initialize one or navigate to one.

Phase 2: Agent Identity

Entry: Phase 1 complete. Workspace needs scaffolding or identity shaping.

Steps:

1. If .genie/ does not exist, run genie to trigger scaffolding (creates .genie/ directory structure, default configs).
2. Delegate to /brainstorm with this seed context:

We're shaping the agent identity for this project. The goal is to create an AGENTS.md that defines who the agents are in this workspace — their roles, responsibilities, communication style, and domain expertise. Look at the codebase to understand the project, then help define the agent team.

3. Let /brainstorm run its interactive flow. It will:
   • Explore the codebase to understand the project
   • Ask clarifying questions about the team's needs
   • Track WRS (Wish Readiness Score) for the identity definition
   • Crystallize into a design when ready

Exit criteria: /brainstorm completes with a design, or user skips identity shaping.

Skip option: If user wants to skip, create a minimal AGENTS.md:

# Agents

This project uses Automagik Genie for orchestration.
Agent identity will be shaped over time through usage.

Phase 3: First Wish

Entry: Phase 2 complete. Agent identity exists or was skipped.

Steps:

1. Ask the user: "What's the first thing you'd like to build or fix in this project?"
2. If the idea is fuzzy, delegate to /brainstorm to explore it.
3. Once the idea is concrete, delegate to /wish to create a structured wish plan:
   • /wish will create .genie/wishes/<slug>/WISH.md
   • It defines scope, acceptance criteria, and execution groups
4. Run /review on the wish to validate the plan before execution.

Exit criteria: A wish exists with status APPROVED (or SHIP from review).

Display progress:

Wizard Phase 3/5: First Wish
  Idea         ✅ "Add dark mode to the settings page"
  Brainstorm   ✅ design crystallized
  Wish plan    ✅ .genie/wishes/add-dark-mode/WISH.md
  Review       ✅ SHIP — plan approved

Phase 4: Execute

Entry: Phase 3 complete. An approved wish exists.

Steps:

1. Show the user what's about to happen:

   Ready to execute wish: add-dark-mode
   Groups: 3 execution groups, estimated 2 agents
   

2. Run /work on the wish to begin execution:
   • /work will orchestrate subagents per execution group
   • Each group runs its fix/review loop
   • Progress is tracked via genie task system
3. Monitor progress and report status to the user.
4. When /work completes, run /review for final verification.

Exit criteria: All work groups complete and pass review.

Phase 5: Celebrate

Entry: Phase 4 complete. Work is done and reviewed.

Steps:

1. Summarize what was accomplished:

   Your first wish has been granted!
   
   Wish:    add-dark-mode
   Status:  COMPLETE
   Files:   12 files changed, 340 insertions
   Review:  SHIP — all criteria met
   

2. Show next steps:
   • Create a PR: genie can help create a pull request for the changes
   • Run another wish: Use /brainstorm or /wish to plan the next piece of work
   • Set up a team: For larger work, use genie team create for autonomous multi-agent execution
   • Explore skills: Run /genie to see all available skills and the wish lifecycle
3. Close with:

   You're all set! From here, the flow is:
     /brainstorm → /wish → /work → /review → ship
   
   Run /genie anytime to see where you are in the lifecycle.
   

Resumption

If the wizard is interrupted and re-invoked, detect the current state:

• .genie/ exists → skip scaffolding in Phase 2
• AGENTS.md exists → skip identity in Phase 2
• .genie/wishes/ has an approved wish → skip to Phase 4
• .genie/wishes/ has a completed wish → skip to Phase 5

Error Handling

• If any phase fails, show the error clearly and offer to retry or skip.
• If /brainstorm or /wish fails, the wizard can still continue — these are delegated skills.
• If /work fails on a group, show the failure and ask the user how to proceed (retry, skip, or abort).
• Never leave the user stuck — always offer a path forward.