@automagik/genie 0.260202.1833 → 0.260203.43

package/.claude/skills/genie-review/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: "review"
+description: "Use when all forge tasks are complete and work needs final validation - produces pass/fail verdict with categorized gaps"
+---
+
+# Review - Final Validation
+
+## Overview
+
+After all forge tasks complete, run a final review of the entire wish. Check every success criterion, run integration tests, optionally run browser tests, and produce a verdict.
+
+**Three verdicts: SHIP / FIX-FIRST / BLOCKED**
+
+---
+
+## The Flow
+
+### 1. Load Wish
+
+```
+Read .genie/wishes/<slug>/wish.md
+Parse all success criteria
+Verify all forge tasks are marked complete
+```
+
+### 2. Wish Audit (Criterion by Criterion)
+
+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 |
+
+### 3. Integration Verification
+
+Run validation commands from the wish document:
+
+```
+For each execution group:
+  Run its validation command
+  Record: PASS or FAIL with output
+```
+
+### 4. Browser Tests (Optional)
+
+If the wish involves user-facing changes and agent-browser is available:
+
+```
+Use agent-browser to:
+  - Navigate to relevant pages
+  - Verify user-visible behavior
+  - Capture screenshots as evidence
+```
+
+**If agent-browser is not available:** Skip gracefully. Note in report: "Browser tests skipped - agent-browser not available."
+
+### 5. Verdict
+
+**SHIP** - All criteria pass. No CRITICAL or HIGH gaps.
+
+```
+Conditions:
+  - Zero CRITICAL gaps
+  - Zero HIGH gaps
+  - All validation commands pass
+  - 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
+  - Provide specific fix list for /genie:forge
+```
+
+**BLOCKED** - Fundamental issues. Return to wish.
+
+```
+Conditions:
+  - CRITICAL gaps that require scope changes
+  - Or architectural problems that can't be fixed in forge
+  - Provide specific issues requiring wish revision
+```
+
+### 6. Write Results
+
+Update the wish document with review results:
+
+```markdown
+## Review Results
+
+**Verdict:** SHIP | FIX-FIRST | BLOCKED
+**Date:** YYYY-MM-DD
+
+### Criteria Check
+- [x] Criterion 1 - PASS: [evidence]
+- [ ] Criterion 2 - FAIL (HIGH): [gap description]
+
+### Validation Commands
+- [x] `command 1` - PASS
+- [ ] `command 2` - FAIL: [output]
+
+### 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:** Work is done. Inform the user.
+
+**If FIX-FIRST:**
+```
+"Review found fixable issues. Run /genie:forge to address:
+1. [gap 1]
+2. [gap 2]
+Then run /genie: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 /genie:forge and /genie: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
+- Forget to write results back to the wish document

package/.claude/skills/genie-wish/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: "wish"
+description: "Use when starting any 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 an idea into a structured wish document through collaborative brainstorming, then create native Claude Code tasks for execution.
+
+**Output:** `.genie/wishes/<slug>/wish.md` + native tasks ready for `/forge`
+
+---
+
+## The Flow
+
+### Phase 1: Brainstorm (Explore Mode)
+
+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 structure:
+
+```markdown
+# Wish: <Title>
+
+**Status:** DRAFT
+**Slug:** `<slug>`
+
+---
+
+## Summary
+<2-3 sentences: what and why>
+
+## Scope
+### IN
+- <what we're doing>
+
+### OUT
+- <what we're not doing>
+
+## Decisions
+- **DEC-1:** <key decision with rationale>
+
+## Success Criteria
+- [ ] <overall criterion 1>
+- [ ] <overall criterion 2>
+
+## Execution Groups
+
+### Group A: <Name>
+**Goal:** <one sentence>
+
+**Deliverables:**
+- <concrete output>
+
+**Acceptance Criteria:**
+- [ ] <testable criterion>
+
+**Validation:** `<command to verify>`
+
+### Group B: <Name>
+...
+```
+
+### 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 `/wish-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")

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "namastexlabs",
+  "owner": {
+    "name": "Namastex Labs"
+  },
+  "metadata": {
+    "description": "Plugins by Namastex Labs",
+    "homepage": "https://github.com/namastexlabs/genie-cli"
+  },
+  "plugins": [
+    {
+      "name": "automagik-genie",
+      "version": "2026.02.02",
+      "source": "./plugin",
+      "description": "Human-AI partnership for Claude Code. Share a terminal, orchestrate workers, evolve together. Brainstorm ideas, wish them into plans, forge with parallel agents, ship as one team. A coding genie that grows with your project."
+    }
+  ]
+}

