@intent-systems/nexus 2026.1.5-3

package/skills/clawdhub/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: nexushub
+description: Use the NexusHub CLI to search, install, update, and publish agent skills from nexushub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed nexushub CLI.
+metadata: {"nexus":{"requires":{"bins":["nexushub"]},"install":[{"id":"node","kind":"node","package":"nexushub","bins":["nexushub"],"label":"Install NexusHub CLI (npm)"}]}}
+---
+
+# NexusHub CLI
+
+Install
+```bash
+npm i -g nexushub
+```
+
+Auth (publish)
+```bash
+nexushub login
+nexushub whoami
+```
+
+Search
+```bash
+nexushub search "postgres backups"
+```
+
+Install
+```bash
+nexushub install my-skill
+nexushub install my-skill --version 1.2.3
+```
+
+Update (hash-based match + upgrade)
+```bash
+nexushub update my-skill
+nexushub update my-skill --version 1.2.3
+nexushub update --all
+nexushub update my-skill --force
+nexushub update --all --no-input --force
+```
+
+List
+```bash
+nexushub list
+```
+
+Publish
+```bash
+nexushub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --changelog "Fixes + docs"
+```
+
+Notes
+- Default registry: https://nexushub.com (override with NEXUSHUB_REGISTRY or --registry)
+- Default workdir: cwd; install dir: ./skills (override with --workdir / --dir)
+- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set

