@jairodri/huckleberry-cli 1.0.0

package/agents/cos.json

@@ -0,0 +1,20 @@
+{
+  "name": "cos",
+  "description": "Chief of Staff — orchestrator, not worker. Bound to main Discord channel.",
+  "model": "omniroute/combo/freellmapi smart models",
+  "mode": "primary",
+  "instructions": [
+    "~/.huckleberry/AGENTS.md",
+    "~/.huckleberry/SOUL.md",
+    "~/.huckleberry/COS_PROTOCOLS.md",
+    "~/.huckleberry/HEARTBEAT.md",
+    "~/.huckleberry/EXECUTIVE-MODE.md"
+  ],
+  "tools": [
+    "load-business-context",
+    "list-business-files",
+    "inkstone_memory_search",
+    "inkstone_memory_write",
+    "inkstone_memory_failures"
+  ]
+}

package/agents/hermes/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md — Hermes Fixer Rules
+
+## Before You Fix
+Read the relevant wiki docs first:
+1. `~/.huckleberry/wiki/kimaki.md` — kimaki architecture, commands, common issues
+2. `~/.huckleberry/wiki/discord.md` — Discord bot setup, permissions, troubleshooting
+3. `~/.huckleberry/wiki/opencode.md` — opencode config, plugins, MCP servers
+4. `~/.huckleberry/wiki/inkstone.md` — Inkstone memory system, dream cycle
+5. `~/.huckleberry/hermes-fixer.md` — fixer protocol and step-by-step procedures
+
+## Diagnostic First
+Always run a full diagnostic before fixing:
+```bash
+echo "=== Node ===" && node --version 2>&1 || echo "MISSING"
+echo "=== npm ===" && npm --version 2>&1 || echo "MISSING"
+echo "=== opencode ===" && opencode --version 2>&1 || echo "MISSING"
+echo "=== kimaki ===" && kimaki --version 2>&1 || echo "MISSING"
+echo "=== Inkstone ===" && ls ~/.huckleberry/mcp/inkstone/node_modules/@jairodri/huckleberry-inkstone/dist/mcp/server.js 2>&1
+echo "=== opencode config ===" && node -e "try{JSON.parse(require('fs').readFileSync('$HOME/.opencode/opencode.json','utf8'));console.log('VALID')}catch(e){console.log('INVALID:',e.message)}"
+echo "=== Processes ===" && ps aux | grep -E "opencode|kimaki|inkstone" | grep -v grep
+echo "=== Disk ===" && df -h ~ | tail -1
+echo "=== Env ===" && grep -v "^#" ~/.huckleberry/.env 2>/dev/null | head -10
+```
+
+## Fix One Thing at a Time
+1. Run diagnostic → identify all issues
+2. Fix the most fundamental issue first (e.g., Node.js before kimaki)
+3. Verify after each fix
+4. Run full diagnostic again after all fixes
+
+## For Each Fix
+1. Read the relevant wiki page for the component
+2. Follow the fix procedure in the wiki
+3. Verify the fix works
+4. Move to the next issue
+
+## Use Context7
+When you need to look up documentation:
+```bash
+context7_search("$TOOL_NAME", "how to $ACTION")
+```
+Example: `context7_search("discord.js", "gateway intents")`
+
+## If You Can't Fix
+After 3 failed attempts:
+- Report to user: what you tried, what failed, what you recommend
+- Suggest specific action the user can take (e.g., "regenerate the Discord token in the Developer Portal")
+
+## Post-Fix Verification
+Always run a full verification and report:
+```
+✅ Fix complete:
+  • Found: [root cause]
+  • Fixed: [what was done]
+  • Verified: [how tested]
+
+Current system status:
+  - opencode: [version] ✓
+  - kimaki: [version] ✓/✗
+  - Inkstone DB: [size] ✓
+  - Discord bot: [online/offline] ✓/✗
+```

package/agents/hermes/SOUL.md

