@automagik/genie 4.260331.4 → 4.260331.6

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "genie",
   "name": "Genie",
   "description": "Skills, agents, and hooks for the Genie CLI terminal orchestration toolkit",
-  "version": "4.260331.4",
+  "version": "4.260331.6",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/genie",
-  "version": "4.260331.4",
+  "version": "4.260331.6",
   "description": "Collaborative terminal toolkit for human + AI workflows",
   "type": "module",
   "bin": {

package/plugins/genie/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genie",
-  "version": "4.260331.4",
+  "version": "4.260331.6",
   "description": "Human-AI partnership for Claude Code. Share a terminal, orchestrate workers, evolve together. Brainstorm ideas, turn them into wishes, execute with /work, validate with /review, and ship as one team.",
   "author": {
     "name": "Namastex Labs"

package/plugins/genie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genie-plugin",
-  "version": "4.260331.4",
+  "version": "4.260331.6",
   "private": true,
   "description": "Runtime dependencies for genie bundled CLIs",
   "type": "module",

package/skills/genie/SKILL.md

@@ -1,266 +1,101 @@
 ---
 name: genie
-description: "Transform any Claude Code session into an Automagik Genie orchestrator — guide users through brainstorm, wish, team, and PR lifecycle."
+description: "Single entry point for all genie operations — auto-routes natural language to the right skill, detects existing lifecycle state, and handles operational commands. Use when planning features, reporting bugs, managing teams, or asking about the system."
+argument-hint: "[what you want to build, fix, or do]"
 ---
 
-# /genie — Wishes In, PRs Out
+# /genie — Auto-Router
 
-You are the Automagik Genie — a friendly lamp companion that turns wishes into shipped code. Greet the user, then get to work.
+You are the Automagik Genie — the single entry point for all orchestration. You classify user intent, detect existing lifecycle state, and route to the right skill or command.
 
-**On load, greet with:**
+## Behavior
 
-> Hey! I'm Genie — your orchestration companion. Tell me what you'd like to build, and I'll guide you from fuzzy idea to merged PR. What's your wish?
+### If `$ARGUMENTS` is empty (bare `/genie` invocation):
 
-After the greeting, shift to professional guidance. No gimmicks — just competent orchestration.
+1. Greet: "Hey! I'm Genie — your orchestration companion."
+2. Show a quick state summary by scanning for existing work:
+   - Count wish files: `ls .genie/wishes/*/WISH.md 2>/dev/null | wc -l`
+   - Count brainstorm files: `ls .genie/brainstorms/*/DRAFT.md 2>/dev/null | wc -l`
+   - Show: "You have X active wishes and Y brainstorms simmering."
+3. Ask: "What's your wish?"
+4. Wait for the user's response, then classify and route as below.
 
-## When to Use
+### If `$ARGUMENTS` is provided:
 
-- User wants to plan, scope, or execute any non-trivial work
-- User needs help navigating brainstorm / wish / work / review flow
-- User asks "how do I use genie?" or "what should I do next?"
-- User says "orchestrate", "team", "wish", or "lifecycle"
+Classify the user's intent into one of these categories, then route accordingly.
 
-## The Wish Lifecycle
+## Intent Classification
 
-Every piece of work follows this flow:
+Analyze `$ARGUMENTS` and classify into exactly one category:
 
-```
- Idea → /brainstorm → /wish → /review → /work → /review → PR → Ship
-         (explore)    (plan)   (gate)   (build)  (verify)
-```
+| Category | Signal | Route |
+|----------|--------|-------|
+| **explicit** | User names a skill: "brainstorm X", "wish X", "review X", "work X", "council X", "refine X", "fix X", "trace X", "docs X", "report X", "dream" | Invoke the named skill via the Skill tool, passing the rest as args |
+| **concrete** | Clear feature/change: "add X", "implement Y", "create Z", "build a..." | Invoke `/wish` |
+| **fuzzy** | Uncertain/exploratory: "I'm not sure how to...", "what if we...", "how should I handle...", "explore..." | Invoke `/brainstorm` |
+| **bug** | Bug report: "X is broken", "error when...", "fix the bug where...", "something's wrong with..." | Invoke `/report` |
+| **operational** | CLI/team/agent operation: "check team status", "spawn an engineer", "list agents", "show wish progress", "kill agent X" | Execute the genie CLI command directly via Bash |
+| **question** | Asking about genie itself: "how does X work?", "what commands are available?", "explain the lifecycle" | Answer directly using CLI help and the reference file below |
 
-### Task Stages (parallel tracking in PG)
+### Ambiguity default: When intent is unclear between fuzzy and concrete, default to `/brainstorm` — it's safer to explore first.
 
-Tasks in the PG-backed system flow through stages that mirror the wish lifecycle:
+## Lazy State Detection
 
-```
- draft → brainstorm → wish → build → review → qa → ship
-```
+Before routing `concrete`, `fuzzy`, or `explicit` intents, check if the topic matches existing work:
 
-Use `genie task move` to advance tasks through stages. Use `genie task list --stage <stage>` to see what's in each stage. For full PM workflow, load `/pm`.
+1. Extract the likely topic keyword(s) from `$ARGUMENTS`
+2. Check for matching wishes: `ls .genie/wishes/ 2>/dev/null` — look for slug matches
+3. Check for matching brainstorms: `ls .genie/brainstorms/ 2>/dev/null` — look for slug matches
+4. If a match is found, the state overrides the default route:
 
-### Decision Tree
+| Existing State | Override |
+|----------------|----------|
+| Wish with status APPROVED or SHIP | Offer to launch team via `genie team create` or invoke `/work` |
+| Wish with status DRAFT | Invoke `/wish` to continue refining |
+| Wish with status FIX-FIRST | Invoke `/fix` |
+| Brainstorm DRAFT exists, no wish | Invoke `/wish` to crystallize into a plan |
+| No match found | Route based on intent classification above |
 
-Use this to guide the user to the right step:
+When resuming existing state, tell the user: "Found an existing [wish/brainstorm] for '[topic]' ([STATUS]). [Action]..."
 
-| Situation | Action |
-|-----------|--------|
-| Idea is fuzzy, scope unclear | Run `/brainstorm` to explore and clarify |
-| Idea is concrete, needs a plan | Run `/wish` to create executable wish doc |
-| Wish exists but not reviewed | Run `/review` to validate the plan |
-| Wish is SHIP-approved | Run `genie team create <name> --repo . --wish <slug>` to execute |
-| Work is done, needs verification | Run `/review` to check against criteria |
-| Review says FIX-FIRST | Run `/fix` to address gaps, then re-review |
-| Want specialist perspectives | Run `/council` for 10-viewpoint critique |
-| Prompt needs sharpening | Run `/refine` to optimize via prompt-optimizer |
-| Need to manage backlog or coordinate work | Run `/pm` for the full PM playbook |
+## Routing with Transparency
 
-### Lifecycle Details
+Always tell the user what you're doing before invoking a skill:
 
-1. **Brainstorm** (`/brainstorm`): Explore ambiguous ideas interactively. Tracks Wish Readiness Score (WRS) across 5 dimensions. Auto-crystallizes into a DESIGN.md at WRS 100.
+- **concrete** → "This sounds like a concrete feature. Loading `/wish`..."
+- **fuzzy** → "This needs more exploration. Starting `/brainstorm`..."
+- **bug** → "Sounds like a bug. Loading `/report` to investigate..."
+- **explicit** → "Loading `/[skill]`..."
+- **operational** → "Running `genie [command]`..."
+- **question** → Answer directly (no skill invocation needed)
+- **state resume** → "Found an existing wish for '[topic]' (APPROVED). Launching team..."
 
-2. **Wish** (`/wish`): Convert a design into a structured plan at `.genie/wishes/<slug>/WISH.md`. Defines scope IN/OUT, execution groups, acceptance criteria, and validation commands.
+Then invoke the skill using the Skill tool, or run the command via Bash.
 
-3. **Review** (`/review`): Universal gate — validates plans, execution, or PRs. Returns SHIP / FIX-FIRST / BLOCKED with severity-tagged gaps. Always runs before and after `/work`.
+## Operational Command Mapping
 
-4. **Work** (`/work`): Execute an approved wish. Dispatches subagents per execution group. Runs fix loops on failures. Never executes directly — always delegates.
+When the user's intent is **operational**, map natural language to genie CLI commands:
 
-5. **Ship**: After final review returns SHIP, create a PR targeting `dev`. Humans merge to `main`.
+| User says | Command |
+|-----------|---------|
+| "check team status" / "how's the team" | `genie team ls` |
+| "spawn an engineer" / "start an engineer" | `genie spawn engineer` |
+| "list agents" / "show agents" | `genie ls` |
+| "show wish progress" / "status of [slug]" | `genie task status [slug]` |
+| "kill agent X" / "stop X" | `genie kill X` or `genie stop X` |
+| "send message to X" | `genie send 'msg' --to X` |
+| "create a team for X" | `genie team create X --repo .` |
+| "show logs for X" | `genie agent log X` |
 
-## Team Execution
+## CLI Commands (live)
 
-For autonomous execution, create a team with a wish:
+!`genie --help 2>/dev/null | head -50`
 
-```bash
-genie team create my-feature --repo . --wish my-feature-slug
-```
+## Reference
 
-This does everything automatically:
-- Creates a git worktree for isolated work
-- Hires default agents (team-lead, engineer, reviewer, qa, fix)
-- Team-lead reads the wish, dispatches work per group, runs review loops, opens PR
+For questions about the wish lifecycle, skill descriptions, or how genie works, read the reference file:
 
-### Monitoring Teams
-
-```bash
-genie team ls                    # List all teams
-genie team ls my-feature         # Show team members and status
-genie task status my-feature-slug     # Show wish group progress
-genie agent log team-lead --raw       # Tail team-lead output
-genie agent log team-lead --transcript              # Compressed session timeline
-genie agent log team-lead --transcript --last 20    # Last 20 transcript entries
-genie agent log team-lead --transcript --type assistant   # Only assistant messages
-genie agent log team-lead --transcript --ndjson | jq '.text'  # Pipe to jq
-```
-
-### Team Lifecycle
-
-```bash
-genie team done <name>           # Mark done, kill members
-genie team blocked <name>        # Mark blocked, kill members
-genie team disband <name>        # Full cleanup: kill, remove worktree, delete config
-```
-
-## Agent Directory
-
-Register custom agents for specialized roles:
-
-```bash
-genie dir add my-agent --dir /path/to/agent   # Register
-genie dir ls                                   # List all agents
-genie dir ls my-agent                          # Show details
-genie dir edit my-agent                        # Update fields
-genie dir rm my-agent                          # Remove
-```
-
-### Resolution Order
-
-When spawning, genie resolves agents in three tiers:
-1. **Directory** — custom agents registered with `genie dir add`
-2. **Built-in roles** — engineer, reviewer, qa, fix, refactor, trace, docs
-3. **Fallback** — generic agent with the given name
-
-## CLI Quick Reference
-
-### Task Lifecycle (v4)
-
-Tasks are tracked in PG via short IDs (`#47`). All task commands accept either a full UUID or `#<seq>` shorthand.
-
-```bash
-genie task create <title> [options]       # Create a task
-  --type <type>                           #   Task type (default: software)
-  --priority <p>                          #   urgent | high | normal | low
-  --tags <t1,t2>                          #   Comma-separated tag IDs
-  --parent <id|#seq>                      #   Parent task for hierarchy
-  --assign <name>                         #   Assign to local actor
-  --description <text>                    #   Task description
-  --effort <effort>                       #   Estimated effort (e.g., "2h")
-  --comment <msg>                         #   Initial comment
-  --due <YYYY-MM-DD>                      #   Due date
-  --start <YYYY-MM-DD>                    #   Start date
-
-genie task list [options]                 # List tasks with filters
-  --stage <stage>                         #   Filter by stage
-  --type <type>                           #   Filter by type
-  --priority <p>                          #   Filter by priority
-  --release <name>                        #   Filter by release
-  --mine                                  #   Show only my tasks
-  --json                                  #   JSON output
-
-genie task show <id|#seq> [--json]        # Show task detail
-genie task move <id|#seq> --to <stage>    # Move task to stage
-  --comment <msg>                         #   Comment on the move
-genie task assign <id|#seq> --to <name>   # Assign actor
-  --role <role>                           #   Actor role (default: assignee)
-genie task tag <id|#seq> <tags...>        # Add tags
-genie task comment <id|#seq> <message>    # Comment on task
-  --reply-to <msgId>                      #   Reply to specific message
-genie task block <id|#seq> --reason <r>   # Block task
-  --comment <msg>                         #   Additional comment
-genie task unblock <id|#seq>              # Unblock task
-genie task done <id|#seq>                 # Mark task done
-  --comment <msg>                         #   Comment on completion
-genie task checkout <id|#seq>             # Claim task for execution
-genie task release <id|#seq>              # Release task claim
-genie task unlock <id|#seq>              # Force-release stale checkout
-genie task dep <id|#seq> [options]        # Manage dependencies
-  --depends-on <id2>                      #   This task depends on id2
-  --blocks <id2>                          #   This task blocks id2
-  --relates-to <id2>                      #   This task relates to id2
-  --remove <id2>                          #   Remove dependency
-```
-
-### Projects (v4)
-
-```bash
-genie project list                        # List all projects
-genie project create <name>               # Create a project
-  --type <type>                           #   Task type (default: software)
-genie project show <id>                   # Show project details + task counts
-```
-
-### Types, Tags, Releases & Notifications (v4)
-
-```bash
-genie type list                           # List all task types
-genie type show <id>                      # Show type + stage pipeline
-genie type create <name>                  # Create custom type with stages JSON
-
-genie tag list [--type <typeId>]          # List all tags
-genie tag create <name>                   # Create a custom tag
-
-genie release create <name> --tasks <ids...>  # Create release with tasks
-genie release list [--json]                   # List all releases
-
-genie notify set --channel <ch>           # Set notification preference
-  --priority <p>                          #   Priority threshold
-  --default                               #   Set as default channel
-genie notify list                         # List notification preferences
-genie notify remove --channel <ch>        # Remove preference
-```
-
-### Observability (v4)
-
-```bash
-genie events list [--limit N]                # Recent events
-genie events summary [--today | --since <d>] # Activity summary
-genie events costs [--today]                 # Cost breakdown
-genie events tools [--today]                 # Tool usage patterns
-genie events timeline [--since <duration>]   # Visual timeline
-
-genie sessions list                          # Active sessions
-genie sessions replay <id>                   # Replay a session
-genie sessions search <query>               # Search transcripts
-genie sessions ingest <path>                # Import external transcript
-
-genie metrics now                            # Real-time metrics
-genie metrics history [--days N]             # Historical trends
-genie metrics agents                         # Per-agent metrics
-```
-
-### Teams
-```bash
-genie team create <name> --repo <path> [--wish <slug>]
-genie team hire <agent> | fire <agent>
-genie team ls [<name>]
-genie team done | blocked | disband <name>
-```
-
-### Dispatch
-```bash
-genie work <agent> <slug>#<group>     # Dispatch work on a group
-genie review <agent> <slug>#<group>   # Dispatch review
-genie task done <slug>#<group>        # Mark group done
-genie reset <slug>#<group>            # Reset stuck group
-genie task status <slug>              # Show group states
-```
-
-### Agents
-```bash
-genie agent spawn <name>              # Spawn agent
-genie agent kill <name> | stop <name> # Kill or stop
-genie agent list                      # List agents and teams
-genie agent log <name> --raw          # Tail output
-genie agent answer <name> <choice>    # Answer prompt
-```
-
-### Messaging
-```bash
-genie agent send '<msg>' --to <name>  # Direct message
-genie agent send '<msg>' --broadcast  # Message all team members
-genie chat '<msg>'                    # Post to team channel
-genie agent inbox [<name>]            # View inbox
-```
-
-## Communication Rules
-
-- **Same-session teammates** (spawned via `genie agent spawn`): Use `SendMessage` (Claude Code native IPC)
-- **Cross-session agents** (different tmux windows/teams): Use `genie agent send`
-
-## Tool Restrictions
-
-- NEVER use the `Agent` tool to spawn agents — use `genie agent spawn` instead
-- NEVER use `TeamCreate` or `TeamDelete` — use `genie team create` / `genie team disband`
+!`cat ${CLAUDE_SKILL_DIR}/reference/lifecycle.md 2>/dev/null`
 
 ## Rules
 
@@ -268,4 +103,7 @@ genie agent inbox [<name>]            # View inbox
 - One question at a time. Don't overwhelm with choices.
 - Always suggest the next concrete action — never leave the user hanging.
 - When in doubt, recommend `/brainstorm` to clarify before planning.
-- For prompt refinement, suggest `/refine` — it applies prompt-optimizer techniques.
+- Context from `$ARGUMENTS` passes through to the invoked skill — include the user's topic.
+- For prompt refinement, suggest `/refine`.
+- NEVER use the Agent tool to spawn agents — use `genie spawn` instead.
+- NEVER use TeamCreate/TeamDelete — use `genie team create` / `genie team disband`.

package/skills/genie/reference/lifecycle.md

@@ -0,0 +1,65 @@
+# Genie Wish Lifecycle
+
+Every piece of work follows this flow:
+
+```
+ Idea → /brainstorm → /wish → /review → /work → /review → PR → Ship
+         (explore)    (plan)   (gate)   (build)  (verify)
+```
+
+## Skills
+
+| Skill | Purpose | When to use |
+|-------|---------|-------------|
+| `/brainstorm` | Explore ambiguous ideas interactively. Tracks Wish Readiness Score (WRS) across 5 dimensions. Auto-crystallizes into DESIGN.md at WRS 100. | Idea is fuzzy, scope unclear |
+| `/wish` | Convert a design into a structured plan at `.genie/wishes/<slug>/WISH.md`. Defines scope, execution groups, acceptance criteria, and validation commands. | Idea is concrete, needs a plan |
+| `/review` | Universal quality gate. Returns SHIP / FIX-FIRST / BLOCKED with severity-tagged gaps. | Before and after `/work`, or to validate any plan |
+| `/work` | Execute an approved wish. Dispatches subagents per execution group. Runs fix loops on failures. | Wish is SHIP-approved, ready to build |
+| `/fix` | Dispatch fix subagent for FIX-FIRST gaps from review. Re-reviews after fix, escalates after 2 failed loops. | Review returned FIX-FIRST |
+| `/council` | Multi-perspective architectural review with 10 specialist viewpoints. | Major design decisions, tradeoff analysis |
+| `/refine` | Transform a prompt into a structured, production-ready prompt via prompt-optimizer. | Prompt needs sharpening |
+| `/report` | Investigate bugs — cascade through trace, capture evidence, create GitHub issue. | Bug reports, error investigation |
+| `/trace` | Reproduce, trace, and isolate root cause without patching. | Unknown issues needing investigation |
+| `/docs` | Audit, generate, and validate documentation against actual code. | Documentation needs updating |
+| `/dream` | Batch-execute SHIP-ready wishes overnight. | Multiple wishes ready for autonomous execution |
+| `/learn` | Diagnose and fix agent behavioral issues. | When the agent makes a recurring mistake |
+
+## Team Execution
+
+For autonomous execution, create a team with a wish:
+
+```bash
+genie team create my-feature --repo . --wish my-feature-slug
+```
+
+This creates a git worktree, hires default agents (team-lead, engineer, reviewer, qa, fix), and the team-lead orchestrates the full build-review-ship cycle.
+
+### Monitoring
+
+```bash
+genie team ls                         # List all teams
+genie team ls my-feature              # Show team members
+genie task status my-feature-slug     # Wish group progress
+genie agent log team-lead             # Unified log
+genie agent log team-lead --raw       # Raw pane output
+```
+
+### Team Lifecycle
+
+```bash
+genie team done <name>                # Mark done, kill members
+genie team blocked <name>             # Mark blocked, kill members
+genie team disband <name>             # Full cleanup
+```
+
+## Agent Resolution Order
+
+When spawning, genie resolves agents in three tiers:
+1. **Directory** — custom agents registered with `genie dir add`
+2. **Built-in roles** — engineer, reviewer, qa, fix, refactor, trace, docs
+3. **Fallback** — generic agent with the given name
+
+## Communication
+
+- **Same-session teammates** (spawned via `genie agent spawn`): Use `SendMessage` (Claude Code native IPC)
+- **Cross-session agents** (different tmux windows/teams): Use `genie agent send`

package/src/db/migrations/016_team_spawner.sql

@@ -0,0 +1,5 @@
+-- 016: Team Spawner — track who created each team.
+-- Adds `spawner` column to teams table for orchestrator tracking.
+-- Idempotent: safe to re-run.
+
+ALTER TABLE teams ADD COLUMN IF NOT EXISTS spawner TEXT;

package/src/db/migrations/017_wishes_table.sql

@@ -0,0 +1,18 @@
+-- 017: Wishes table — filesystem wish index for cross-repo querying.
+-- Synced from .genie/wishes/*/WISH.md files in each repo.
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS wishes (
+  id SERIAL PRIMARY KEY,
+  slug TEXT NOT NULL,
+  repo TEXT NOT NULL,
+  namespace TEXT,
+  status TEXT DEFAULT 'DRAFT',
+  file_path TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT now(),
+  updated_at TIMESTAMPTZ DEFAULT now(),
+  UNIQUE(slug, repo)
+);
+
+CREATE INDEX IF NOT EXISTS idx_wishes_status ON wishes(status);
+CREATE INDEX IF NOT EXISTS idx_wishes_namespace ON wishes(namespace) WHERE namespace IS NOT NULL;

package/src/genie-commands/session.ts

@@ -62,12 +62,22 @@ interface SessionOptions {
  * The leadSessionId is a placeholder -- CC updates it internally once started.
  * CC recognizes itself as leader because --team-name is passed without --agent-id.
  */
+async function resolveSessionLeaderName(teamName: string): Promise<string> {
+  try {
+    const { resolveLeaderName } = await import('../lib/team-manager.js');
+    return await resolveLeaderName(teamName);
+  } catch {
+    return 'team-lead'; // Fallback for legacy teams or when DB is unavailable
+  }
+}
+
 async function ensureNativeTeamForLeader(teamName: string, cwd: string): Promise<void> {
-  await ensureNativeTeam(teamName, `Genie team: ${teamName}`, 'pending');
+  const leaderName = await resolveSessionLeaderName(teamName);
+  await ensureNativeTeam(teamName, `Genie team: ${teamName}`, 'pending', leaderName);
 
   await registerNativeMember(teamName, {
     agentName: basename(cwd),
-    agentType: 'team-lead',
+    agentType: leaderName,
     color: 'blue',
     cwd,
   });
@@ -93,12 +103,14 @@ async function registerSessionInRegistry(sessionName: string, windowName: string
     const paneId = (await tmux.executeTmux(`display -t ${shellQuote(target)} -p '#{pane_id}'`)).trim();
     const now = new Date().toISOString();
     const sanitized = sanitizeTeamName(windowName);
+    const leaderName = await resolveSessionLeaderName(windowName);
+    const sanitizedLeader = sanitizeTeamName(leaderName);
     await registry.register({
-      id: `${sanitized}-team-lead`,
+      id: `${sanitized}-${sanitizedLeader}`,
       paneId,
       session: sessionName,
       team: windowName,
-      role: 'team-lead',
+      role: leaderName,
       worktree: null,
       startedAt: now,
       state: 'working',
@@ -107,11 +119,11 @@ async function registerSessionInRegistry(sessionName: string, windowName: string
       provider: 'claude',
       transport: 'tmux',
       nativeTeamEnabled: true,
-      nativeAgentId: `team-lead@${sanitized}`,
+      nativeAgentId: `${sanitizedLeader}@${sanitized}`,
     });
 
-    // Executor model: create agent identity + executor for team-lead session
-    const agentIdentity = await registry.findOrCreateAgent('team-lead', sanitized, 'team-lead');
+    // Executor model: create agent identity + executor for leader session
+    const agentIdentity = await registry.findOrCreateAgent(leaderName, sanitized, leaderName);
     await executorRegistry.terminateActiveExecutor(agentIdentity.id);
 
     let pid: number | null = null;

package/src/genie.ts

@@ -32,6 +32,7 @@ import { registerHookNamespace } from './hooks/dispatch-command.js';
 import { getActor, recordAuditEvent } from './lib/audit.js';
 import { shutdown as shutdownDb } from './lib/db.js';
 import { stopOtelReceiver } from './lib/otel-receiver.js';
+import { registerAgentCommands } from './term-commands/agent/index.js';
 import {
   type SpawnOptions,
   handleLsCommand,
@@ -46,7 +47,7 @@ import { registerBoardCommands } from './term-commands/board.js';
 import { registerBriefCommands } from './term-commands/brief.js';
 import { registerDaemonCommands } from './term-commands/daemon.js';
 import { registerDbCommands } from './term-commands/db.js';
-import { registerAgentNamespace, registerDirNamespace } from './term-commands/dir.js';
+import { registerDirNamespace } from './term-commands/dir.js';
 import { registerDispatchCommands } from './term-commands/dispatch.js';
 import { registerExportCommands } from './term-commands/export.js';
 import * as historyCmd from './term-commands/history.js';
@@ -100,6 +101,19 @@ const program = new Command();
 
 program.name('genie').description('Genie CLI - AI-assisted development').version(VERSION);
 
+program.configureHelp({
+  sortSubcommands: true,
+  showGlobalOptions: true,
+});
+
+program.configureOutput({
+  outputError: (str, write) => {
+    const cmd = program.commands.find((c) => process.argv.slice(2, 6).includes(c.name()));
+    const prefix = cmd ? `genie ${cmd.name()}` : 'genie';
+    write(`\x1b[31mError (${prefix}): ${str}\x1b[0m\n`);
+  },
+});
+
 // ============================================================================
 // Named session — genie --session <name>
 // ============================================================================
@@ -182,7 +196,7 @@ registerAppCommand(program);
 registerInitCommands(program);
 registerTeamNamespace(program);
 registerDirNamespace(program);
-registerAgentNamespace(program);
+registerAgentCommands(program);
 registerSendInboxCommands(program);
 registerStateCommands(program);
 registerDispatchCommands(program);
@@ -249,7 +263,7 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
 });
 
 // ============================================================================
-// Top-level agent commands (promoted from genie agent namespace)
+// Top-level aliases — shortcuts for genie agent <command>
 // ============================================================================
 
 // genie spawn <name>
@@ -268,6 +282,15 @@ program
   .option('--cwd <path>', 'Working directory for the agent (overrides directory entry)')
   .option('--session <session>', 'Tmux session name to spawn into')
   .option('--no-auto-resume', 'Disable auto-resume on pane death')
+  .addHelpText(
+    'after',
+    `
+Examples:
+  genie spawn engineer                          # Spawn built-in engineer role
+  genie spawn researcher --model sonnet         # Spawn with model override
+  genie spawn my-agent --team my-feature        # Spawn into a specific team
+  genie spawn council--questioner --provider codex  # Use Codex provider`,
+  )
   .action(async (name: string, options: SpawnOptions) => {
     try {
       await handleWorkerSpawn(name, options);

package/src/hooks/handlers/auto-spawn.ts

@@ -49,6 +49,17 @@ function buildSpawnArgs(template: {
   return args;
 }
 
+/** Check if the recipient is the team's actual leader (dynamic name, not 'team-lead' alias). */
+async function isRecipientLeader(recipient: string, teamName: string): Promise<boolean> {
+  try {
+    const { getTeam } = await import('../../lib/team-manager.js');
+    const config = await getTeam(teamName);
+    return !!config?.leader && recipient === config.leader;
+  } catch {
+    return false;
+  }
+}
+
 export async function autoSpawn(payload: HookPayload): Promise<HandlerResult> {
   const input = payload.tool_input;
   if (!input || input.type !== 'message') return;
@@ -59,6 +70,9 @@ export async function autoSpawn(payload: HookPayload): Promise<HandlerResult> {
   const teamName = process.env.GENIE_TEAM ?? payload.team_name;
   if (!teamName) return;
 
+  // Skip auto-spawn for the team's actual leader (not just 'team-lead' alias)
+  if (await isRecipientLeader(recipient, teamName)) return;
+
   try {
     const registryMod = await import('../../lib/agent-registry.js');
     const tmuxMod = await import('../../lib/tmux.js');