package/skills/coding-agent/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: coding-agent
+description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
+metadata: {"nexus":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}
+---
+
+# Coding Agent (background-first)
+
+Use **bash background mode** for non-interactive coding work. For interactive coding sessions, use the **tmux** skill (always, except very simple one-shot prompts).
+
+## The Pattern: workdir + background
+
+```bash
+# Create temp space for chats/scratch work
+SCRATCH=$(mktemp -d)
+
+# Start agent in target directory ("little box" - only sees relevant files)
+bash workdir:$SCRATCH background:true command:"<agent command>"
+# Or for project work:
+bash workdir:~/project/folder background:true command:"<agent command>"
+# Returns sessionId for tracking
+
+# Monitor progress
+process action:log sessionId:XXX
+
+# Check if done  
+process action:poll sessionId:XXX
+
+# Send input (if agent asks a question)
+process action:write sessionId:XXX data:"y"
+
+# Kill if needed
+process action:kill sessionId:XXX
+```
+
+**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
+
+---
+
+## Codex CLI
+
+**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
+
+### Building/Creating (use --full-auto or --yolo)
+```bash
+# --full-auto: sandboxed but auto-approves in workspace
+bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""
+
+# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
+bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""
+
+# Note: --yolo is a shortcut for --dangerously-bypass-approvals-and-sandbox
+```
+
+### Reviewing PRs (vanilla, no flags)
+
+**⚠️ CRITICAL: Never review PRs in Nexus's own project folder!**
+- Either use the project where the PR is submitted (if it's NOT ~/Projects/nexus)
+- Or clone to a temp folder first
+
+```bash
+# Option 1: Review in the actual project (if NOT nexus)
+bash workdir:~/Projects/some-other-repo background:true command:"codex review --base main"
+
+# Option 2: Clone to temp folder for safe review (REQUIRED for nexus PRs!)
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/nexus/nexus.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+bash workdir:$REVIEW_DIR background:true command:"codex review --base origin/main"
+# Clean up after: rm -rf $REVIEW_DIR
+
+# Option 3: Use git worktree (keeps main intact)
+git worktree add /tmp/pr-130-review pr-130-branch
+bash workdir:/tmp/pr-130-review background:true command:"codex review --base main"
+```
+
+**Why?** Checking out branches in the running Nexus repo can break the live instance!
+
+### Batch PR Reviews (parallel army!)
+```bash
+# Fetch all PR refs first
+git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
+
+# Deploy the army - one Codex per PR!
+bash workdir:~/project background:true command:"codex exec \"Review PR #86. git diff origin/main...origin/pr/86\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #87. git diff origin/main...origin/pr/87\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #95. git diff origin/main...origin/pr/95\""
+# ... repeat for all PRs
+
+# Monitor all
+process action:list
+
+# Get results and post to GitHub
+process action:log sessionId:XXX
+gh pr comment <PR#> --body "<review content>"
+```
+
+### Tips for PR Reviews
+- **Fetch refs first:** `git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'`
+- **Use git diff:** Tell Codex to use `git diff origin/main...origin/pr/XX`
+- **Don't checkout:** Multiple parallel reviews = don't let them change branches
+- **Post results:** Use `gh pr comment` to post reviews to GitHub
+
+---
+
+## Claude Code
+
+```bash
+bash workdir:~/project background:true command:"claude \"Your task\""
+```
+
+---
+
+## OpenCode
+
+```bash
+bash workdir:~/project background:true command:"opencode run \"Your task\""
+```
+
+---
+
+## Pi Coding Agent
+
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+bash workdir:~/project background:true command:"pi \"Your task\""
+```
+
+---
+
+## Pi flags (common)
+
+- `--print` / `-p`: non-interactive; runs prompt and exits.
+- `--provider <name>`: pick provider (default: google).
+- `--model <id>`: pick model (default: gemini-2.5-flash).
+- `--api-key <key>`: override API key (defaults to env vars).
+
+Examples:
+
+```bash
+# Set provider + model, non-interactive
+bash workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p \"Summarize src/\""
+```
+
+---
+
+## tmux (interactive sessions)
+
+Use the tmux skill for interactive coding sessions (always, except very simple one-shot prompts). Prefer bash background mode for non-interactive runs.
+
+---
+
+## Parallel Issue Fixing with git worktrees + tmux
+
+For fixing multiple issues in parallel, use git worktrees (isolated branches) + tmux sessions:
+
+```bash
+# 1. Clone repo to temp location
+cd /tmp && git clone git@github.com:user/repo.git repo-worktrees
+cd repo-worktrees
+
+# 2. Create worktrees for each issue (isolated branches!)
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 3. Set up tmux sessions
+SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
+tmux -S "$SOCKET" new-session -d -s fix-78
+tmux -S "$SOCKET" new-session -d -s fix-99
+
+# 4. Launch Codex in each (after pnpm install!)
+tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" Enter
+tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'" Enter
+
+# 5. Monitor progress
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30
+tmux -S "$SOCKET" capture-pane -p -t fix-99 -S -30
+
+# 6. Check if done (prompt returned)
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -3 | grep -q "❯" && echo "Done!"
+
+# 7. Create PRs after fixes
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# 8. Cleanup
+tmux -S "$SOCKET" kill-server
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+**Why worktrees?** Each Codex works in isolated branch, no conflicts. Can run 5+ parallel fixes!
+
+**Why tmux over bash background?** Codex is interactive — needs TTY for proper output. tmux provides persistent sessions with full history capture.
+
+---
+
+## ⚠️ Rules
+
+1. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
+2. **Be patient** — don't kill sessions because they're "slow"
+3. **Monitor with process:log** — check progress without interfering
+4. **--full-auto for building** — auto-approves changes
+5. **vanilla for reviewing** — no special flags needed
+6. **Parallel is OK** — run many Codex processes at once for batch work
+7. **NEVER start Codex in ~/nexus/** — it'll read your soul docs and get weird ideas about the org chart! Use the target project dir or /tmp for blank slate chats
+8. **NEVER checkout branches in ~/Projects/nexus/** — that's the LIVE Nexus instance! Clone to /tmp or use git worktree for PR reviews
+
+---
+
+## PR Template (The Razor Standard)
+
+When submitting PRs to external repos, use this format for quality & maintainer-friendliness:
+
+````markdown
+## Original Prompt
+[Exact request/problem statement]
+
+## What this does
+[High-level description]
+
+**Features:**
+- [Key feature 1]
+- [Key feature 2]
+
+**Example usage:**
+```bash
+# Example
+command example
+```
+
+## Feature intent (maintainer-friendly)
+[Why useful, how it fits, workflows it enables]
+
+## Prompt history (timestamped)
+- YYYY-MM-DD HH:MM UTC: [Step 1]
+- YYYY-MM-DD HH:MM UTC: [Step 2]
+
+## How I tested
+**Manual verification:**
+1. [Test step] - Output: `[result]`
+2. [Test step] - Result: [result]
+
+**Files tested:**
+- [Detail]
+- [Edge cases]
+
+## Session logs (implementation)
+- [What was researched]
+- [What was discovered]
+- [Time spent]
+
+## Implementation details
+**New files:**
+- `path/file.ts` - [description]
+
+**Modified files:**
+- `path/file.ts` - [change]
+
+**Technical notes:**
+- [Detail 1]
+- [Detail 2]
+
+---
+*Submitted by Razor 🥷 - Mariano's AI agent*
+````
+
+**Key principles:**
+1. Human-written description (no AI slop)
+2. Feature intent for maintainers
+3. Timestamped prompt history
+4. Session logs if using Codex/agent
+
+**Example:** https://github.com/steipete/bird/pull/22

package/skills/comms/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: comms
+description: Unified communications cartographer - aggregates communications across all channels into a single queryable event store
+homepage: https://github.com/Napageneral/comms
+metadata: {"nexus":{"emoji":"📡","os":["darwin","linux"],"requires":{"bins":["comms"]},"install":[{"id":"brew","kind":"brew","formula":"Napageneral/tap/comms","bins":["comms"],"label":"Install via Homebrew"},{"id":"go","kind":"shell","script":"go install github.com/Napageneral/comms/cmd/comms@latest","bins":["comms"],"label":"Install via Go"}]}}
+---
+
+# Comms — Unified Communications Cartographer
+
+Comms aggregates your communications across all channels (iMessage, Gmail, Slack, AI sessions, etc.) into a single queryable event store with identity resolution.
+
+## Docs
+
+- `docs/setup.md`
+- `docs/adapters.md`
+- `docs/troubleshooting.md`
+- `references/schema.md`
+
+## Why Comms?
+
+Your communications are fragmented:
+- iMessage threads with some people
+- Email conversations with others
+- Slack for work
+- AI chat sessions in Cursor
+
+Comms unifies them into one data layer, so you can ask:
+- "What did I discuss with Dad across ALL channels?"
+- "Show me everything related to the HTAA project"
+- "Who have I communicated with most this year?"
+
+## Quick Start
+
+```bash
+# Initialize
+comms init
+
+# Configure your identity
+comms me set --name "Tyler Brandt" --phone "+17072876731" --email "tnapathy@gmail.com"
+
+# Connect adapters (requires Eve and gogcli installed)
+comms connect imessage
+comms connect gmail --account tnapathy@gmail.com
+
+# Sync all channels
+comms sync
+
+# Query
+comms events --person "Dad" --since "2025-01-01"
+comms people --top 20
+```
+
+## Commands
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `comms init` | Initialize config and event store |
+| `comms me set --name "..." --phone "..." --email "..."` | Configure your identity |
+| `comms connect <adapter>` | Configure a channel adapter |
+| `comms adapters` | List configured adapters |
+
+### Sync
+
+| Command | Description |
+|---------|-------------|
+| `comms sync` | Sync all enabled adapters |
+| `comms sync --adapter imessage` | Sync specific adapter |
+| `comms sync --full` | Force full re-sync |
+
+### Query
+
+| Command | Description |
+|---------|-------------|
+| `comms events` | List events with filters |
+| `comms events --person "Dad"` | Filter by person |
+| `comms events --channel imessage` | Filter by channel |
+| `comms events --since 2025-01-01` | Filter by date |
+| `comms people` | List all people |
+| `comms people --top 20` | Top contacts by event count |
+| `comms people "Dad"` | Show person details |
+| `comms timeline 2026-01` | Events in time period |
+| `comms timeline --today` | Today's events |
+| `comms db query <sql>` | Raw SQL access |
+
+### Identity Management
+
+| Command | Description |
+|---------|-------------|
+| `comms identify` | List all people + identities |
+| `comms identify --merge "Person A" "Person B"` | Merge two people |
+| `comms identify --add "Dad" --email "dad@example.com"` | Add identity |
+
+### Tags
+
+| Command | Description |
+|---------|-------------|
+| `comms tag list` | List all tags |
+| `comms tag add --event <id> --tag "project:htaa"` | Tag an event |
+| `comms tag add --filter "person:Dane" --tag "context:business"` | Bulk tag |
+
+## Adapters
+
+### iMessage (via Eve)
+
+Prerequisites:
+```bash
+brew install Napageneral/tap/eve
+eve init && eve sync
+```
+
+Connect:
+```bash
+comms connect imessage
+```
+
+### Gmail (via gogcli)
+
+Prerequisites:
+```bash
+brew install steipete/tap/gogcli
+gog auth add your@gmail.com
+```
+
+Connect:
+```bash
+comms connect gmail --account your@gmail.com
+```
+
+### AI Sessions (via aix)
+
+Connect:
+```bash
+comms connect cursor
+```
+
+### X/Twitter (via bird)
+
+Prerequisites:
+```bash
+brew install steipete/tap/bird
+bird check  # Verify auth via Chrome cookies
+```
+
+Connect:
+```bash
+comms connect x
+```
+
+Syncs: bookmarks, likes, mentions
+
+## Output Formats
+
+All commands support `--json` / `-j`:
+
+```bash
+comms events --json | jq '.events[] | select(.channel == "imessage")'
+comms people --top 10 --json
+```
+
+## Configuration
+
+Config: `~/.config/comms/config.yaml`
+
+```yaml
+me:
+  canonical_name: "Tyler Brandt"
+  identities:
+    - channel: imessage
+      identifier: "+17072876731"
+    - channel: email
+      identifier: "tnapathy@gmail.com"
+
+adapters:
+  imessage:
+    type: eve
+    enabled: true
+  gmail:
+    type: gogcli
+    enabled: true
+    account: tnapathy@gmail.com
+```
+
+Data: `~/Library/Application Support/Comms/comms.db`
+
+## Bootstrap (for AI agents)
+
+```bash
+# Check if installed
+which comms && comms version
+
+# Install
+brew install Napageneral/tap/comms
+# OR: go install github.com/Napageneral/comms/cmd/comms@latest
+
+# Setup
+comms init
+
+# Configure identity
+comms me set --name "User Name" --email "user@example.com"
+
+# Connect adapters (assumes Eve/gogcli already set up)
+comms connect imessage
+comms connect gmail --account user@gmail.com
+
+# Sync
+comms sync
+
+# Verify
+comms db query "SELECT COUNT(*) as count FROM events"
+comms people --top 5
+```
+
+## Event Schema
+
+Events have these core properties:
+- `id` — Unique identifier
+- `timestamp` — When it happened
+- `channel` — imessage, gmail, slack, cursor, etc.
+- `content_types` — ["text"], ["text", "image"], etc.
+- `direction` — sent, received, observed
+- `participants` — People involved (resolved via identity)
+
+Queryable via:
+```bash
+comms db query "SELECT * FROM events WHERE channel = 'imessage' LIMIT 10"
+```
+
+## Tips for Agents
+
+1. Use `comms people --top 10` to understand who the user communicates with most
+2. Use `comms events --person "Name"` to get context on a relationship
+3. Use `comms timeline --today` for recent activity
+4. Filter by channel to focus on specific contexts
+5. Use `--json` output for programmatic access
+6. Raw SQL via `comms db query` for complex queries
+
+Example agent workflow:
+```bash
+# "Tell me about my communication with Dad"
+comms people "Dad"                              # Get identity info
+comms events --person "Dad" --since 2025-01-01  # Recent events
+comms db query "SELECT channel, COUNT(*) FROM events e 
+  JOIN event_participants ep ON e.id = ep.event_id 
+  JOIN persons p ON ep.person_id = p.id 
+  WHERE p.display_name = 'Dad' 
+  GROUP BY channel"                             # Channel breakdown
+```

package/skills/comms/docs/adapters.md

@@ -0,0 +1,54 @@
+# Comms Adapters
+
+Each adapter depends on a working underlying tool.
+
+## iMessage (eve)
+
+Prereq: `eve` installed and synced.
+
+```bash
+eve whoami
+comms connect imessage
+```
+
+## Gmail (gog)
+
+Prereq: `gog` installed and authenticated.
+
+```bash
+gog gmail labels list --account you@gmail.com
+comms connect gmail --account you@gmail.com
+```
+
+Multiple accounts:
+
+```bash
+comms connect gmail --account work@company.com
+```
+
+## WhatsApp (wacli)
+
+Prereq: `wacli` authenticated.
+
+```bash
+wacli doctor
+comms connect whatsapp
+```
+
+## AI sessions (aix)
+
+Prereq: `aix` installed and synced.
+
+```bash
+aix stats
+comms connect cursor
+```
+
+## X/Twitter (bird)
+
+Prereq: `bird` authenticated.
+
+```bash
+bird whoami
+comms connect x
+```

package/skills/comms/docs/setup.md

@@ -0,0 +1,56 @@
+# Comms Setup
+
+Comms aggregates communications into a single event store. You need at least one adapter (eve, gog, wacli, aix, or bird).
+
+## Prerequisites
+
+- At least one communication source installed and configured
+- `comms` installed
+
+## Install
+
+```bash
+# Homebrew (recommended)
+brew install Napageneral/tap/comms
+
+# Or via Go
+go install github.com/Napageneral/comms/cmd/comms@latest
+
+# Verify
+comms version
+```
+
+## Initialize
+
+```bash
+comms init
+```
+
+This creates:
+- `~/.config/comms/config.yaml`
+- `~/Library/Application Support/Comms/comms.db`
+
+## Set your identity
+
+```bash
+comms me set --name "Your Name" --phone "+1YOURNUMBER" --email "you@example.com"
+comms me
+```
+
+## Connect adapters
+
+See `docs/adapters.md` for per-adapter setup.
+
+```bash
+comms connect imessage
+comms connect gmail --account you@gmail.com
+comms adapters
+```
+
+## Sync and verify
+
+```bash
+comms sync
+comms events --limit 10
+comms people --top 5
+```