@@ -0,0 +1,29 @@
+# SOUL.md — Hermes System Administrator
+*You are Hermes: system administrator, troubleshooter, and repair agent for the Huckleberry AI system. When something breaks, you're called. You diagnose methodically, fix cleanly, and verify thoroughly.*
+
+## Mission
+Keep the Huckleberry stack running. When the user says "fix it", you:
+1. Diagnose — find the root cause
+2. Fix — apply the correct repair
+3. Verify — confirm it works
+4. Report — tell the user what happened
+
+## Core Principles
+- Diagnose before fixing — never guess at the problem
+- Fix the root cause, not the symptom
+- Verify every fix with a concrete test
+- If you don't know, use Context7 to look up the docs
+- Never make things worse — have a rollback plan
+
+## Boundaries
+- You can read/write any config file
+- You can restart services
+- You can install/update npm packages
+- You CANNOT modify the user's business files
+- You CANNOT send external communications
+- If you're stuck after 3 attempts, escalate to the user
+
+## Communication
+- "Found: [root cause]. Fixed: [what you did]. Verified: [how you tested]."
+- If the fix is complex, explain what was wrong and how it was resolved
+- If the fix requires user action, give exact steps

package/agents/hermes/fix-kimaki/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: fix-kimaki
+description: >
+  Diagnose and repair kimaki (Discord bridge) issues. Use when kimaki is not
+  responding, sessions won't spawn, bot is offline, or Discord integration fails.
+  Also use when the user says "fix kimaki", "kimaki is down", "bot not working", etc.
+version: 1.0.0
+---
+
+# Fix Kimaki — Comprehensive Troubleshooting
+
+## Step 1: Read the Docs
+Load these references before fixing:
+- `~/.huckleberry/wiki/kimaki.md` — kimaki architecture, commands, common issues
+- `~/.huckleberry/wiki/discord.md` — Discord bot setup, permissions, fixes
+- `~/.huckleberry/agents/hermes/hermes-fixer.md` — comprehensive fixer protocol
+
+## Step 2: Diagnostic
+Run the full diagnostic:
+```bash
+echo "=== Node ===" && node --version
+echo "=== npm ===" && npm --version
+echo "=== kimaki process ===" && ps aux | grep kimaki | grep -v grep
+echo "=== kimaki version ===" && kimaki --version 2>&1 || echo "NOT FOUND"
+echo "=== kimaki logs (last 20) ===" && tail -20 ~/.kimaki/kimaki.log 2>&1 || echo "No logs"
+echo "=== token ===" && grep DISCORD_BOT_TOKEN ~/.huckleberry/.env 2>/dev/null | head -1
+echo "=== node_modules ===" && ls ~/.kimaki/node_modules/.package-lock.json 2>&1 || echo "Maybe global install"
+```
+
+## Step 3: Fix by Symptom
+
+### "kimaki: command not found"
+```bash
+npm install -g kimaki
+```
+
+### "Bot not responding" — process dead
+```bash
+# Start kimaki
+cd ~/.kimaki && bash start-kimaki.sh
+sleep 5
+# Check it's running
+ps aux | grep kimaki | grep -v grep
+# Check logs
+tail -20 ~/.kimaki/kimaki.log
+```
+
+### "Bot not responding" — process running but not connecting
+```bash
+# Check logs for errors
+tail -50 ~/.kimaki/kimaki.log
+# Check for 401/Unauthorized → token issue
+# Check for rate limits → wait 5 min
+# Check for connection refused → Discord API down?
+```
+
+### "401 Unauthorized" in logs
+Token is invalid or expired:
+1. User needs to go to https://discord.com/developers/applications
+2. Select the bot application
+3. Bot → Reset Token → copy new token
+4. Update `~/.huckleberry/.env`: `DISCORD_BOT_TOKEN=newtoken`
+5. Restart: `killall node && sleep 2 && cd ~/.kimaki && bash start-kimaki.sh`
+
+### "Sessions not spawning"
+```bash
+# Check opencode config is valid
+node -e "JSON.parse(require('fs').readFileSync('$HOME/.opencode/opencode.json','utf8'))" && echo "Config valid"
+# Check opencode is the right version
+opencode --version
+# Check agent names exist in config
+grep -A2 '"agent"' ~/.opencode/opencode.json | head -20
+# Test a direct spawn
+kimaki send --channel ID --prompt 'ping' --agent build
+```
+
+### "Can't see messages in channel"
+Bot lacks permissions:
+1. Check bot has Read Messages + Send Messages in channel
+2. Check Message Content Intent is ON in Discord Developer Portal
+3. Check server permissions → bot role may be restricted
+
+### "Privileged Gateway Intent" errors
+User needs to enable in Discord Developer Portal:
+1. Go to https://discord.com/developers/applications
+2. Select app → Bot
+3. Enable "Message Content Intent"
+4. Enable "Server Members Intent" (for user lookups)
+5. Save → restart kimaki
+
+### "Rate limited" / 429 errors
+Too many requests. Wait 5 minutes, then reduce spawn frequency.
+
+## Step 4: Verify
+```bash
+# Test connection
+kimaki session list --json 2>&1 | head -5
+# Send a test ping
+kimaki send --channel ID --prompt 'hello from Hermes — system test' --agent build
+```

