@automagik/genie 0.260202.1833 → 0.260203.43

package/plugin/skills/genie-cli-dev/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: genie-cli-dev
+description: "Development guide for genie-cli - the AI-friendly terminal orchestration tool built on tmux. Use when modifying term commands, tmux library, or adding new CLI features."
+---
+
+# Genie-CLI Development Guide
+
+## Overview
+
+Genie-CLI (`tools/genie-cli/`) is an AI-friendly terminal orchestration system built on tmux. It provides two main entry points:
+
+- **`genie`** - Setup and utilities (install, setup, doctor, shortcuts)
+- **`term`** - Terminal orchestration (session/window/pane management, command execution)
+
+**Stack:** TypeScript, Bun, Commander.js, tmux
+
+---
+
+## Architecture
+
+```
+tools/genie-cli/
+├── src/
+│   ├── genie.ts          # genie CLI entry point
+│   ├── term.ts           # term CLI entry point
+│   ├── lib/
+│   │   ├── tmux.ts       # Core tmux wrapper (CRITICAL)
+│   │   ├── tmux-wrapper.ts
+│   │   ├── config.ts
+│   │   ├── worktree.ts   # Git worktree management
+│   │   ├── worker-registry.ts
+│   │   └── orchestrator/ # Claude Code automation
+│   ├── term-commands/    # term subcommands
+│   │   ├── split.ts
+│   │   ├── new.ts
+│   │   ├── ls.ts
+│   │   ├── exec.ts
+│   │   ├── read.ts
+│   │   ├── window.ts
+│   │   ├── pane.ts
+│   │   ├── spawn.ts      # Skill-based Claude spawning
+│   │   ├── work.ts       # Worker orchestration
+│   │   └── orchestrate.ts
+│   └── genie-commands/   # genie subcommands
+│       ├── install.ts
+│       ├── setup.ts
+│       └── doctor.ts
+└── plugin/               # Claude Code plugin
+```
+
+---
+
+## Core tmux Library (`src/lib/tmux.ts`)
+
+### Key Interfaces
+
+```typescript
+interface TmuxSession {
+  id: string;       // e.g., "$0"
+  name: string;     // User-friendly name
+  attached: boolean;
+  windows: number;
+}
+
+interface TmuxWindow {
+  id: string;       // e.g., "@0"
+  name: string;
+  active: boolean;  // Is this the active window?
+  sessionId: string;
+}
+
+interface TmuxPane {
+  id: string;       // e.g., "%0"
+  windowId: string;
+  active: boolean;  // Is this the active pane?
+  title: string;
+}
+```
+
+### Critical Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `listSessions()` | Get all tmux sessions | `TmuxSession[]` |
+| `findSessionByName(name)` | Find session by name | `TmuxSession \| null` |
+| `listWindows(sessionId)` | Get windows in session | `TmuxWindow[]` |
+| `listPanes(windowId)` | Get panes in window | `TmuxPane[]` |
+| `splitPane(paneId, direction, size?, workingDir?)` | Split a pane | `TmuxPane \| null` |
+| `executeCommand(paneId, command)` | Run command in pane | `commandId` |
+| `runCommandSync(paneId, command, timeout?)` | Run command and wait | `{output, exitCode}` |
+| `capturePaneContent(paneId, lines?)` | Read pane output | `string` |
+
+### Finding Active Window/Pane
+
+Both `TmuxWindow` and `TmuxPane` have an `active: boolean` property parsed from tmux format strings:
+
+```typescript
+// From listWindows - uses #{?window_active,1,0}
+const activeWindow = windows.find(w => w.active) || windows[0];
+
+// From listPanes - uses #{?pane_active,1,0}
+const activePane = panes.find(p => p.active) || panes[0];
+```
+
+**Common bug pattern:** Using `windows[0]` or `panes[0]` instead of finding the active one.
+
+---
+
+## Term Commands Pattern
+
+Each command in `src/term-commands/` follows this pattern:
+
+```typescript
+// Example: split.ts
+import * as tmux from '../lib/tmux.js';
+
+export interface SplitOptions {
+  workspace?: string;
+  worktree?: string;
+}
+
+export async function splitSessionPane(
+  sessionName: string,
+  direction?: string,
+  options: SplitOptions = {}
+): Promise<void> {
+  // 1. Find session
+  const session = await tmux.findSessionByName(sessionName);
+  if (!session) { /* error handling */ }
+
+  // 2. Get windows/panes
+  const windows = await tmux.listWindows(session.id);
+  // ...
+
+  // 3. Perform operation
+  // ...
+}
+```
+
+### Registering Commands
+
+Commands are registered in `src/term.ts` using Commander.js:
+
+```typescript
+program
+  .command('split <session> [direction]')
+  .description('Split pane in a tmux session (h=horizontal, v=vertical)')
+  .option('-d, --workspace <path>', 'Working directory for the new pane')
+  .action(async (session, direction, options) => {
+    await splitCmd.splitSessionPane(session, direction, options);
+  });
+```
+
+---
+
+## Common Patterns
+
+### Session → Window → Pane Navigation
+
+```typescript
+// Get session by name
+const session = await tmux.findSessionByName(sessionName);
+
+// Get windows in session
+const windows = await tmux.listWindows(session.id);
+
+// Find ACTIVE window (not just first!)
+const activeWindow = windows.find(w => w.active) || windows[0];
+
+// Get panes in window
+const panes = await tmux.listPanes(activeWindow.id);
+
+// Find ACTIVE pane (not just first!)
+const activePane = panes.find(p => p.active) || panes[0];
+```
+
+### Getting Pane Working Directory
+
+```typescript
+const currentPath = await tmux.executeTmux(
+  `display-message -p -t '${paneId}' '#{pane_current_path}'`
+);
+```
+
+### Splitting Panes
+
+```typescript
+const newPane = await tmux.splitPane(
+  targetPaneId,
+  'horizontal' | 'vertical',  // direction
+  undefined,                   // size (percentage)
+  workingDir                   // optional working directory
+);
+```
+
+---
+
+## Known Issues & Fixes
+
+### Issue: Commands target first pane instead of active pane
+
+**Symptom:** `term split genie h` splits the first pane of first window, not the user's current pane.
+
+**Root cause:** Using `windows[0]` and `panes[0]` instead of finding active.
+
+**Fix pattern:**
+```typescript
+// Before (wrong)
+const panes = await tmux.listPanes(windows[0].id);
+const paneId = panes[0].id;
+
+// After (correct)
+const activeWindow = windows.find(w => w.active) || windows[0];
+const panes = await tmux.listPanes(activeWindow.id);
+const activePane = panes.find(p => p.active) || panes[0];
+const paneId = activePane.id;
+```
+
+---
+
+## Testing Commands
+
+```bash
+# Build
+cd tools/genie-cli && bun run build
+
+# Test term commands
+term ls                    # List sessions
+term new test-session      # Create session
+term window ls test-session # List windows
+term pane ls test-session  # List panes
+term split test-session h  # Split horizontally
+term rm test-session       # Cleanup
+```
+
+---
+
+## Worker Orchestration
+
+Workers bind Claude Code sessions to beads issues:
+
+```bash
+term work <bd-id>      # Spawn worker for issue
+term work next         # Work on next ready issue
+term workers           # List workers
+term close <bd-id>     # Close issue and cleanup
+term kill <worker>     # Force kill worker
+```
+
+Worker state tracked in `src/lib/worker-registry.ts`.
+
+---
+
+## Orchestrator (Claude Automation)
+
+The `src/lib/orchestrator/` module automates Claude Code:
+
+- **Completion detection** - Detect when Claude finishes
+- **State detection** - Parse Claude's current state from terminal output
+- **Event monitoring** - Watch for permissions, questions, errors
+
+```bash
+term orc start genie       # Start Claude with monitoring
+term orc status genie      # Check Claude state
+term orc send genie "msg"  # Send message and wait
+term orc approve genie     # Approve permission
+term orc answer genie 1    # Answer question
+term orc run genie "task"  # Fire-and-forget with auto-approve
+```
+
+---
+
+## Development Workflow
+
+1. Edit source in `src/`
+2. Build: `bun run build`
+3. Test: `term <command>`
+4. The CLI is symlinked, so rebuilt files are immediately available
+
+---
+
+## Key Files Reference
+
+| File | Purpose |
+|------|---------|
+| `src/lib/tmux.ts` | All tmux operations |
+| `src/term.ts` | Command registration |
+| `src/term-commands/split.ts` | Pane splitting |
+| `src/term-commands/spawn.ts` | Skill-based Claude spawning |
+| `src/term-commands/orchestrate.ts` | Claude automation |
+| `src/lib/orchestrator/state-detector.ts` | Claude state parsing |
+| `src/lib/worker-registry.ts` | Worker state tracking |

