@dreb/coding-agent 1.16.0

package/docs/shell-aliases.md

@@ -0,0 +1,55 @@
+# Shell Aliases
+
+dreb runs bash in non-interactive mode (`bash -c "<command>"`). Non-interactive bash doesn't load your shell config files (`.bashrc`, `.bash_profile`) and doesn't expand aliases by default.
+
+## Enabling aliases
+
+Add to `~/.dreb/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\nsource ~/.bashrc 2>/dev/null\n"
+}
+```
+
+The `shellCommandPrefix` is prepended to every bash command dreb executes. This sources your config and enables alias expansion.
+
+Adjust the path to match your shell config: `~/.bashrc`, `~/.bash_profile`, etc.
+
+## Performance warning
+
+`shellCommandPrefix` runs on **every** bash command — including simple things like `ls` or `cat`. If your `.bashrc` is slow (loads nvm, conda, pyenv, etc.), this adds latency to every tool call.
+
+To avoid this, source only the aliases you need instead of the full config:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.bashrc)\"\n"
+}
+```
+
+This extracts only `alias` lines, skipping everything else.
+
+## zsh and fish
+
+The `shellCommandPrefix` runs inside bash, not your login shell. If your aliases are defined in `~/.zshrc` or `~/.config/fish/config.fish`, the `grep` approach works for simple aliases:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\"\n"
+}
+```
+
+Complex zsh/fish aliases that use shell-specific syntax won't translate to bash. For those, consider wrapper scripts in your `$PATH` instead.
+
+## Alternative: wrapper scripts
+
+If you have commands you frequently want dreb to use (e.g., `docker-compose`, `kubectl` shortcuts), you can create small scripts in a directory on your `$PATH` instead of relying on aliases:
+
+```bash
+#!/bin/bash
+# ~/bin/dc — shortcut for docker-compose
+exec docker-compose "$@"
+```
+
+This works without any `shellCommandPrefix` configuration.

package/docs/skills.md

