@automagik/genie 0.260202.1833 → 0.260203.43

package/plugin/skills/wish/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: wish
+description: "Use when starting non-trivial work that needs structured planning - converts ideas into wish documents with scope, acceptance criteria, and execution tasks."
+---
+
+# Wish - Turn Ideas Into Plans
+
+## Overview
+
+Convert a validated design (from `/brainstorm`) or direct request into a structured wish document. Create native Claude Code tasks for execution.
+
+**Output:** `.genie/wishes/<slug>/wish.md` + native tasks ready for `/forge`
+
+---
+
+## The Flow
+
+### Phase 1: Brainstorm (if needed)
+
+If coming from `/brainstorm`, the design is already validated. If starting fresh:
+
+Enter plan mode to explore the codebase read-only. Understand the landscape before proposing anything.
+
+**One question at a time. Multiple choice when possible.**
+
+1. **Resonate** - Understand the intent
+   - What does the user actually want? (not just what they said)
+   - Ask clarifying questions, one at a time
+   - Prefer multiple choice: "Which of these best describes what you want?"
+
+2. **Explore approaches** - Propose 2-3 alternatives
+   - Present options with trade-offs
+   - Lead with your recommendation and explain why
+   - Let the user choose (or propose something different)
+
+3. **Align on scope** - Define boundaries
+   - What's IN scope?
+   - What's explicitly OUT of scope?
+   - What assumptions are we making?
+
+### Phase 2: Design (200-300 Word Sections)
+
+Present the design incrementally. Check after each section.
+
+**Sections to cover:**
+- Summary (what and why, 2-3 sentences)
+- Architecture approach
+- Key decisions with rationale
+- Risks and mitigations
+
+### Phase 3: Plan (Bite-Sized Tasks)
+
+Break the design into execution groups. Each task should be:
+- **Small enough** to implement in one focused session
+- **Testable** with clear acceptance criteria
+- **Independent** where possible (minimize blocking dependencies)
+
+**Per task, define:**
+- What to do (deliverables)
+- Acceptance criteria (checkboxes)
+- Validation command (how to verify it worked)
+- Files likely touched
+
+### Phase 4: Write the Wish Document
+
+Write to `.genie/wishes/<slug>/wish.md` using the template from `references/wish-template.md`.
+
+**Required sections:**
+- Status, Slug, Created date
+- Summary (what and why)
+- Scope (IN and OUT - OUT must not be empty)
+- Decisions with rationale
+- Success Criteria (checkboxes)
+- Execution Groups with acceptance criteria and validation commands
+
+### Phase 5: Create Native Tasks
+
+After writing the wish document:
+- Use `TaskCreate` for each execution group
+- Set up `addBlockedBy` dependencies between tasks
+- Include wish slug and group name in task description
+
+### Phase 6: Handoff
+
+Output: **"Wish documented. Run `/plan-review` to validate, then `/forge` to begin execution."**
+
+---
+
+## Key Principles
+
+- **One question at a time** - Never ask multiple questions in one message
+- **Multiple choice preferred** - Easier for users to answer
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Acceptance criteria are king** - Every task must have testable criteria
+- **Validation commands required** - Every task must have a way to verify completion
+- **Explore before proposing** - Read code before designing changes
+- **Small tasks** - If a task feels big, split it
+
+---
+
+## Never Do
+
+- Skip brainstorming and jump to plan writing
+- Ask more than one question per message
+- Create tasks without acceptance criteria
+- Create tasks without validation commands
+- Write a wish without user agreement on scope
+- Start implementation during wish creation (plan mode only)
+- Create overly broad tasks ("implement everything")
+- Leave OUT scope empty (always exclude something explicitly)