package/plugin/skills/plan-review/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: plan-review
+description: "Validate a wish document (structure, scope boundaries, acceptance criteria, validation commands). Use after creating or editing .genie/wishes/<slug>/wish.md to catch missing sections before forge."
+---
+
+# Plan Review - Validate Wish Documents
+
+## Overview
+
+Fast structural/quality check on wish documents before execution. Catches missing sections and weak criteria.
+
+**Two verdicts: PASS / NEEDS ATTENTION**
+
+---
+
+## How to Run
+
+1. Identify the wish file to validate (`.genie/wishes/<slug>/wish.md`)
+2. Check all items below
+3. Report PASS or NEEDS ATTENTION with fix list
+
+---
+
+## Validation Checklist
+
+### Structure Completeness
+
+- [ ] Has `## Summary` (2-3 sentences)
+- [ ] Has `## Scope` with `### IN` and `### OUT`
+- [ ] OUT scope is **not empty** (must explicitly exclude something)
+- [ ] Has `## Success Criteria` with checkbox items (`- [ ]`)
+- [ ] Has `## Execution Groups` with at least one `### Group`
+
+### Task Quality (per execution group)
+
+- [ ] Each group has `**Goal:**` (one sentence)
+- [ ] Each group has `**Deliverables:**` list
+- [ ] Each group has `**Acceptance Criteria:**` with checkboxes
+- [ ] Each group has `**Validation:**` with a concrete command
+- [ ] Tasks are specific (not "implement everything")
+- [ ] Tasks are small enough for one focused session
+
+### Scope Boundaries
+
+- [ ] OUT contains explicit exclusions (not empty)
+- [ ] IN and OUT do not contradict
+- [ ] Scope is realistic for the task count
+
+### Acceptance Criteria Quality
+
+- [ ] Criteria are testable (can verify pass/fail)
+- [ ] Criteria are specific (not "works correctly")
+- [ ] Validation commands are executable
+
+---
+
+## Output Format
+
+**If all checks pass:**
+
+```
+Plan review: PASS
+
+Wish document is well-structured and ready for /forge.
+```
+
+**If checks fail:**
+
+```
+Plan review: NEEDS ATTENTION
+
+Structure:
+- [ ] Missing OUT scope - add explicit exclusions
+
+Task Quality:
+- [ ] Group B missing validation command
+- [ ] Group C acceptance criteria too vague ("works correctly")
+
+Scope:
+- [ ] IN/OUT contradiction: X is in both sections
+
+Fix these issues, then run /plan-review again.
+```
+
+---
+
+## Key Principles
+
+- **Fast** - This is a gate check, seconds not minutes
+- **Structure over content** - Check format, not design quality
+- **Actionable feedback** - Every issue includes what to fix
+- **Don't block on style** - Focus on missing/broken structure
+
+---
+
+## Never Do
+
+- Modify the wish document (only report)
+- Block on style/naming preferences
+- Deep review of design quality (trust brainstorm/wish phases)
+- Take more than 30 seconds to run