@@ -0,0 +1,296 @@
+> dreb can create skills. Ask it to build one for your use case.
+
+# Skills
+
+Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
+
+dreb implements the [Agent Skills standard](https://agentskills.io/specification), warning about violations but remaining lenient.
+
+## Table of Contents
+
+- [Locations](#locations)
+- [How Skills Work](#how-skills-work)
+- [Invocation](#invocation)
+- [Skill Structure](#skill-structure)
+- [Frontmatter](#frontmatter)
+- [Content Substitution](#content-substitution)
+- [Validation](#validation)
+- [Example](#example)
+- [Built-in Skills](#built-in-skills)
+- [Skill Repositories](#skill-repositories)
+
+## Locations
+
+> **Note:** Skills can instruct the model to run commands and may include executable code. Skim what you're loading, same as any other dependency.
+
+dreb loads skills from:
+
+- Global:
+  - `~/.dreb/agent/skills/`
+  - `~/.agents/skills/`
+- Project:
+  - `.dreb/skills/`
+  - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
+- Packages: `skills/` directories or `dreb.skills` entries in `package.json`
+- Settings: `skills` array with files or directories
+- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
+
+Discovery rules:
+- Direct `.md` files in the skills directory root
+- Recursive `SKILL.md` files under subdirectories
+
+Disable discovery with `--no-skills` (explicit `--skill` paths still load).
+
+### Using Skills from Other Harnesses
+
+To use skills from Claude Code or OpenAI Codex, add their directories to settings:
+
+```json
+{
+  "skills": [
+    "~/.claude/skills",
+    "~/.codex/skills"
+  ]
+}
+```
+
+For project-level Claude Code skills, add to `.dreb/settings.json`:
+
+```json
+{
+  "skills": ["../.claude/skills"]
+}
+```
+
+## How Skills Work
+
+1. At startup, dreb scans skill locations and extracts names and descriptions
+2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills)
+3. When a task matches, the agent uses the `skill` tool to load the full SKILL.md with content substitution applied
+4. Users can also invoke skills directly via `/skill:name [args]` slash commands
+5. The agent follows the instructions, using relative paths to reference scripts and assets
+
+This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
+
+## Invocation
+
+### Skill Tool (model-invocable)
+
+The agent can invoke skills programmatically via the built-in `skill` tool:
+
+```
+skill(skill: "review-pr", args: "123")
+```
+
+The tool reads the SKILL.md, strips frontmatter, applies [content substitution](#content-substitution), and returns the expanded content. Skills with `disable-model-invocation: true` are hidden from the system prompt and return a warning if the model tries to invoke them.
+
+### Slash Commands (user-invocable)
+
+Skills register as `/skill:name` commands in interactive mode:
+
+```bash
+/skill:brave-search           # Load and execute the skill
+/skill:pdf-tools extract      # Load skill with arguments
+```
+
+Arguments after the command are passed through [content substitution](#content-substitution) into the skill content.
+
+Skills with `user-invocable: false` are hidden from the `/` menu but remain available to the model via the skill tool.
+
+Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
+
+```json
+{
+  "enableSkillCommands": true
+}
+```
+
+## Skill Structure
+
+A skill is a directory with a `SKILL.md` file. Everything else is freeform.
+
+```
+my-skill/
+├── SKILL.md              # Required: frontmatter + instructions
+├── scripts/              # Helper scripts
+│   └── process.sh
+├── references/           # Detailed docs loaded on-demand
+│   └── api-reference.md
+└── assets/
+    └── template.json
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it. Be specific.
+argument-hint: "<input file>"
+---
+
+# My Skill
+
+## Setup
+
+Run once before first use:
+\`\`\`bash
+cd ${DREB_SKILL_DIR} && npm install
+\`\`\`
+
+## Usage
+
+Process the input file: $1
+
+\`\`\`bash
+${DREB_SKILL_DIR}/scripts/process.sh $1
+\`\`\`
+```
+
+Use relative paths from the skill directory:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+```
+
+## Frontmatter
+
+Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required), plus dreb-specific fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory. |
+| `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
+| `argument-hint` | No | Hint text shown in the `/` menu (e.g. `"[PR number or URL]"`). |
+| `user-invocable` | No | Default `true`. When `false`, skill is hidden from the `/` menu but remains available to the model via the skill tool. |
+| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |
+
+### Name Rules
+
+- 1-64 characters
+- Lowercase letters, numbers, hyphens only
+- No leading/trailing hyphens
+- No consecutive hyphens
+- Must match parent directory name
+
+Valid: `pdf-processing`, `data-analysis`, `code-review`
+Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
+
+### Description Best Practices
+
+The description determines when the agent loads the skill. Be specific.
+
+Good:
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
+```
+
+Poor:
+```yaml
+description: Helps with PDFs.
+```
+
+## Content Substitution
+
+When a skill is invoked (via the skill tool or `/skill:name`), placeholders in the body are replaced before injection:
+
+| Placeholder | Replaced with |
+|-------------|---------------|
+| `$ARGUMENTS`, `$@` | All arguments joined |
+| `$0` | First argument (alias for `$1`) |
+| `$1`, `$2`, ... | Positional arguments (bash-style parsing: supports quoting) |
+| `${@:N}` | Arguments from the Nth position |
+| `${@:N:L}` | `L` arguments starting at N |
+| `${DREB_SKILL_DIR}` | Absolute path to the skill's directory |
+| `${DREB_SESSION_ID}` | Current session ID |
+
+Example:
+
+```markdown
+---
+name: review-file
+description: Review a specific file for issues.
+argument-hint: "<filename>"
+---
+Read ${DREB_SKILL_DIR}/checklist.md for the review criteria.
+
+Review the file: $1
+Focus areas: ${@:2}
+```
+
+Usage: `/skill:review-file src/main.ts "security" "performance"`
+
+## Validation
+
+dreb validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
+
+- Name doesn't match parent directory
+- Name exceeds 64 characters or contains invalid characters
+- Name starts/ends with hyphen or has consecutive hyphens
+- Description exceeds 1024 characters
+
+Unknown frontmatter fields are ignored.
+
+**Exception:** Skills with missing description are not loaded.
+
+Name collisions (same name from different locations) warn and keep the first skill found.
+
+## Example
+
+```
+brave-search/
+├── SKILL.md
+├── search.js
+└── content.js
+```
+
+**SKILL.md:**
+```markdown
+---
+name: brave-search
+description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
+---
+
+# Brave Search
+
+## Setup
+
+\`\`\`bash
+cd ${DREB_SKILL_DIR} && npm install
+\`\`\`
+
+## Search
+
+\`\`\`bash
+./search.js "query"              # Basic search
+./search.js "query" --content    # Include page content
+\`\`\`
+
+## Extract Page Content
+
+\`\`\`bash
+./content.js https://example.com
+\`\`\`
+```
+
+## Built-in Skills
+
+dreb ships with **mach6**, a development workflow that orchestrates the full issue-to-merge lifecycle using GitHub as shared memory. Six skills cover each stage:
+
+| Skill | What it does |
+|---|---|
+| `mach6-issue` | Assess an existing issue or create a new one |
+| `mach6-plan` | Explore codebase, plan, create branch and draft PR |
+| `mach6-push` | Commit, push, post progress comment |
+| `mach6-review` | Multi-agent code review with independent assessment |
+| `mach6-implement` | Implement plans, fix review findings, or fix CI failures |
+| `mach6-publish` | Pre-merge checks, docs update, merge, tag, release |
+
+Built-in skills are always available and can be overridden by placing a skill with the same name in any [user or project location](#locations).
+
+See [docs/mach6.md](mach6.md) for full documentation.
+
+## Skill Repositories
+
+- [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development
+- [Pi Skills](https://github.com/badlogic/pi-skills) - Web search, browser automation, Google APIs, transcription (from [pi-mono](https://github.com/badlogic/pi-mono), dreb's upstream fork)

package/docs/terminal-setup.md

@@ -0,0 +1,104 @@
+# Terminal Setup
+
+dreb uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
+
+## Kitty, iTerm2
+
+Work out of the box.
+
+## Ghostty
+
+Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
+
+```
+keybind = alt+backspace=text:\x1b\x7f
+```
+
+You may have a Ghostty mapping that sends a raw linefeed for `Shift+Enter`:
+
+```
+keybind = shift+enter=text:\n
+```
+
+This is indistinguishable from `Ctrl+J` inside dreb, so tmux and dreb can't see a real `shift+enter` key event. If you don't need this mapping for another tool, remove it.
+
+If you want `Shift+Enter` to keep working in tmux with that remap active, add `ctrl+j` to your dreb `tui.input.newLine` keybinding in `~/.dreb/agent/keybindings.json`:
+
+```json
+{
+  "tui.input.newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
+## WezTerm
+
+Create `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+## VS Code (Integrated Terminal)
+
+`keybindings.json` locations:
+- macOS: `~/Library/Application Support/Code/User/keybindings.json`
+- Linux: `~/.config/Code/User/keybindings.json`
+- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
+
+Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+## Windows Terminal
+
+Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys dreb uses:
+
+```json
+{
+  "actions": [
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+      "keys": "shift+enter"
+    },
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
+      "keys": "alt+enter"
+    }
+  ]
+}
+```
+
+- `Shift+Enter` inserts a new line.
+- Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents dreb from receiving `Alt+Enter` for follow-up queueing.
+- Remapping `Alt+Enter` to `sendInput` forwards the real key chord to dreb instead.
+
+If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
+
+## xfce4-terminal, terminator
+
+These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
+
+For the best experience, use a terminal that supports the Kitty keyboard protocol:
+- [Kitty](https://sw.kovidgoyal.net/kitty/)
+- [Ghostty](https://ghostty.org/)
+- [WezTerm](https://wezfurlong.org/wezterm/)
+- [iTerm2](https://iterm2.com/)
+- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
+
+## IntelliJ IDEA (Integrated Terminal)
+
+The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+
+If you want the hardware cursor visible, set `DREB_HARDWARE_CURSOR=1` before running dreb (disabled by default for compatibility).
+
+Consider using a dedicated terminal emulator for the best experience.

package/docs/termux.md

@@ -0,0 +1,127 @@
+# Termux (Android) Setup
+
+dreb runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android.
+
+## Prerequisites
+
+1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated)
+2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations
+
+## Installation
+
+```bash
+# Update packages
+pkg update && pkg upgrade
+
+# Install dependencies
+pkg install nodejs termux-api git
+
+# Install dreb
+npm install -g @dreb/coding-agent
+
+# Create config directory
+mkdir -p ~/.dreb/agent
+
+# Run dreb
+dreb
+```
+
+## Clipboard Support
+
+Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.
+
+Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work).
+
+## Example AGENTS.md for Termux
+
+Create `~/.dreb/agent/AGENTS.md` to help the agent understand the Termux environment:
+
+```markdown
+# Agent Environment: Termux on Android
+
+## Location
+- **OS**: Android (Termux terminal emulator)
+- **Home**: `/data/data/com.termux/files/home`
+- **Prefix**: `/data/data/com.termux/files/usr`
+- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)
+
+## Opening URLs
+```bash
+termux-open-url "https://example.com"
+```
+
+## Opening Files
+```bash
+termux-open file.pdf          # Opens with default app
+termux-open -c image.jpg      # Choose app
+```
+
+## Clipboard
+```bash
+termux-clipboard-set "text"   # Copy
+termux-clipboard-get          # Paste
+```
+
+## Notifications
+```bash
+termux-notification -t "Title" -c "Content"
+```
+
+## Device Info
+```bash
+termux-battery-status         # Battery info
+termux-wifi-connectioninfo    # WiFi info
+termux-telephony-deviceinfo   # Device info
+```
+
+## Sharing
+```bash
+termux-share -a send file.txt # Share file
+```
+
+## Other Useful Commands
+```bash
+termux-toast "message"        # Quick toast popup
+termux-vibrate                # Vibrate device
+termux-tts-speak "hello"      # Text to speech
+termux-camera-photo out.jpg   # Take photo
+```
+
+## Notes
+- Termux:API app must be installed for `termux-*` commands
+- Use `pkg install termux-api` for the command-line tools
+- Storage permission needed for `/storage/emulated/0` access
+```
+
+## Limitations
+
+- **No image clipboard**: Termux clipboard API only supports text
+- **No native binaries**: Some optional native dependencies (like the clipboard module) are unavailable on Android ARM64 and are skipped during installation
+- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions
+
+## Troubleshooting
+
+### Clipboard not working
+
+Ensure both apps are installed:
+1. Termux (from GitHub or F-Droid)
+2. Termux:API (from GitHub or F-Droid)
+
+Then install the CLI tools:
+```bash
+pkg install termux-api
+```
+
+### Permission denied for shared storage
+
+Run once to grant storage permissions:
+```bash
+termux-setup-storage
+```
+
+### Node.js installation issues
+
+If npm fails, try clearing the cache:
+```bash
+npm cache clean --force
+```