package/plugin/skills/work-orchestration/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: work-orchestration
+description: "How to orchestrate real work with the human using term, claudio, and beads. Stop planning, start doing."
+---
+
+# Work Orchestration
+
+## The Stack
+
+- **term** - Terminal/tmux orchestration
+- **claudio** - Claude Code API automation
+- **beads** - Task/issue tracking (bd CLI)
+- **worktrees** - Isolated git branches for parallel work
+
+## Start Working NOW
+
+### 1. Check Current State
+
+```bash
+term ls                    # What sessions exist?
+term workers               # Any active workers?
+bd ls                      # What issues are ready?
+```
+
+### 2. Pick or Create Work
+
+```bash
+# Work on existing issue
+term work <bd-id>
+
+# Or create new issue and work it
+term create "Fix the thing" && term work next
+```
+
+### 3. Execute
+
+The worker spawns Claude in a pane. You can:
+- Watch: `tmux attach -t genie`
+- Approve: `term approve <worker>`
+- Answer: `term answer <worker> <choice>`
+- Check: `term orc status genie`
+
+### 4. Close When Done
+
+```bash
+term close <bd-id>         # Closes issue, cleans worktree
+```
+
+---
+
+## Parallel Work Pattern
+
+Split work across multiple panes/workers:
+
+```bash
+# In session "genie"
+term split genie h         # New pane (uses ACTIVE pane)
+term spawn forge           # Spawn Claude with skill
+```
+
+Or use workers for tracked work:
+
+```bash
+term work bd-001           # Worker 1
+term work bd-002           # Worker 2 (parallel)
+term workers               # See both
+```
+
+---
+
+## Human-AI Handoff
+
+**Human does:**
+- Approves permissions
+- Answers questions
+- Provides context when stuck
+- Reviews before merge
+
+**AI does:**
+- Implements tasks
+- Runs tests
+- Creates commits (when asked)
+- Reports blockers
+
+---
+
+## Quick Commands
+
+| Action | Command |
+|--------|---------|
+| See sessions | `term ls` |
+| See workers | `term workers` |
+| See issues | `bd ls` |
+| Start work | `term work <id>` |
+| Split pane | `term split genie h` |
+| Approve | `term approve <worker>` |
+| Answer | `term answer <worker> 1` |
+| Check status | `term orc status genie` |
+| Close work | `term close <id>` |
+
+---
+
+## Stop Planning, Start Doing
+
+1. What needs to be done? (one thing)
+2. Is there an issue? Create one if not
+3. `term work <id>` or just start coding
+4. Ship it
+
+No more circles.