package/.genie/.gitkeep

@@ -0,0 +1,3 @@
+# .genie directory structure
+# wishes/ - Wish documents created by genie:wish skill
+# notes/ - Session notes and brainstorm artifacts

package/.genie/backlog/hooks-v2.md

@@ -0,0 +1,82 @@
+# Hooks v2 - Intelligent Session Awareness
+
+**Status:** Parked (removed 2026-02-02)
+**Why parked:** Scripts weren't being copied to plugin cache + bun dependency
+
+---
+
+## The Soul
+
+Hooks that make Genie *aware* of the session flow:
+- Know when a wish task is being written (validate structure live)
+- Know when Claude stops (did we actually complete what was asked?)
+- Know session context (what wish are we forging? what task?)
+
+## What We Had (v1 - broken)
+
+```json
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "matcher": { "tool_name": "Write", "file_path": ".genie/wishes/**/*.md" },
+      "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/validate-wish.ts --file \"$CLAUDE_FILE_PATH\"",
+      "timeout_ms": 5000,
+      "on_failure": "warn"
+    },
+    {
+      "event": "Stop",
+      "matcher": { "stop_reason": "end_turn" },
+      "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/validate-completion.ts --session \"$CLAUDE_SESSION_ID\"",
+      "timeout_ms": 10000,
+      "on_failure": "ignore"
+    }
+  ]
+}
+```
+
+## Problems
+1. `.ts` files not copied to plugin cache (only `smart-install.js` was)
+2. `bun` dependency - not always available
+3. Scripts need to be self-contained `.js` or `.cjs`
+
+## Ideas for v2
+
+### Wish Validation Hook
+- Validate wish.md structure before write
+- Check: scope section exists, acceptance criteria present, tasks defined
+- Output: warn if missing sections, suggest fixes
+- Could use prompt-based hook instead of script?
+
+### Completion Awareness Hook
+- On Stop: check if we're in a forge session
+- Did we complete the current task?
+- Should we mark task done? Move to next?
+- Auto-update task status in wish.md?
+
+### Session Context Hook
+- SessionStart: detect if we're resuming a wish/forge
+- Load context automatically
+- "Welcome back, you were working on wish X, task 3"
+
+### Prompt-Based Alternative
+Instead of scripts, use Claude's own judgment via prompt hooks:
+```json
+{
+  "event": "Stop",
+  "hooks": [{
+    "type": "prompt",
+    "prompt": "Check if the current task from .genie/active-wish was completed..."
+  }]
+}
+```
+
+## Questions to Brainstorm
+- What's the minimal viable hook that adds value?
+- Script vs prompt-based - which fits genie's soul better?
+- How to track "active wish" and "active task" across sessions?
+- Should hooks modify files or just inform?
+
+---
+
+*This is a parking lot for hook ideas. When ready, run /wish to plan implementation.*

package/.genie/wishes/upgrade-brainstorm-handoff/wish.md

