@quantumclaw/quantumclaw 2026.3.22

package/skills/coding-agent/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: coding-agent
+description: 'Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.'
+metadata:
+  {
+    "quantumclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
+  }
+---
+
+# Coding Agent (bash-first)
+
+Use **bash** (with optional background mode) for all coding agent work. Simple and effective.
+
+## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no
+
+For **Codex, Pi, and OpenCode**, PTY is still required (interactive terminal apps):
+
+```bash
+# ✅ Correct for Codex/Pi/OpenCode
+bash pty:true command:"codex exec 'Your prompt'"
+```
+
+For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead.
+`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog.
+`--print` mode keeps full tool access and avoids interactive confirmation:
+
+```bash
+# ✅ Correct for Claude Code (no PTY needed)
+cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'
+
+# For background execution: use background:true on the exec tool
+
+# ❌ Wrong for Claude Code
+bash pty:true command:"claude --dangerously-skip-permissions 'task'"
+```
+
+### Bash Tool Parameters
+
+| Parameter    | Type    | Description                                                                 |
+| ------------ | ------- | --------------------------------------------------------------------------- |
+| `command`    | string  | The shell command to run                                                    |
+| `pty`        | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |
+| `workdir`    | string  | Working directory (agent sees only this folder's context)                   |
+| `background` | boolean | Run in background, returns sessionId for monitoring                         |
+| `timeout`    | number  | Timeout in seconds (kills process on expiry)                                |
+| `elevated`   | boolean | Run on host instead of sandbox (if allowed)                                 |
+
+### Process Tool Actions (for background sessions)
+
+| Action      | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `list`      | List all running/recent sessions                     |
+| `poll`      | Check if session is still running                    |
+| `log`       | Get session output (with optional offset/limit)      |
+| `write`     | Send raw data to stdin                               |
+| `submit`    | Send data + newline (like typing and pressing Enter) |
+| `send-keys` | Send key tokens or hex bytes                         |
+| `paste`     | Paste text (with optional bracketed mode)            |
+| `kill`      | Terminate the session                                |
+
+---
+
+## Quick Start: One-Shot Tasks
+
+For quick prompts/chats, create a temp git repo and run:
+
+```bash
+# Quick chat (Codex needs a git repo!)
+SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"
+
+# Or in a real project - with PTY!
+bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"
+```
+
+**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.
+
+---
+
+## The Pattern: workdir + background + pty
+
+For longer tasks, use background mode with PTY:
+
+```bash
+# Start agent in target directory (with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
+# 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"
+
+# Submit with Enter (like typing "yes" and pressing Enter)
+process action:submit sessionId:XXX data:"yes"
+
+# 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)
+
+### Flags
+
+| Flag            | Effect                                             |
+| --------------- | -------------------------------------------------- |
+| `exec "prompt"` | One-shot execution, exits when done                |
+| `--full-auto`   | Sandboxed but auto-approves in workspace           |
+| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |
+
+### Building/Creating
+
+```bash
+# Quick one-shot (auto-approves) - remember PTY!
+bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
+
+# Background for longer work
+bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"
+```
+
+### Reviewing PRs
+
+**⚠️ CRITICAL: Never review PRs in QuantumClaw's own project folder!**
+Clone to temp folder or use git worktree.
+
+```bash
+# Clone to temp for safe review
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/user/repo.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
+# Clean up after: trash $REVIEW_DIR
+
+# Or use git worktree (keeps main intact)
+git worktree add /tmp/pr-130-review pr-130-branch
+bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
+```
+
+### 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 (all with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"
+
+# Monitor all
+process action:list
+
+# Post results to GitHub
+gh pr comment <PR#> --body "<review content>"
+```
+
+---
+
+## Claude Code
+
+```bash
+# Foreground
+bash workdir:~/project command:"claude --permission-mode bypassPermissions --print 'Your task'"
+
+# Background
+bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'"
+```
+
+---
+
+## OpenCode
+
+```bash
+bash pty:true workdir:~/project command:"opencode run 'Your task'"
+```
+
+---
+
+## Pi Coding Agent
+
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+bash pty:true workdir:~/project command:"pi 'Your task'"
+
+# Non-interactive mode (PTY still recommended)
+bash pty:true command:"pi -p 'Summarize src/'"
+
+# Different provider/model
+bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"
+```
+
+**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
+
+---
+
+## Parallel Issue Fixing with git worktrees
+
+For fixing multiple issues in parallel, use git worktrees:
+
+```bash
+# 1. Create worktrees for each issue
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 2. Launch Codex in each (background + PTY!)
+bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
+bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'"
+
+# 3. Monitor progress
+process action:list
+process action:log sessionId:XXX
+
+# 4. 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 "..."
+
+# 5. Cleanup
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+---
+
+## ⚠️ Rules
+
+1. **Use the right execution mode per agent**:
+   - Codex/Pi/OpenCode: `pty:true`
+   - Claude Code: `--print --permission-mode bypassPermissions` (no PTY required)
+2. **Respect tool choice** - if user asks for Codex, use Codex.
+   - Orchestrator mode: do NOT hand-code patches yourself.
+   - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
+3. **Be patient** - don't kill sessions because they're "slow"
+4. **Monitor with process:log** - check progress without interfering
+5. **--full-auto for building** - auto-approves changes
+6. **vanilla for reviewing** - no special flags needed
+7. **Parallel is OK** - run many Codex processes at once for batch work
+8. **NEVER start Codex in ~/.quantumclaw/** - it'll read your soul docs and get weird ideas about the org chart!
+9. **NEVER checkout branches in ~/Projects/quantumclaw/** - that's the LIVE QuantumClaw instance!
+
+---
+
+## Progress Updates (Critical)
+
+When you spawn coding agents in the background, keep the user in the loop.
+
+- Send 1 short message when you start (what's running + where).
+- Then only update again when something changes:
+  - a milestone completes (build finished, tests passed)
+  - the agent asks a question / needs input
+  - you hit an error or need user action
+  - the agent finishes (include what changed + where)
+- If you kill a session, immediately say you killed it and why.
+
+This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.
+
+---
+
+## Auto-Notify on Completion
+
+For long-running background tasks, append a wake trigger to your prompt so QuantumClaw gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):
+
+```
+... your task here.
+
+When completely finished, run this command to notify me:
+quantumclaw system event --text "Done: [brief summary of what was built]" --mode now
+```
+
+**Example:**
+
+```bash
+bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.
+
+When completely finished, run: quantumclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
+```
+
+This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
+
+---
+
+## Learnings (Jan 2026)
+
+- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs.
+- **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.
+- **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots.
+- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.
+- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: _"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"_ 🦞

package/skills/discord/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: discord
+description: "Discord ops via the message tool (channel=discord)."
+metadata: { "quantumclaw": { "emoji": "🎮", "requires": { "config": ["channels.discord.token"] } } }
+allowed-tools: ["message"]
+---
+
+# Discord (Via `message`)
+
+Use the `message` tool. No provider-specific `discord` tool exposed to the agent.
+
+## Musts
+
+- Always: `channel: "discord"`.
+- Respect gating: `channels.discord.actions.*` (some default off: `roles`, `moderation`, `presence`, `channels`).
+- Prefer explicit ids: `guildId`, `channelId`, `messageId`, `userId`.
+- Multi-account: optional `accountId`.
+
+## Guidelines
+
+- Avoid Markdown tables in outbound Discord messages.
+- Mention users as `<@USER_ID>`.
+- Prefer Discord components v2 (`components`) for rich UI; use legacy `embeds` only when you must.
+
+## Targets
+
+- Send-like actions: `to: "channel:<id>"` or `to: "user:<id>"`.
+- Message-specific actions: `channelId: "<id>"` (or `to`) + `messageId: "<id>"`.
+
+## Common Actions (Examples)
+
+Send message:
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "hello",
+  "silent": true
+}
+```
+
+Send with media:
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "see attachment",
+  "media": "file:///tmp/example.png"
+}
+```
+
+- Optional `silent: true` to suppress Discord notifications.
+
+Send with components v2 (recommended for rich UI):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "components": "[Carbon v2 components]"
+}
+```
+
+- `components` expects Carbon component instances (Container, TextDisplay, etc.) from JS/TS integrations.
+- Do not combine `components` with `embeds` (Discord rejects v2 + embeds).
+
+Legacy embeds (not recommended):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "embeds": [{ "title": "Legacy", "description": "Embeds are legacy." }]
+}
+```
+
+- `embeds` are ignored when components v2 are present.
+
+React:
+
+```json
+{
+  "action": "react",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "emoji": "✅"
+}
+```
+
+Read:
+
+```json
+{
+  "action": "read",
+  "channel": "discord",
+  "to": "channel:123",
+  "limit": 20
+}
+```
+
+Edit / delete:
+
+```json
+{
+  "action": "edit",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "message": "fixed typo"
+}
+```
+
+```json
+{
+  "action": "delete",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+Poll:
+
+```json
+{
+  "action": "poll",
+  "channel": "discord",
+  "to": "channel:123",
+  "pollQuestion": "Lunch?",
+  "pollOption": ["Pizza", "Sushi", "Salad"],
+  "pollMulti": false,
+  "pollDurationHours": 24
+}
+```
+
+Pins:
+
+```json
+{
+  "action": "pin",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+Threads:
+
+```json
+{
+  "action": "thread-create",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "threadName": "bug triage"
+}
+```
+
+Search:
+
+```json
+{
+  "action": "search",
+  "channel": "discord",
+  "guildId": "999",
+  "query": "release notes",
+  "channelIds": ["123", "456"],
+  "limit": 10
+}
+```
+
+Presence (often gated):
+
+```json
+{
+  "action": "set-presence",
+  "channel": "discord",
+  "activityType": "playing",
+  "activityName": "with fire",
+  "status": "online"
+}
+```
+
+## Writing Style (Discord)
+
+- Short, conversational, low ceremony.
+- No markdown tables.
+- Mention users as `<@USER_ID>`.

package/skills/eightctl/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: eightctl
+description: Control Eight Sleep pods (status, temperature, alarms, schedules).
+homepage: https://eightctl.sh
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "🛌",
+        "requires": { "bins": ["eightctl"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/eightctl/cmd/eightctl@latest",
+              "bins": ["eightctl"],
+              "label": "Install eightctl (go)",
+            },
+          ],
+      },
+  }
+---
+
+# eightctl
+
+Use `eightctl` for Eight Sleep pod control. Requires auth.
+
+Auth
+
+- Config: `~/.config/eightctl/config.yaml`
+- Env: `EIGHTCTL_EMAIL`, `EIGHTCTL_PASSWORD`
+
+Quick start
+
+- `eightctl status`
+- `eightctl on|off`
+- `eightctl temp 20`
+
+Common tasks
+
+- Alarms: `eightctl alarm list|create|dismiss`
+- Schedules: `eightctl schedule list|create|update`
+- Audio: `eightctl audio state|play|pause`
+- Base: `eightctl base info|angle`
+
+Notes
+
+- API is unofficial and rate-limited; avoid repeated logins.
+- Confirm before changing temperature or alarms.

package/skills/gemini/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gemini
+description: Gemini CLI for one-shot Q&A, summaries, and generation.
+homepage: https://ai.google.dev/
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "✨",
+        "requires": { "bins": ["gemini"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Gemini CLI
+
+Use Gemini in one-shot mode with a positional prompt (avoid interactive mode).
+
+Quick start
+
+- `gemini "Answer this question..."`
+- `gemini --model <name> "Prompt..."`
+- `gemini --output-format json "Return JSON"`
+
+Extensions
+
+- List: `gemini --list-extensions`
+- Manage: `gemini extensions <command>`
+
+Notes
+
+- If auth is required, run `gemini` once interactively and follow the login flow.
+- Avoid `--yolo` for safety.