package/scripts/build.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * Build script for automagik-genie plugin
+ * Bundles TypeScript CLIs into standalone CJS executables using esbuild
+ */
+
+import { build } from 'esbuild';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, '..');
+
+const TARGETS = [
+  { name: 'genie', source: 'src/genie.ts' },
+  { name: 'term', source: 'src/term.ts' },
+  { name: 'worker-service', source: 'src/services/worker-service.ts' },
+  { name: 'validate-wish', source: '.claude-plugin/scripts/validate-wish.ts' },
+  { name: 'validate-completion', source: '.claude-plugin/scripts/validate-completion.ts' }
+];
+
+async function buildPlugin() {
+  console.log('Building automagik-genie plugin...\n');
+
+  try {
+    // Read version from package.json
+    const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf-8'));
+    const version = packageJson.version;
+    console.log(`Version: ${version}`);
+
+    // Create output directory
+    const scriptsDir = path.join(rootDir, 'plugin/scripts');
+    if (!fs.existsSync(scriptsDir)) {
+      fs.mkdirSync(scriptsDir, { recursive: true });
+    }
+
+    // Generate plugin/package.json for dependency installation
+    console.log('\nGenerating plugin package.json...');
+    const pluginPackageJson = {
+      name: 'automagik-genie-plugin',
+      version: version,
+      private: true,
+      description: 'Runtime dependencies for automagik-genie bundled CLIs',
+      type: 'module',
+      dependencies: {},
+      engines: {
+        node: '>=18.0.0',
+        bun: '>=1.0.0'
+      }
+    };
+    fs.writeFileSync(
+      path.join(rootDir, 'plugin/package.json'),
+      JSON.stringify(pluginPackageJson, null, 2) + '\n'
+    );
+    console.log('plugin/package.json generated');
+
+    // Build each target
+    for (const target of TARGETS) {
+      const sourcePath = path.join(rootDir, target.source);
+
+      // Check if source exists
+      if (!fs.existsSync(sourcePath)) {
+        console.log(`\nSkipping ${target.name} (source not found: ${target.source})`);
+        continue;
+      }
+
+      console.log(`\nBuilding ${target.name}...`);
+
+      const outfile = `${scriptsDir}/${target.name}.cjs`;
+
+      await build({
+        entryPoints: [sourcePath],
+        bundle: true,
+        platform: 'node',
+        target: 'node18',
+        format: 'cjs',
+        outfile,
+        minify: true,
+        logLevel: 'error',
+        external: ['bun', 'bun:*'],
+        define: {
+          '__GENIE_VERSION__': `"${version}"`
+        }
+      });
+
+      // Add shebang (esbuild banner can cause duplicates if source has shebang)
+      const content = fs.readFileSync(outfile, 'utf-8');
+      const shebang = '#!/usr/bin/env bun\n';
+      // Remove any existing shebangs and add fresh one
+      const cleanContent = content.replace(/^#!.*\n/gm, '');
+      fs.writeFileSync(outfile, shebang + cleanContent);
+
+      // Make executable
+      fs.chmodSync(outfile, 0o755);
+
+      const stats = fs.statSync(`${scriptsDir}/${target.name}.cjs`);
+      console.log(`  ${target.name}.cjs (${(stats.size / 1024).toFixed(2)} KB)`);
+    }
+
+    // Copy smart-install.js (stays as Node.js, not bundled)
+    const smartInstallSrc = path.join(rootDir, 'scripts/smart-install.js');
+    const smartInstallDest = path.join(scriptsDir, 'smart-install.js');
+    if (fs.existsSync(smartInstallSrc)) {
+      fs.copyFileSync(smartInstallSrc, smartInstallDest);
+      console.log('\nCopied smart-install.js');
+    }
+
+    // Update plugin.json version
+    const pluginJsonPath = path.join(rootDir, 'plugin/.claude-plugin/plugin.json');
+    if (fs.existsSync(pluginJsonPath)) {
+      const pluginJson = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf-8'));
+      pluginJson.version = version;
+      fs.writeFileSync(pluginJsonPath, JSON.stringify(pluginJson, null, 2) + '\n');
+      console.log('Updated plugin.json version');
+    }
+
+    console.log('\nBuild complete!');
+    console.log(`Output: plugin/scripts/`);
+
+  } catch (error) {
+    console.error('\nBuild failed:', error.message);
+    if (error.errors) {
+      console.error('\nBuild errors:');
+      error.errors.forEach(err => console.error(`  - ${err.text}`));
+    }
+    process.exit(1);
+  }
+}
+
+buildPlugin();

package/scripts/smart-install.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Smart Install Script for automagik-genie
+ *
+ * Ensures required dependencies are installed:
+ * - Bun runtime (auto-installs if missing)
+ * - tmux (guides user if missing - can't auto-install)
+ * - beads (auto-installs if missing via npm)
+ *
+ * Also handles:
+ * - Dependency installation when version changes
+ * - CLI symlink creation for agent access
+ * - Version marker management
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, symlinkSync, unlinkSync } from 'fs';
+import { execSync, spawnSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(homedir(), '.claude', 'plugins', 'automagik-genie');
+const GENIE_DIR = join(homedir(), '.genie');
+const MARKER = join(GENIE_DIR, '.install-version');
+const BIN_DIR = join(homedir(), '.local', 'bin');
+const IS_WINDOWS = process.platform === 'win32';
+
+// Common installation paths (handles fresh installs before PATH reload)
+const BUN_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+  : [join(homedir(), '.bun', 'bin', 'bun'), '/usr/local/bin/bun', '/opt/homebrew/bin/bun'];
+
+const BEADS_COMMON_PATHS = IS_WINDOWS
+  ? [join(homedir(), 'AppData', 'Roaming', 'npm', 'bd.cmd')]
+  : [join(homedir(), '.local', 'bin', 'bd'), '/usr/local/bin/bd', '/opt/homebrew/bin/bd'];
+
+/**
+ * Get the Bun executable path
+ */
+function getBunPath() {
+  // Try PATH first
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bun';
+  } catch {
+    // Not in PATH
+  }
+  return BUN_COMMON_PATHS.find(existsSync) || null;
+}
+
+function isBunInstalled() {
+  return getBunPath() !== null;
+}
+
+function getBunVersion() {
+  const bunPath = getBunPath();
+  if (!bunPath) return null;
+  try {
+    const result = spawnSync(bunPath, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install Bun automatically
+ */
+function installBun() {
+  console.error('Installing Bun runtime...');
+  try {
+    if (IS_WINDOWS) {
+      execSync('powershell -c "irm bun.sh/install.ps1 | iex"', { stdio: 'inherit', shell: true });
+    } else {
+      execSync('curl -fsSL https://bun.sh/install | bash', { stdio: 'inherit', shell: true });
+    }
+    if (!isBunInstalled()) {
+      throw new Error('Bun installation completed but binary not found. Please restart your terminal.');
+    }
+    console.error(`Bun ${getBunVersion()} installed`);
+  } catch (error) {
+    console.error('Failed to install Bun. Please install manually:');
+    if (IS_WINDOWS) {
+      console.error('  winget install Oven-sh.Bun');
+    } else {
+      console.error('  curl -fsSL https://bun.sh/install | bash');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if tmux is installed
+ */
+function isTmuxInstalled() {
+  try {
+    const result = spawnSync('tmux', ['-V'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get tmux version
+ */
+function getTmuxVersion() {
+  try {
+    const result = spawnSync('tmux', ['-V'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if beads (bd) is installed
+ */
+function getBeadsPath() {
+  try {
+    const result = spawnSync('bd', ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: IS_WINDOWS
+    });
+    if (result.status === 0) return 'bd';
+  } catch {
+    // Not in PATH
+  }
+  return BEADS_COMMON_PATHS.find(existsSync) || null;
+}
+
+function isBeadsInstalled() {
+  return getBeadsPath() !== null;
+}
+
+/**
+ * Install beads via npm
+ */
+function installBeads() {
+  console.error('Installing beads (bd)...');
+  try {
+    execSync('npm install -g @anthropic-ai/bd', { stdio: 'inherit', shell: true });
+    if (!isBeadsInstalled()) {
+      throw new Error('beads installation completed but bd not found.');
+    }
+    console.error('beads installed');
+  } catch (error) {
+    console.error('Failed to install beads. Please install manually:');
+    console.error('  npm install -g @anthropic-ai/bd');
+    throw error;
+  }
+}
+
+/**
+ * Check if dependencies need to be installed
+ */
+function needsInstall() {
+  if (!existsSync(join(ROOT, 'node_modules'))) return true;
+  if (!existsSync(join(ROOT, 'package.json'))) return false; // No package.json = no deps needed
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    if (!existsSync(MARKER)) return true;
+    const marker = JSON.parse(readFileSync(MARKER, 'utf-8'));
+    return pkg.version !== marker.version || getBunVersion() !== marker.bun;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Install dependencies using Bun
+ */
+function installDeps() {
+  const bunPath = getBunPath();
+  if (!bunPath) {
+    throw new Error('Bun executable not found');
+  }
+
+  console.error('Installing dependencies...');
+
+  // Ensure .genie directory exists
+  if (!existsSync(GENIE_DIR)) {
+    mkdirSync(GENIE_DIR, { recursive: true });
+  }
+
+  const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
+  execSync(`${bunCmd} install`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+
+  // Write version marker
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+    version = pkg.version;
+  } catch {
+    // Ignore
+  }
+
+  writeFileSync(MARKER, JSON.stringify({
+    version,
+    bun: getBunVersion(),
+    tmux: getTmuxVersion(),
+    installedAt: new Date().toISOString()
+  }));
+}
+
+/**
+ * Create CLI symlinks for agent access
+ */
+function createCliSymlinks() {
+  // Ensure bin directory exists
+  if (!existsSync(BIN_DIR)) {
+    mkdirSync(BIN_DIR, { recursive: true });
+  }
+
+  const links = [
+    { name: 'genie', target: join(ROOT, 'scripts', 'genie.cjs') },
+    { name: 'term', target: join(ROOT, 'scripts', 'term.cjs') }
+  ];
+
+  for (const { name, target } of links) {
+    const linkPath = join(BIN_DIR, name);
+
+    // Skip if target doesn't exist
+    if (!existsSync(target)) {
+      continue;
+    }
+
+    // Remove existing symlink if it exists
+    try {
+      if (existsSync(linkPath)) {
+        unlinkSync(linkPath);
+      }
+    } catch {
+      // Ignore errors
+    }
+
+    // Create symlink
+    try {
+      symlinkSync(target, linkPath);
+      console.error(`Created symlink: ${linkPath} -> ${target}`);
+    } catch (error) {
+      console.error(`Warning: Could not create symlink for ${name}: ${error.message}`);
+    }
+  }
+}
+
+// Main execution
+try {
+  // 1. Check/install Bun
+  if (!isBunInstalled()) {
+    installBun();
+  }
+
+  // 2. Check tmux - REQUIRED, but can't auto-install
+  if (!isTmuxInstalled()) {
+    console.error('');
+    console.error('ERROR: tmux is required but not installed.');
+    console.error('');
+    console.error('Please install tmux manually:');
+    if (process.platform === 'darwin') {
+      console.error('  brew install tmux');
+    } else if (process.platform === 'linux') {
+      console.error('  sudo apt install tmux    # Debian/Ubuntu');
+      console.error('  sudo dnf install tmux    # Fedora/RHEL');
+      console.error('  sudo pacman -S tmux      # Arch');
+    } else if (IS_WINDOWS) {
+      console.error('  WSL is required for tmux on Windows');
+      console.error('  Inside WSL: sudo apt install tmux');
+    }
+    console.error('');
+    console.error('Then restart Claude Code.');
+    process.exit(2); // Exit code 2 = blocking error for Claude to process
+  }
+
+  // 3. Check/install beads
+  if (!isBeadsInstalled()) {
+    installBeads();
+  }
+
+  // 4. Install dependencies if needed
+  if (needsInstall()) {
+    installDeps();
+    console.error('Dependencies installed');
+  }
+
+  // 5. Create CLI symlinks
+  createCliSymlinks();
+
+} catch (e) {
+  console.error('Installation failed:', e.message);
+  process.exit(1);
+}