@@ -0,0 +1,124 @@
+# Wish: Upgrade Brainstorm Skill with Handoff Output
+
+**Status:** DRAFT
+**Slug:** `upgrade-brainstorm-handoff`
+**Created:** 2026-02-02
+
+---
+
+## Summary
+
+Merge the best parts from local and plugin brainstorm skill versions, and add a structured handoff output to `.genie/brainstorms/<slug>/design.md` that provides the perfect input for `/wish` to begin execution planning.
+
+---
+
+## Scope
+
+### IN
+- Merge local `.claude/skills/brainstorm/` improvements into plugin
+- Add design.md output template as a reference file
+- Update SKILL.md to include handoff phase
+- Delete local duplicate after merge
+- Test the upgraded skill works
+
+### OUT
+- Changes to other skills (wish, forge, review)
+- New features beyond the handoff document
+- Changes to the wish template (wish reads brainstorm output, not the other way)
+
+---
+
+## Decisions
+
+- **DEC-1:** Output location is `.genie/brainstorms/<slug>/design.md` — keeps brainstorm artifacts separate from wishes
+- **DEC-2:** Handoff document uses markdown table format for decisions/risks — scannable and structured
+- **DEC-3:** Status field in design.md is `VALIDATED` — signals ready for /wish consumption
+
+---
+
+## Success Criteria
+
+- [ ] Plugin brainstorm skill includes all best practices from both versions
+- [ ] Running `/brainstorm` produces `.genie/brainstorms/<slug>/design.md` on completion
+- [ ] Design.md format includes: Problem, Solution, Scope IN/OUT, Decisions, Risks, Success definition
+- [ ] Local `.claude/skills/brainstorm/` is deleted
+- [ ] No duplicate brainstorm skills exist
+
+---
+
+## Assumptions
+
+- **ASM-1:** The plugin can be updated and reinstalled locally for testing
+- **ASM-2:** The design.md template is sufficient for /wish to begin planning
+
+## Risks
+
+- **RISK-1:** Breaking existing brainstorm behavior — Mitigation: Test with a real brainstorm session before deleting local
+
+---
+
+## Execution Groups
+
+### Group A: Create Design Template Reference
+
+**Goal:** Add the design.md template as a reference file in the plugin.
+
+**Deliverables:**
+- `plugin/references/design-template.md` with the agreed format
+
+**Acceptance Criteria:**
+- [ ] Template file exists at `plugin/references/design-template.md`
+- [ ] Template includes all agreed sections (Problem, Solution, Scope, Design, Constraints, Success)
+
+**Validation:** `cat plugin/references/design-template.md | head -30`
+
+---
+
+### Group B: Upgrade Brainstorm SKILL.md
+
+**Goal:** Merge best practices and add handoff phase to the brainstorm skill.
+
+**Deliverables:**
+- Updated `plugin/skills/brainstorm/SKILL.md` with:
+  - Merged content from both versions
+  - New Phase 6: Write Handoff Document
+  - Reference to design-template.md
+
+**Acceptance Criteria:**
+- [ ] SKILL.md includes all 6 phases
+- [ ] Phase 6 writes to `.genie/brainstorms/<slug>/design.md`
+- [ ] References the design-template.md for format
+- [ ] Includes "Never Do" guardrails
+
+**Validation:** `grep -c "Phase\|design-template\|\.genie/brainstorms" plugin/skills/brainstorm/SKILL.md`
+
+---
+
+### Group C: Delete Local Duplicate
+
+**Goal:** Remove the local `.claude/skills/brainstorm/` now that plugin is upgraded.
+
+**Deliverables:**
+- Delete `.claude/skills/brainstorm/` directory
+
+**Acceptance Criteria:**
+- [ ] `.claude/skills/brainstorm/` no longer exists
+- [ ] No errors when running `/brainstorm` (uses plugin version)
+
+**Validation:** `ls .claude/skills/brainstorm 2>&1 | grep -c "No such file"`
+
+---
+
+## Review Results
+
+_Populated by `/review` after forge execution completes._
+
+---
+
+## Files to Create/Modify
+
+```
+plugin/references/design-template.md (CREATE)
+plugin/skills/brainstorm/SKILL.md (MODIFY)
+.claude/skills/brainstorm/ (DELETE)
+```

package/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.genie/issues.jsonl merge=beads

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>         # Complete work
+bd sync               # Sync with git
+```
+
+## Co-Orchestration Mode
+
+When working as a **spawned worker** via `term work`, you are part of a multi-agent system:
+
+1. **You are bound to a specific issue** - Focus ONLY on that task
+2. **Your state is tracked** - The orchestrator sees your status (working/idle/permission/etc.)
+3. **You work in an isolated worktree** - Your changes don't affect other workers
+4. **Beads syncs automatically** - The daemon handles commits
+
+### CLI Improvement Rule (CRITICAL)
+
+**DO NOT implement CLI improvements directly.** When you identify an opportunity to improve genie-cli:
+
+1. Create an issue: `bd create "CLI: <improvement>" --label cli-improvement`
+2. Continue with your assigned task
+3. A dedicated `genie-cli-improver` worker will handle CLI changes
+
+This ensures:
+- Your current task stays focused
+- CLI changes are isolated and reviewable
+- No scope creep in your work
+
+### Worker Lifecycle
+
+```
+term work bd-X  →  You start  →  Work on task  →  Signal completion  →  term close bd-X
+```
+
+When done with your task:
+1. Commit your changes
+2. Inform the orchestrator you're done (just say "Done" or similar)
+3. The orchestrator will run `term close bd-X` to clean up
+
+See `docs/CO-ORCHESTRATION-GUIDE.md` for the full orchestration workflow.
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+