@automagik/genie 3.260314.8 → 3.260314.10

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "genie",
-      "version": "3.260314.8",
+      "version": "3.260314.10",
       "source": "./plugins/genie",
       "description": "Human-AI partnership for Claude Code. Share a terminal, orchestrate workers, evolve together. Brainstorm ideas, wish them into plans, make with parallel agents, ship as one team. A coding genie that grows with your project."
     }

package/install.sh

@@ -664,69 +664,110 @@ inject_orchestration_prompt() {
 
 You are a team-lead in a **genie-managed environment**. ALL agent spawning, messaging, and team management MUST go through the genie CLI via Bash.
 
-## CRITICAL: NEVER Use These Native Tools
+## 1. CRITICAL: NEVER Use These Native Tools
 
-NEVER use the `Agent` tool to spawn agents or subagents. Use `genie agent spawn` instead.
+NEVER use the `Agent` tool to spawn agents or subagents. Use `genie spawn` instead.
 NEVER use `SendMessage` to communicate with agents. Use `genie send` instead.
-NEVER use `TeamCreate` or `TeamDelete`. Use `genie team ensure` / `genie team delete` instead.
+NEVER use `TeamCreate` or `TeamDelete`. Use `genie team create` / `genie team disband` instead.
 
 If you catch yourself about to use Agent, SendMessage, TeamCreate, or TeamDelete — STOP and use the genie CLI equivalent below.
 
-## Agents
+## 2. CLI Commands Reference
+
+### Agent Lifecycle
 
 ```bash
-# Spawn an agent (ALWAYS use this instead of Agent tool)
-genie agent spawn --role <role>                    # implementor, tests, review, fix, refactor
-genie agent spawn --role <role> --skill <skill>    # With specific skill
-
-# Monitor
-genie agent list                           # List all agents
-genie agent dashboard                      # Live dashboard
-genie agent history <agent>                # Session history
-genie agent read <agent> --follow          # Tail terminal output
-
-# Control
-genie agent kill <id>                      # Force kill
-genie agent suspend <id>                   # Suspend (preserves session)
-genie agent exec <agent> '<cmd>'           # Run command in agent pane
-genie agent answer <agent> <choice>        # Answer prompt (1-9 or text:...)
+genie spawn <role>                         # Spawn agent (implementor, tests, review, fix, refactor)
+genie kill <name>                          # Force kill agent
+genie stop <name>                          # Graceful stop
+genie ls                                   # List all agents
+genie history <name>                       # Session history
+genie read <name> --follow                 # Tail terminal output
+genie answer <name> <choice>               # Answer prompt (1-9 or text:...)
 ```
 
-## Messaging
+### Messaging
 
 ```bash
-# Send message to an agent (ALWAYS use this instead of SendMessage)
-genie send '<text>' --to <agent>            # Send to specific agent
-genie inbox <agent>                         # View agent inbox
-genie inbox <agent> --unread                # Unread only
+genie send '<text>' --to <agent>           # Send message to agent
+genie broadcast '<text>'                   # Broadcast to all agents
+genie chat [args...]                       # Interactive chat with agent
+genie inbox [agent]                        # View message inbox
 ```
 
-## Teams
+### Teams
 
 ```bash
-genie team ensure <name>                    # Ensure team exists (creates if needed)
-genie team list                             # List teams
-genie team delete <name>                    # Delete team
+genie team create <name> --repo <path>     # Create a team
+genie team hire <agent>                    # Add agent to team
+genie team fire <agent>                    # Remove agent from team
+genie team ls [name]                       # List teams or team members
+genie team disband <name>                  # Disband and clean up team
 ```
 
-## Typical Flow
+### Dispatch (Skill-Bound Work)
 
 ```bash
-# 1. Spawn an agent
-genie agent spawn --role implementor
+genie work <agent> <ref>                   # Dispatch worker bound to wish group
+genie brainstorm <agent> <slug>            # Dispatch brainstorm on topic
+genie wish <agent> <slug>                  # Dispatch wish planning
+genie review <agent> <ref>                 # Dispatch review
+```
+
+### State Management
 
-# 2. Monitor
-genie agent list
+```bash
+genie done <ref>                           # Mark group/task done
+genie status <slug>                        # Check wish/group status
+genie reset <ref>                          # Reset stuck group
+```
 
-# 3. Send instructions
-genie send 'Implement endpoint X' --to <agent-name>
+## 3. Skill Flow — Auto-Invocation Chain
 
-# 4. Check progress
-genie agent history <agent-name>
+Skills trigger the next step automatically where possible:
 
-# 5. Shut down
-genie agent kill <agent-id>
 ```
+/brainstorm ──(WRS=100)──▸ /review (plan)
+      │                        │
+      │                   SHIP ▸ /wish
+      │                        │
+      │                   /wish ──▸ /review (plan)
+      │                              │
+      │                         SHIP ▸ /work
+      │                              │
+      │                    /work (per group) ──▸ /review (execution)
+      │                                             │
+      │                          SHIP ▸ PR     FIX-FIRST ▸ /fix ──▸ /review
+      │                                              │
+      │                                   unclear root cause ▸ /trace
+      │
+      ▾
+  Decisions stuck after 2+ exchanges ──▸ suggest /council
+```
+
+## 4. Team Lifecycle
+
+```
+create team ──▸ hire agents ──▸ dispatch work ──▸ review ──▸ PR to dev ──▸ QA ──▸ disband
+```
+
+1. `genie team create <name> --repo <path>` — create team for the initiative
+2. `genie team hire <agent>` — add agents with needed roles
+3. `genie work <agent> <ref>` — dispatch groups to workers
+4. Monitor via `genie status <slug>`, mark done via `genie done <ref>`
+5. Workers signal completion via `genie send`; leader runs `/review`
+6. Create PR targeting `dev`. CI must be green before merge.
+7. QA loop on dev: test against wish criteria → `/fix` → retest
+8. `genie team disband <name>` — clean up when done
+
+## 5. Rules
+
+- **No native tools.** All agent/team/messaging operations go through `genie` CLI.
+- **Role separation.** Leader orchestrates; workers implement. Workers never spawn other agents.
+- **Critical: PR review.** Every PR gets `/review` before merge. Auto-invoke `/fix` on FIX-FIRST.
+- **CI green before merge.** Never merge with failing checks. Poll CI status, don't sleep.
+- **Agents merge to dev, not main.** PRs always target `dev`. Only humans merge `dev` → `main`.
+- **Signal, don't poll.** Workers use `genie send` to report completion. Leader uses `genie done` to track state.
 </GENIE_CLI>
 ORCHESTRATION_EOF
 

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": "3.260314.8",
+  "version": "3.260314.10",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/genie",
-  "version": "3.260314.8",
+  "version": "3.260314.10",
   "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": "3.260314.8",
+  "version": "3.260314.10",
   "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": "3.260314.8",
+  "version": "3.260314.10",
   "private": true,
   "description": "Runtime dependencies for genie bundled CLIs",
   "type": "module",

package/plugins/genie/scripts/smart-install.js

@@ -245,69 +245,110 @@ const ORCHESTRATION_PROMPT = `<GENIE_CLI>
 
 You are a team-lead in a **genie-managed environment**. ALL agent spawning, messaging, and team management MUST go through the genie CLI via Bash.
 
-## CRITICAL: NEVER Use These Native Tools
+## 1. CRITICAL: NEVER Use These Native Tools
 
-NEVER use the \`Agent\` tool to spawn agents or subagents. Use \`genie agent spawn\` instead.
+NEVER use the \`Agent\` tool to spawn agents or subagents. Use \`genie spawn\` instead.
 NEVER use \`SendMessage\` to communicate with agents. Use \`genie send\` instead.
-NEVER use \`TeamCreate\` or \`TeamDelete\`. Use \`genie team ensure\` / \`genie team delete\` instead.
+NEVER use \`TeamCreate\` or \`TeamDelete\`. Use \`genie team create\` / \`genie team disband\` instead.
 
 If you catch yourself about to use Agent, SendMessage, TeamCreate, or TeamDelete — STOP and use the genie CLI equivalent below.
 
-## Agents
+## 2. CLI Commands Reference
+
+### Agent Lifecycle
 
 \`\`\`bash
-# Spawn an agent (ALWAYS use this instead of Agent tool)
-genie agent spawn --role <role>                    # implementor, tests, review, fix, refactor
-genie agent spawn --role <role> --skill <skill>    # With specific skill
-
-# Monitor
-genie agent list                           # List all agents
-genie agent dashboard                      # Live dashboard
-genie agent history <agent>                # Session history
-genie agent read <agent> --follow          # Tail terminal output
-
-# Control
-genie agent kill <id>                      # Force kill
-genie agent suspend <id>                   # Suspend (preserves session)
-genie agent exec <agent> '<cmd>'           # Run command in agent pane
-genie agent answer <agent> <choice>        # Answer prompt (1-9 or text:...)
+genie spawn <role>                         # Spawn agent (implementor, tests, review, fix, refactor)
+genie kill <name>                          # Force kill agent
+genie stop <name>                          # Graceful stop
+genie ls                                   # List all agents
+genie history <name>                       # Session history
+genie read <name> --follow                 # Tail terminal output
+genie answer <name> <choice>               # Answer prompt (1-9 or text:...)
 \`\`\`
 
-## Messaging
+### Messaging
 
 \`\`\`bash
-# Send message to an agent (ALWAYS use this instead of SendMessage)
-genie send '<text>' --to <agent>            # Send to specific agent
-genie inbox <agent>                         # View agent inbox
-genie inbox <agent> --unread                # Unread only
+genie send '<text>' --to <agent>           # Send message to agent
+genie broadcast '<text>'                   # Broadcast to all agents
+genie chat [args...]                       # Interactive chat with agent
+genie inbox [agent]                        # View message inbox
 \`\`\`
 
-## Teams
+### Teams
 
 \`\`\`bash
-genie team ensure <name>                    # Ensure team exists (creates if needed)
-genie team list                             # List teams
-genie team delete <name>                    # Delete team
+genie team create <name> --repo <path>     # Create a team
+genie team hire <agent>                    # Add agent to team
+genie team fire <agent>                    # Remove agent from team
+genie team ls [name]                       # List teams or team members
+genie team disband <name>                  # Disband and clean up team
 \`\`\`
 
-## Typical Flow
+### Dispatch (Skill-Bound Work)
 
 \`\`\`bash
-# 1. Spawn an agent
-genie agent spawn --role implementor
+genie work <agent> <ref>                   # Dispatch worker bound to wish group
+genie brainstorm <agent> <slug>            # Dispatch brainstorm on topic
+genie wish <agent> <slug>                  # Dispatch wish planning
+genie review <agent> <ref>                 # Dispatch review
+\`\`\`
+
+### State Management
 
-# 2. Monitor
-genie agent list
+\`\`\`bash
+genie done <ref>                           # Mark group/task done
+genie status <slug>                        # Check wish/group status
+genie reset <ref>                          # Reset stuck group
+\`\`\`
 
-# 3. Send instructions
-genie send 'Implement endpoint X' --to <agent-name>
+## 3. Skill Flow — Auto-Invocation Chain
 
-# 4. Check progress
-genie agent history <agent-name>
+Skills trigger the next step automatically where possible:
 
-# 5. Shut down
-genie agent kill <agent-id>
 \`\`\`
+/brainstorm ──(WRS=100)──▸ /review (plan)
+      │                        │
+      │                   SHIP ▸ /wish
+      │                        │
+      │                   /wish ──▸ /review (plan)
+      │                              │
+      │                         SHIP ▸ /work
+      │                              │
+      │                    /work (per group) ──▸ /review (execution)
+      │                                             │
+      │                          SHIP ▸ PR     FIX-FIRST ▸ /fix ──▸ /review
+      │                                              │
+      │                                   unclear root cause ▸ /trace
+      │
+      ▾
+  Decisions stuck after 2+ exchanges ──▸ suggest /council
+\`\`\`
+
+## 4. Team Lifecycle
+
+\`\`\`
+create team ──▸ hire agents ──▸ dispatch work ──▸ review ──▸ PR to dev ──▸ QA ──▸ disband
+\`\`\`
+
+1. \`genie team create <name> --repo <path>\` — create team for the initiative
+2. \`genie team hire <agent>\` — add agents with needed roles
+3. \`genie work <agent> <ref>\` — dispatch groups to workers
+4. Monitor via \`genie status <slug>\`, mark done via \`genie done <ref>\`
+5. Workers signal completion via \`genie send\`; leader runs \`/review\`
+6. Create PR targeting \`dev\`. CI must be green before merge.
+7. QA loop on dev: test against wish criteria → \`/fix\` → retest
+8. \`genie team disband <name>\` — clean up when done
+
+## 5. Rules
+
+- **No native tools.** All agent/team/messaging operations go through \`genie\` CLI.
+- **Role separation.** Leader orchestrates; workers implement. Workers never spawn other agents.
+- **Critical: PR review.** Every PR gets \`/review\` before merge. Auto-invoke \`/fix\` on FIX-FIRST.
+- **CI green before merge.** Never merge with failing checks. Poll CI status, don't sleep.
+- **Agents merge to dev, not main.** PRs always target \`dev\`. Only humans merge \`dev\` → \`main\`.
+- **Signal, don't poll.** Workers use \`genie send\` to report completion. Leader uses \`genie done\` to track state.
 </GENIE_CLI>
 `;
 
@@ -454,7 +495,7 @@ try {
   if (!isTmuxInstalled()) {
     console.error('');
     console.error('WARNING: tmux is not installed.');
-    console.error('tmux is required for agent orchestration (genie agent spawn, teams, etc.).');
+    console.error('tmux is required for agent orchestration (genie spawn, teams, etc.).');
     console.error('Non-interactive features still work without it.');
     console.error('');
     console.error('Install tmux:');

package/skills/brain/SKILL.md

@@ -7,6 +7,20 @@ description: "Obsidian-style knowledge vault — store, search, and retrieve age
 
 Persistent long-term memory for agents. Knowledge is stored in `brain/`, searched before answering, and written back every session.
 
+## Brain vs Memory
+
+These are **different tools for different purposes**:
+
+| | **Brain** (this skill) | **Memory** (Claude native) |
+|---|---|---|
+| **What** | Context graph — entities, relationships, domain knowledge | Behavioral learnings — feedback, decisions, user preferences |
+| **Tool** | `notesmd-cli` (Obsidian-style vault) | `.claude/memory/` files with YAML frontmatter |
+| **When** | Domain intel, playbooks, company/person context, session logs | Corrections, conventions, project rules, user profile |
+| **Updated by** | `/brain` (this skill) | `/learn` skill, auto memory system |
+| **Format** | Markdown notes in `brain/` directory | Typed memory files (user, feedback, project, reference) |
+
+**Rule of thumb:** If it's *knowledge about the world* → brain. If it's *how the agent should behave* → memory.
+
 ## When to Use
 - Agent needs to recall prior session context, decisions, or intel
 - New intel (person, company, deal) is discovered mid-session
@@ -59,18 +73,36 @@ notesmd-cli print "Playbooks/<playbook-name>"
 | `notesmd-cli list` | Browse full vault structure |
 | `notesmd-cli set-default --vault <path>` | Configure vault path (one-time setup) |
 
-## Installation
+## Installation (Auto-Detect)
+
+On first use, check if `notesmd-cli` is available:
 
 ```bash
-# Automated (recommended)
-bash skills/brain/scripts/install-notesmd.sh --vault ./brain
+command -v notesmd-cli >/dev/null 2>&1 && echo "installed" || echo "missing"
+```
+
+**If missing**, offer to install from https://github.com/Yakitrak/notesmd-cli:
 
-# Manual
+```bash
+# macOS (Homebrew)
 brew install yakitrak/yakitrak/notesmd-cli
+
+# Linux / manual
+# Download the latest release binary from:
+# https://github.com/Yakitrak/notesmd-cli/releases
+# Place in /usr/local/bin/notesmd-cli and chmod +x
+
+# Or use the bundled install script (if available)
+bash skills/brain/scripts/install-notesmd.sh --vault ./brain
+```
+
+After install, configure the vault:
+
+```bash
 notesmd-cli set-default --vault ./brain/
 ```
 
-If Homebrew is unavailable: download from https://github.com/Yakitrak/notesmd-cli/releases and place in `/usr/local/bin/notesmd-cli`.
+If the user declines installation, skip brain operations gracefully and note that `/brain` requires `notesmd-cli`.
 
 ## Provisioning a New Agent Brain
 

package/skills/brainstorm/SKILL.md

@@ -76,26 +76,78 @@ Brainstorm index at `.genie/brainstorm.md`. Tracks all topics across sessions.
 
 Triggered automatically when WRS = 100.
 
-1. Write `.genie/brainstorms/<slug>/DESIGN.md` from `DRAFT.md` (use `references/design-template.md`).
+1. Write `.genie/brainstorms/<slug>/DESIGN.md` from `DRAFT.md` using the Design Template below.
 2. Update `.genie/brainstorm.md` — move item to Poured with wish link.
-3. Run `genie brainstorm crystallize`.
+3. Auto-invoke `/review` (plan review) on the `DESIGN.md`.
 
 ## Output Options
 
 | Complexity | Output |
 |-----------|--------|
-| Standard | Write `DESIGN.md`, hand off to `/wish` |
+| Standard | Write `DESIGN.md`, auto-invoke `/review` (plan review) |
 | Small but non-trivial | Write design, ask whether to implement directly |
-| Trivial | Verbal validation only — no file needed |
+| Trivial | Add one-liner to jar (Raw section), no file needed |
 
 ## Handoff
 
+After `/review` returns SHIP on the design:
+
 ```
-Design validated (WRS {score}/100). Run /wish to turn this into an executable plan.
+Design reviewed and validated (WRS {score}/100). Proceeding to /wish.
 ```
 
 Note any cross-repo or cross-agent dependencies — these become `depends-on`/`blocks` fields in the wish.
 
+## Stuck Decisions
+
+If the **Decisions** dimension stays ░ (unfilled) after 2+ exchanges, suggest:
+
+```
+Decisions seem stuck. Consider running /council to get specialist perspectives on the tradeoffs.
+```
+
+## Design Template
+
+Use this structure when writing `DESIGN.md` at crystallize:
+
+```markdown
+# Design: <Title>
+
+| Field | Value |
+|-------|-------|
+| **Slug** | `<slug>` |
+| **Date** | YYYY-MM-DD |
+| **WRS** | 100/100 |
+
+## Problem
+One-sentence problem statement.
+
+## Scope
+### IN
+- Concrete deliverable 1
+- Concrete deliverable 2
+
+### OUT
+- Explicit exclusion 1
+
+## Approach
+Chosen approach with rationale. Reference alternatives considered.
+
+## Decisions
+| Decision | Rationale |
+|----------|-----------|
+| Choice 1 | Why this over alternatives |
+
+## Risks & Assumptions
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| Risk 1 | Low/Medium/High | How to handle |
+
+## Success Criteria
+- [ ] Testable criterion 1
+- [ ] Testable criterion 2
+```
+
 ## Rules
 - One question per message. Never batch questions.
 - YAGNI and simplicity first.

package/skills/council/SKILL.md

@@ -14,6 +14,12 @@ Convene a panel of 10 specialist perspectives to brainstorm, critique, and vote
 - During `/review` to surface risks and blind spots
 - Deadlocked discussions needing fresh angles
 
+### Auto-Invocation Triggers
+
+The council can be triggered automatically by other skills:
+- **During `/review`**: when an architecture decision has significant tradeoffs, `/review` may invoke `/council` to get specialist input before rendering a verdict.
+- **During `/brainstorm`**: when the Decisions dimension stays unfilled (░) after 2+ exchanges, `/brainstorm` suggests running `/council` to break the deadlock.
+
 ## Mode Detection
 
 Before running the council flow, detect which mode to use:
@@ -24,7 +30,7 @@ Before running the council flow, detect which mode to use:
 
 ## Lightweight Mode (Default)
 
-When no council members are hired in the team, simulate all perspectives in a single session.
+When no council members are hired in the team, simulate all perspectives in a single session. One agent plays all roles — faster, lower cost, good for most decisions.
 
 ### Flow
 
@@ -37,7 +43,17 @@ When no council members are hired in the team, simulate all perspectives in a si
 
 ## Full Spawn Mode
 
-When council members are hired in the team, use the team chat channel for real multi-agent deliberation.
+When council members are hired in the team, real agents deliberate via `genie chat` and reach consensus. Higher-quality than lightweight mode since each member runs in its own context with its own reasoning.
+
+### Setup
+
+Hire council members into the team before invoking:
+
+```bash
+genie team hire council
+```
+
+This adds specialist agents (e.g., `council-questioner`, `council-architect`) to the current team.
 
 ### Flow
 
@@ -54,17 +70,18 @@ When council members are hired in the team, use the team chat channel for real m
    ```bash
    genie chat read --team <team> --since <topic-post-timestamp>
    ```
-5. Once all consulted members have responded (or after a reasonable wait), the leader synthesizes:
+5. **Timeout:** if a council member hasn't responded within 2 minutes, proceed with "no response" in the tally. Do not block indefinitely.
+6. Once all consulted members have responded (or timeout reached), the leader synthesizes:
    - Collect all perspectives from team chat
    - Tally votes
    - Produce the synthesized recommendation
-6. Present the advisory to the user using the same output format
+7. Present the advisory to the user using the same output format
 
 ### Notes on Full Spawn Mode
 
 - Council members respond independently — each applies their own lens prompt
 - The leader (session running `/council`) acts as moderator and synthesizer
-- If a council member hasn't responded, note them as "no response" in the tally
+- If a council member hasn't responded after timeout, note them as "no response" in the tally
 - Full spawn mode produces higher-quality reviews since each member runs in its own context
 
 ## Council Members

package/skills/docs/SKILL.md

@@ -12,10 +12,25 @@ Audit existing documentation, identify gaps, generate what's missing, and valida
 - Existing documentation is stale or references removed features
 - A wish deliverable includes documentation
 - After significant code changes that invalidate existing docs
+- After `/work` completes — suggest `/docs` to document what changed
+
+## Documentation Surfaces
+
+Audit and maintain these doc types:
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| **README** | `README.md`, `*/README.md` | Project/module overview, setup, usage |
+| **CLAUDE.md** | `CLAUDE.md`, `*/CLAUDE.md` | Project conventions, commands, gotchas for AI agents |
+| **API docs** | `docs/api/`, inline JSDoc/TSDoc | Endpoint contracts, request/response schemas |
+| **Architecture** | `docs/architecture.md`, `ARCHITECTURE.md` | System design, data flow, component relationships |
+| **Inline docs** | JSDoc, TSDoc, docstrings | Function/class/module-level documentation |
+
+**CLAUDE.md is a first-class documentation surface.** When the codebase changes significantly (new commands, changed conventions, removed features), flag CLAUDE.md for update. CLAUDE.md should always reflect the current state of the project.
 
 ## Flow
-1. **Audit existing docs:** scan for READMEs, guides, inline docs, changelogs — map what exists.
-2. **Identify gaps:** compare documentation against actual code — find what's missing, outdated, or wrong.
+1. **Audit existing docs:** scan all documentation surfaces above — map what exists.
+2. **Identify gaps:** compare documentation against actual code — find what's missing, outdated, or wrong. Pay special attention to CLAUDE.md accuracy.
 3. **Generate:** write documentation to fill the gaps, matching project conventions.
 4. **Validate against code:** verify every claim — file paths exist, APIs match, behaviors are accurate.
 5. **Report:** return list of created/updated files with validation results.