package/plugin/skills/review/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: review
+description: "Use when all forge tasks are complete and work needs final validation - produces SHIP/FIX-FIRST/BLOCKED verdict with categorized gaps."
+---
+
+# Review - Final Validation
+
+## Overview
+
+After forge completes all tasks, run comprehensive final review. Check every success criterion with evidence, run validation commands, do quality spot-check, and produce the ship decision.
+
+**Three verdicts: SHIP / FIX-FIRST / BLOCKED**
+
+---
+
+## The Flow
+
+### 1. Load Wish & Verify Tasks
+
+```
+Read .genie/wishes/<slug>/wish.md
+Check TaskList for wish tasks
+Verify all tasks marked complete
+```
+
+**If tasks incomplete:** Stop. Output: "Forge not complete. [N] tasks remaining. Run /forge to continue."
+
+### 2. Task Completion Audit
+
+For each execution group in the wish:
+- Check the task was completed
+- Verify acceptance criteria checkboxes are checked
+- Note any tasks that were BLOCKED during forge
+
+**Output per group:**
+```
+Group A: [name]
+- Task: COMPLETE | BLOCKED
+- Criteria: [X/Y] checked
+```
+
+### 3. Criterion-by-Criterion Audit
+
+For each success criterion in the wish document:
+
+- **PASS**: Evidence exists. Describe the evidence.
+- **FAIL**: Not met. Categorize the gap.
+
+**Gap Categories:**
+
+| Severity | Meaning | Blocks Ship? |
+|----------|---------|--------------|
+| CRITICAL | Broken functionality, security flaw, data loss | Yes |
+| HIGH | Missing feature, major bug, test failure | Yes |
+| MEDIUM | Missing edge case, incomplete docs | No |
+| LOW | Style, naming, minor polish | No |
+
+### 4. Run All Validation Commands
+
+Execute validation command for each execution group:
+
+```
+For each execution group:
+  Run its validation command
+  Record: PASS or FAIL with output
+```
+
+### 5. Quality Spot-Check
+
+Dispatch a quick quality review:
+
+```
+Task tool dispatch:
+  subagent_type: general-purpose
+  prompt: |
+    Quick quality review for wish: [slug]
+
+    Check the changes made across all execution groups.
+    Look for obvious issues:
+    - Security vulnerabilities
+    - Broken error handling
+    - Missing null checks
+    - Obvious performance issues
+
+    Verdict: OK or CONCERNS with brief list.
+```
+
+### 6. Browser Tests (Optional)
+
+If the wish involves user-facing changes and agent-browser is available:
+- Navigate to relevant pages
+- Verify user-visible behavior
+- Capture screenshots as evidence
+
+**If agent-browser is not available:** Skip gracefully. Note: "Browser tests skipped - agent-browser not available."
+
+### 7. Verdict
+
+**SHIP** - All criteria pass. No CRITICAL or HIGH gaps.
+
+```
+Conditions:
+  - Zero CRITICAL gaps
+  - Zero HIGH gaps
+  - All validation commands pass
+  - No BLOCKED tasks
+  - Quality spot-check returns OK or minor concerns only
+  - MEDIUM/LOW gaps are advisory only
+```
+
+**FIX-FIRST** - Fixable issues found. Return to forge.
+
+```
+Conditions:
+  - One or more HIGH gaps (fixable)
+  - Or validation commands failing
+  - Quality spot-check found significant concerns
+  - Provide specific fix list for /forge
+```
+
+**BLOCKED** - Fundamental issues. Return to wish.
+
+```
+Conditions:
+  - CRITICAL gaps that require scope changes
+  - Or architectural problems that can't be fixed in forge
+  - Any BLOCKED tasks from forge
+  - Provide specific issues requiring wish revision
+```
+
+### 8. Write Results
+
+Update the wish document with review results:
+
+```markdown
+## Review Results
+
+**Verdict:** SHIP | FIX-FIRST | BLOCKED
+**Date:** YYYY-MM-DD
+
+### Task Completion
+| Group | Status | Criteria |
+|-------|--------|----------|
+| A | COMPLETE | 3/3 |
+| B | COMPLETE | 2/2 |
+
+### Criteria Check
+- [x] Criterion 1 - PASS: [evidence]
+- [ ] Criterion 2 - FAIL (HIGH): [gap description]
+
+### Validation Commands
+- [x] `command 1` - PASS
+- [ ] `command 2` - FAIL: [output]
+
+### Quality Spot-Check
+Verdict: OK
+Notes: [brief notes if any]
+
+### Browser Tests
+- [x] Page loads correctly
+- Skipped: agent-browser not available
+
+### Gaps
+| # | Severity | Description | Fix |
+|---|----------|-------------|-----|
+| 1 | HIGH | Missing error handling | Add try/catch in handler.ts |
+| 2 | MEDIUM | No edge case test | Add test for empty input |
+
+### Recommendation
+[One paragraph: what to do next]
+```
+
+---
+
+## After Review
+
+**If SHIP:**
+```
+"Review passed. Work is complete and ready to ship."
+```
+
+**If FIX-FIRST:**
+```
+"Review found fixable issues. Run /forge to address:
+1. [gap 1]
+2. [gap 2]
+Then run /review again."
+```
+
+**If BLOCKED:**
+```
+"Review found fundamental issues requiring scope changes.
+Revise the wish document to address:
+1. [issue 1]
+2. [issue 2]
+Then run /forge and /review again."
+```
+
+---
+
+## Key Principles
+
+- **Every criterion checked** - No skipping, no "probably fine"
+- **Evidence required** - PASS needs proof, not assumption
+- **Gaps categorized** - Severity determines whether it blocks
+- **Actionable feedback** - Every FAIL includes how to fix
+- **Browser tests graceful** - Skip if agent-browser unavailable, don't fail
+- **Results written to wish** - Review results live in the wish document
+
+---
+
+## Never Do
+
+- Declare SHIP with CRITICAL or HIGH gaps
+- Skip validation commands
+- Mark criteria PASS without evidence
+- Re-implement fixes during review (that's forge's job)
+- Change scope during review (that's wish's job)
+- Block on MEDIUM or LOW gaps
+- Pass with BLOCKED tasks from forge
+- Forget to write results back to the wish document