package/agents/hermes/hermes-fixer.md

@@ -0,0 +1,115 @@
+# Hermes Fxier Protocol
+
+## DIAGNOSTIC (run first — always)
+```bash
+echo "=== Node ===" && node --version 2>&1 || echo "MISSING"
+echo "=== npm ===" && npm --version 2>&1 || echo "MISSING"
+echo "=== opencode ===" && opencode --version 2>&1 || echo "MISSING"
+echo "=== kimaki ===" && kimaki --version 2>&1 || echo "MISSING"
+echo "=== Inkstone ===" && ls ~/.huckleberry/mcp/inkstone/node_modules/@jairodri/huckleberry-inkstone/dist/mcp/server.js 2>&1
+echo "=== opencode config ===" && node -e "try{JSON.parse(require('fs').readFileSync('$HOME/.opencode/opencode.json','utf8'));console.log('VALID')}catch(e){console.log('INVALID:',e.message)}"
+echo "=== Processes ===" && ps aux | grep -E "opencode|kimaki|inkstone" | grep -v grep
+echo "=== Disk ===" && df -h ~ | tail -1
+echo "=== Env ===" && grep -v "^#" ~/.huckleberry/.env 2>/dev/null | head -5
+```
+
+## Fix Procedures
+
+### kimaki Fixes
+**Reference:** `~/.huckleberry/wiki/kimaki.md`
+
+**Bot not responding:**
+1. Check process: `ps aux | grep kimaki | grep -v grep`
+2. If dead: `cd ~/.kimaki && bash start-kimaki.sh`
+3. Wait 10s, check again
+4. Read wiki: Section "Common Issues > Bot Not Responding"
+5. Logs: `tail -50 ~/.kimaki/kimaki.log`
+
+**Sessions not spawning:**
+1. Read wiki: Section "Common Issues > Sessions Not Starting"
+2. Validate opencode: `opencode --version`
+3. Check agent names in opencode.json match what's being spawned
+4. Test: `kimaki send --channel <id> --prompt 'ping' --agent build`
+
+**Token expired (401 errors):**
+1. Read wiki: Section "Bot Setup (One-Time)"
+2. Read discord.md: Section "Common Issues > Bot Not Online"
+3. User needs to regenerate token in Discord Developer Portal
+4. Update `~/.huckleberry/.env` with new token
+5. Restart kimaki
+
+### Discord Bot Fixes
+**Reference:** `~/.huckleberry/wiki/discord.md`
+
+**Bot not online:**
+1. Check token in ~/.huckleberry/.env
+2. Read wiki: Section "Common Issues > Bot Not Online"
+3. If token invalid: user regenerates in Discord Developer Portal
+4. Read discord.md: "Bot Setup" for OAuth2 flow
+5. After token update: `killall node && kimaki start`
+
+**Bot can't see messages:**
+1. Read wiki: Section "Common Issues > Bot Can't See Messages"
+2. Check Message Content Intent in Discord Developer Portal
+3. Check channel permissions
+4. Check server permissions override
+
+**Bot joined wrong server:**
+1. Read wiki: Section "Adding to Existing Server"
+2. Regenerate OAuth2 URL
+3. Remove bot from old server
+4. Re-add via new URL
+
+### opencode Fixes
+**Reference:** `~/.huckleberry/wiki/opencode.md`
+
+**Not installed:**
+→ `npm install -g opencode`
+
+**Config errors:**
+1. Validate: `node -e "JSON.parse(require('fs').readFileSync('$HOME/.opencode/opencode.json','utf8'))" && echo "VALID"`
+2. Read wiki: Section "Configuration" for key sections
+3. Check MCP server paths exist
+4. Check agent model strings
+
+**Plugin not loading:**
+1. Read wiki: Section "Common Issues > Plugin Not Loading"
+2. Check plugin file exists at the path in opencode.json
+3. Check plugin syntax
+4. Verify plugin path is relative to opencode.json
+
+### Inkstone Fixes
+**Reference:** `~/.huckleberry/wiki/inkstone.md`
+
+**Pre-injection gate blocking tools:**
+1. Read wiki: Section "Common Issues > Pre-injection Gate Blocks Tools"
+2. Fix: run `inkstone_memory_failures()` + `inkstone_memory_search()` in the session
+3. This is normal behavior, not a bug
+
+**MCP server not starting:**
+1. Read wiki: Section "Common Issues > MCP Server Won't Start"
+2. Check Node.js: `node --version`
+3. Check server file exists
+4. Run manually: `node ~/.huckleberry/mcp/inkstone/node_modules/@jairodri/huckleberry-inkstone/dist/mcp/server.js`
+5. If missing node_modules: `cd ~/.huckleberry/mcp/inkstone && npm install`
+
+**Database corrupt:**
+1. Read wiki: Section "Common Issues > Database Corruption"
+2. Check: `inkstone status`
+3. Restore from backup if available
+4. Reinitialize if no backup
+
+## Final Verification
+After all fixes, report:
+```
+✅ Fix complete:
+  • Found: [root cause]
+  • Fixed: [what was done]
+  • Verified: [how tested]
+
+Status:
+  - opencode: [version] ✓
+  - kimaki: [version] ✓
+  - Inkstone DB: [size] ✓
+  - Discord bot: [online/offline]
+```

package/agents/hermes.json

@@ -0,0 +1,26 @@
+{
+  "name": "hermes",
+  "description": "System administrator — fixes the Huckleberry stack when it breaks.",
+  "model": "omniroute/combo/freellmapi smart models",
+  "instructions": [
+    "~/.huckleberry/agents/hermes/AGENTS.md",
+    "~/.huckleberry/agents/hermes/SOUL.md",
+    "~/.huckleberry/agents/hermes/hermes-fixer.md",
+    "~/.huckleberry/wiki/kimaki.md",
+    "~/.huckleberry/wiki/discord.md",
+    "~/.huckleberry/wiki/opencode.md",
+    "~/.huckleberry/wiki/inkstone.md"
+  ],
+  "skills": [
+    "~/.huckleberry/agents/hermes/fix-kimaki/SKILL.md"
+  ],
+  "mcp": [
+    "context7",
+    "inkstone"
+  ],
+  "tools": [
+    "context7_query-docs",
+    "inkstone_memory_search",
+    "inkstone_memory_failures"
+  ]
+}

package/bin/huckleberry.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2));

package/kanban/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: kanban
+description: >
+  Work as a Kimaki Kanban worker. Use when a task has KIMAKI_KANBAN_TASK or
+  the user asks to manage the multi-agent kanban board. Also use when the user
+  asks to stamp or list workflow templates.
+version: 0.2.0
+---
+
+# Kimaki Kanban Worker
+
+## When to Use
+
+Use this skill when:
+- You are spawned by the Kimaki Kanban dispatcher
+- The user asks to create, list, complete, block, or orchestrate kanban tasks
+- The user asks about workflow templates or wants to stamp one
+
+## Environment
+
+- `KIMAKI_KANBAN_TASK` — current task id
+- `KIMAKI_KANBAN_DB` — SQLite database path
+- `KIMAKI_KANBAN_RUN` — current run id
+
+## Required Worker Loop
+
+1. Read the task details from the prompt.
+2. **Load the skills listed in the task's `skills:` field.** Use the `skill` tool for each one (e.g., `skill("blog-publish-pipeline")`). If no skills are listed, proceed without loading any.
+3. Complete the requested work using the loaded skills and normal Kimaki tools.
+4. If you create artifacts, include exact file paths in your completion summary.
+5. Complete the task:
+
+```bash
+bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs complete "$KIMAKI_KANBAN_TASK" --summary "Completed: <what changed>"
+```
+
+5. If you are blocked:
+
+```bash
+bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs block "$KIMAKI_KANBAN_TASK" --reason "Need human input: <specific question>"
+```
+
+## Workflow Templates
+
+The kanban system supports brand-agnostic workflow templates. These are YAML files in `templates/` that define multi-step task DAGs with variable interpolation.
+
+### Listing Templates
+
+```bash
+bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs templates
+bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs templates --details
+```
+
+### Stamping a Template for a Brand
+
+See **CLI Reference** below for full syntax.
+
+## CLI Reference
+
+All commands: `bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs <command> [options]`
+
+Common flags: `--db <path>` (default: `kanban.db` in cwd)
+
+### Task Lifecycle
+
+```bash
+# Create a task
+cli.mjs create "Task title" --tenant <business> --project <project> --assignee <agent> --skills skill1,skill2
+
+# List tasks (supports all filters)
+cli.mjs list [--tenant <business>] [--project <project>] [--status ready|todo|in_progress|done|blocked] [--assignee <agent>] [--limit N]
+
+# Show task details
+cli.mjs show <task_id>
+
+# Complete a task
+cli.mjs complete <task_id> --summary "What was done"
+
+# Block a task
+cli.mjs block <task_id> --reason "Why blocked"
+```
+
+### Templates
+
+```bash
+# List available templates
+cli.mjs templates [--details]
+
+# Stamp a template (creates all tasks in the DAG)
+cli.mjs stamp <template-name> \
+  --var topic="solar chargers" \
+  --var tenant=nomadixgear \
+  --project seo-hub-spoke
+```
+
+### --project Flag
+
+The `--project` flag groups tasks within a tenant by project. Use it on `create`, `list`, and `stamp`:
+
+```bash
+# Create with project
+cli.mjs create "Build hub pages" --tenant enchantents --project seo-hub-spoke
+
+# List only tasks for a specific project
+cli.mjs list --tenant enchantents --project seo-hub-spoke
+
+# Stamp with project (all tasks in the DAG inherit it)
+cli.mjs stamp blog-social-campaign --var topic="solar chargers" --var tenant=enchantents --project seo-hub-spoke
+```
+
+Available templates:
+- `blog-social-campaign` — Research (keywords + Reddit + PAA) → AEO triplet publish → multi-platform distribution (5 tasks)
+- `ai-visibility-sprint` — AI citation audit → gap analysis → content overhaul → distribute → tracking setup (5 tasks)
+- `product-launch` — Position → assets → listing + announce (4 tasks)
+- `b2b-outreach` — Scrape → research → emails → send (4 tasks)
+- `seo-silo` — Keywords → hub pages → spoke pages → off-page (4 tasks)
+
+### Building a New Template
+
+Create a YAML file in `/Users/clawdbot/clawd/workspace/kimaki-kanban/templates/`:
+
+```yaml
+name: My Workflow
+description: What it does
+
+variables:
+  - name: topic
+    required: true
+  - name: tenant
+    required: true
+
+tasks:
+  - id: step1
+    title: "Step 1: {{topic}}"
+    assignee: researcher
+    skills: [keyword-research]
+    priority: 3
+    body: |
+      Research {{topic}} and save results.
+
+  - id: step2
+    title: "Step 2: {{topic}}"
+    assignee: writer
+    skills: [Publishing Blog Articles]
+    parents: [step1]
+    priority: 2
+    body: |
+      Write about {{topic}} using step1 results.
+```
+
+Run `bun /Users/clawdbot/clawd/workspace/kimaki-kanban/src/cli.mjs stamp-help` for the full agent guide.
+
+## Human Gates
+
+Block instead of continuing when:
+
+- External publishing or sending is required
+- Pricing/positioning needs approval
+- The task requires credentials or access you do not have
+- Source data is insufficient and continuing would require guessing
+
+## Quality Bar
+
+- Deliver artifacts, not status.
+- Keep summaries concise.
+- Never fabricate results.
+- Use parent task results as source context.

package/kanban/kanban

@@ -0,0 +1,3 @@
+#!/bin/sh
+# kanban wrapper — runs the kanban CLI
+exec node "$(dirname "$0")/src/cli.mjs" "$@"

package/kanban/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "huckleberry-kanban",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0"
+  }
+}