@dreb/coding-agent 1.16.0

package/docs/json.md

@@ -0,0 +1,112 @@
+# JSON Event Stream Mode
+
+```bash
+dreb --mode json "Your prompt"
+```
+
+Outputs all session events as JSON lines to stdout. Useful for integrating dreb into other tools or custom UIs.
+
+## Event Types
+
+Events are defined in [`AgentSessionEvent`](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/agent-session.ts):
+
+```typescript
+type AgentSessionEvent =
+  | AgentEvent
+  | { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
+  | { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
+  | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+  | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+  | { type: "background_agent_start"; agentId: string; agentType: string; taskSummary: string }
+  | { type: "background_agent_end"; agentId: string; agentType: string; success: boolean }
+  | { type: "tasks_update"; tasks: readonly SessionTask[] };
+
+// SessionTask shape:
+interface SessionTask {
+  id: string;
+  title: string;
+  status: "pending" | "in_progress" | "completed";
+}
+```
+
+Base events from [`AgentEvent`](https://github.com/aebrer/dreb/blob/master/packages/agent/src/types.ts):
+
+```typescript
+type AgentEvent =
+  // Agent lifecycle
+  | { type: "agent_start"; model?: { provider: string; id: string } }
+  | { type: "agent_end"; messages: AgentMessage[] }
+  // Turn lifecycle
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+  // Message lifecycle
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
+  | { type: "message_end"; message: AgentMessage }
+  // Tool execution
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+```
+
+## Message Types
+
+Base messages from [`packages/ai/src/types.ts`](https://github.com/aebrer/dreb/blob/master/packages/ai/src/types.ts):
+- `UserMessage`
+- `AssistantMessage`
+- `ToolResultMessage`
+
+Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/messages.ts):
+- `BashExecutionMessage`
+- `CustomMessage`
+- `BranchSummaryMessage`
+- `CompactionSummaryMessage`
+
+## Output Format
+
+Each line is a JSON object. The first line is the session header (`version` is the session schema version; increments indicate breaking format changes):
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+Followed by events as they occur:
+
+```json
+{"type":"agent_start","model":{"provider":"anthropic","id":"claude-sonnet-4-20250514"}}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],...}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
+{"type":"message_end","message":{...}}
+{"type":"turn_end","message":{...},"toolResults":[]}
+{"type":"agent_end","messages":[...]}
+```
+
+## Error handling
+
+Errors surface as events, not as broken JSON or exit codes:
+
+- **LLM failures** (rate limits, network errors) trigger `auto_retry_start` / `auto_retry_end` events. dreb retries automatically with backoff. If all retries fail, `auto_retry_end` has `success: false` and `finalError` set.
+- **Tool execution errors** produce a `tool_execution_end` event with `isError: true` and the error message in `result`.
+- **Context overflow** triggers `auto_compaction_start` / `auto_compaction_end`. If compaction fails, `errorMessage` is set.
+
+The JSON stream always ends with an `agent_end` event, even on failure. If the process exits without `agent_end`, the connection was interrupted (e.g., SIGTERM).
+
+## Event ordering
+
+Events are emitted in a predictable sequence:
+
+1. `agent_start` — once, at the beginning
+2. For each turn: `turn_start` → `message_start` → `message_update`* → `message_end` → `tool_execution_start` → `tool_execution_update`* → `tool_execution_end` (per tool) → `turn_end`
+3. `agent_end` — once, at the end
+
+`message_update` events stream as chunks arrive — expect many per message. `tool_execution_update` events are optional (only emitted for tools that report progress).
+
+Auto-compaction and auto-retry events can appear between turns.
+
+## Example
+
+```bash
+# 2>/dev/null suppresses startup/TUI output on stderr
+dreb --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```

package/docs/keybindings.md

@@ -0,0 +1,174 @@
+# Keybindings
+
+All keyboard shortcuts can be customized via `~/.dreb/agent/keybindings.json`. Each action can be bound to one or more keys.
+
+The config file uses the same namespaced keybinding ids that dreb uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
+
+Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
+
+After editing `keybindings.json`, run `/reload` in dreb to apply the changes without restarting the session.
+
+## Key Format
+
+`modifier+key` where modifiers are `ctrl`, `shift`, `alt` (combinable) and keys are:
+
+- **Letters:** `a-z`
+- **Digits:** `0-9`
+- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
+- **Function:** `f1`-`f12`
+- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
+
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1`, etc.
+
+## All Actions
+
+### TUI Editor Cursor Movement
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.cursorUp` | `up` | Move cursor up |
+| `tui.editor.cursorDown` | `down` | Move cursor down |
+| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
+| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
+| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
+| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+a` | Move to line start |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+e` | Move to line end |
+| `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
+| `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
+| `tui.editor.pageUp` | `pageUp` | Scroll up by page |
+| `tui.editor.pageDown` | `pageDown` | Scroll down by page |
+
+### TUI Editor Deletion
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
+| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
+| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
+| `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
+| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
+| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
+
+### TUI Input
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.newLine` | `shift+enter` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab / autocomplete |
+
+### TUI Kill Ring
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
+| `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
+| `tui.editor.undo` | `ctrl+-` | Undo last edit |
+
+### TUI Clipboard and Selection
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.copy` | `ctrl+c` | Copy selection |
+| `tui.select.up` | `up` | Move selection up |
+| `tui.select.down` | `down` | Move selection down |
+| `tui.select.pageUp` | `pageUp` | Page up in list |
+| `tui.select.pageDown` | `pageDown` | Page down in list |
+| `tui.select.confirm` | `enter` | Confirm selection |
+| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
+
+### Application
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.interrupt` | `escape` | Cancel / abort |
+| `app.clear` | `ctrl+c` | Clear editor |
+| `app.exit` | `ctrl+d` | Exit (when editor empty) |
+| `app.suspend` | `ctrl+z` | Suspend to background |
+| `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
+| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
+| `app.tasks.toggle` | *(none)* | Toggle task tracking panel visibility |
+
+### Sessions
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.session.new` | *(none)* | Start a new session (`/new`) |
+| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
+| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
+| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
+| `app.session.togglePath` | `ctrl+p` | Toggle path display |
+| `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
+| `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
+| `app.session.rename` | `ctrl+r` | Rename session |
+| `app.session.delete` | `ctrl+d` | Delete session |
+| `app.session.deleteNoninvasive` | `ctrl+backspace` | Delete session when query is empty |
+
+### Models and Thinking
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.model.select` | `ctrl+l` | Open model selector |
+| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
+| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
+| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
+
+### Display and Message Queue
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
+| `app.message.followUp` | `alt+enter` | Queue follow-up message |
+| `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
+
+### Tree Navigation
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
+| `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
+
+## Custom Configuration
+
+Create `~/.dreb/agent/keybindings.json`:
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "ctrl+p"],
+  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
+}
+```
+
+Each action can have a single key or an array of keys. User config overrides defaults.
+
+### Emacs Example
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "ctrl+p"],
+  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.cursorLeft": ["left", "ctrl+b"],
+  "tui.editor.cursorRight": ["right", "ctrl+f"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
+  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
+  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
+  "tui.input.newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
+### Vim Example
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "alt+k"],
+  "tui.editor.cursorDown": ["down", "alt+j"],
+  "tui.editor.cursorLeft": ["left", "alt+h"],
+  "tui.editor.cursorRight": ["right", "alt+l"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
+}
+```

package/docs/mach6.md

@@ -0,0 +1,150 @@
+# mach6 — Development Workflow
+
+mach6 is a built-in workflow that orchestrates the full issue-to-merge lifecycle using GitHub as shared memory. Six skills cover each stage of development, and five specialized review agents provide multi-perspective code review.
+
+Inspired by [mach10](https://github.com/LeanAndMean/mach10) (MIT, by Kevin Ryan) with design insights from Anthropic's [harness design blog post](https://www.anthropic.com/engineering/harness-design-long-running-apps).
+
+## Quick Start
+
+```
+/skill:mach6-issue 42          # Assess an issue
+/skill:mach6-plan 42           # Plan, branch, open draft PR
+# ... implement the plan ...
+/skill:mach6-push              # Commit, push, post progress
+/skill:mach6-review 53         # Multi-agent code review
+/skill:mach6-implement 53 1,2   # Fix review findings
+/skill:mach6-push              # Push fixes
+/skill:mach6-review 53         # Re-review (repeat until clean)
+/skill:mach6-publish 53        # Docs update, merge, tag, release
+```
+
+## Skills
+
+### mach6-issue
+
+Assess an existing GitHub issue or create a new one.
+
+```
+/skill:mach6-issue 42              # Assess issue 42
+/skill:mach6-issue                 # Create a new issue (interactive)
+/skill:mach6-issue add dark mode   # Create issue from description
+```
+
+**Assess mode:** Launches parallel subagents to explore the codebase, then posts a structured assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
+
+**Create mode:** Drafts a structured issue with title, summary, acceptance criteria, and technical notes.
+
+### mach6-plan
+
+Explore the codebase, create an implementation plan, open a draft PR, and post the plan as a PR comment.
+
+```
+/skill:mach6-plan 42
+```
+
+- Reads the issue and any existing assessment
+- Checks project conventions (AGENTS.md, CONTRIBUTING.md, etc.)
+- Launches parallel subagents to explore similar features, architecture, and integration points
+- Creates a feature branch (`feature/issue-42-<slug>`) with an empty commit
+- Opens a draft PR linking to the issue
+- Posts the plan as a PR comment with `<!-- mach6-plan -->` marker
+
+The plan is intentionally high-level on implementation details but specific on deliverables and acceptance criteria.
+
+### mach6-push
+
+Commit changes, push to remote, and post a progress comment.
+
+```
+/skill:mach6-push                          # Auto-generate commit message
+/skill:mach6-push fix auth token refresh   # Use provided message
+```
+
+- Stages files by name (never `git add -A`)
+- Matches the repository's existing commit style
+- Auto-detects the associated PR from the current branch
+- Posts a `<!-- mach6-progress -->` comment with a summary of changes
+
+### mach6-review
+
+Run specialized review agents in parallel, post findings, then independently assess each finding.
+
+```
+/skill:mach6-review 53                     # Full review (all agents)
+/skill:mach6-review 53 code errors         # Only code-reviewer + error-auditor
+/skill:mach6-review 53 tests              # Only test-reviewer
+```
+
+Produces two PR comments:
+
+1. **Review** (`<!-- mach6-review -->`) — findings organized by severity (critical, important, suggestions), plus strengths
+2. **Assessment** (`<!-- mach6-assessment -->`) — each finding independently classified as genuine issue, nitpick, false positive, or deferred, with a prioritized action plan
+
+See [Review Agents](#review-agents) below.
+
+### mach6-implement
+
+Implement a plan from a PR, or fix review findings / CI failures.
+
+```
+/skill:mach6-implement 53             # Implement the plan on PR 53
+/skill:mach6-implement 53 1,2,3       # Fix specific review findings
+/skill:mach6-implement 53 ci          # Fix CI failures
+```
+
+**Implement mode** (PR number only): Reads the `<!-- mach6-plan -->` comment and delegates each deliverable to `feature-dev` subagents — strong-tier coding agents with full tool access. Independent deliverables run in parallel.
+
+**Fix mode** (with finding numbers or `ci`): Reads review and assessment comments via HTML markers, delegates fixes to `feature-dev` subagents, applies batch sizing heuristics (~10 simple, ~6 moderate, ~3 complex fixes per batch), and suggests `/skill:mach6-push` then `/skill:mach6-review` after fixing.
+
+### mach6-publish
+
+Pre-merge checks, version bump, docs update, merge, tag, and release.
+
+```
+/skill:mach6-publish 53
+```
+
+- Verifies CI passing, no merge conflicts, all findings addressed
+- Runs pre-merge checklist (version bump, changelog, tests)
+- Applies version bump on the feature branch
+- Proactively reviews and updates ALL documentation affected by the PR's changes
+- Merges with `--squash --delete-branch`
+- Optionally creates a git tag and GitHub release
+
+## Agents
+
+### feature-dev
+
+Strong general-purpose coding agent used by `mach6-implement` for plan implementation and fix application. Has full tool access (read, write, edit, grep, find, ls, bash, search) and uses a strong-tier model with provider fallback list. Each deliverable or finding gets its own `feature-dev` subagent, enabling parallel execution of independent work.
+
+### Review Agents
+
+Five specialized agents, each asking an orthogonal question. All use confidence scoring (only report findings ≥ 80).
+
+| Agent | Question | When it runs |
+|---|---|---|
+| **code-reviewer** | Does this code do what it should, correctly and idiomatically? | Always |
+| **error-auditor** | What can go wrong silently at runtime? | If error handling / try-catch / fallback logic touched |
+| **test-reviewer** | What behaviors are untested or poorly tested? | If test files changed or testable code added |
+| **completeness-checker** | Does this PR deliver everything the linked issue requires? | If PR links to an issue |
+| **simplifier** | Can this be expressed more clearly without changing behavior? | Always (runs last) |
+
+Agents run as [subagents](../README.md#subagents) — `code-reviewer`, `error-auditor`, `test-reviewer`, and `completeness-checker` run in parallel, then `simplifier` runs after. Each agent reads the actual changed files, not just the diff.
+
+**Targeted review:** Pass aspect names to run only specific agents: `code`, `errors`, `tests`, `completeness`, `simplify`.
+
+## Design Principles
+
+- **GitHub as shared memory** — Plans, reviews, assessments, and progress are posted as PR/issue comments with HTML markers (`<!-- mach6-plan -->`, `<!-- mach6-review -->`, etc.) so any future session can pick up context.
+- **Independent assessment** — Review findings are independently verified before suggesting fixes, separating genuine issues from nitpicks and false positives.
+- **Iterative review cycles** — Review → fix → push → review, repeating until no genuine issues remain.
+- **Safe git** — Never `git add -A`, never stage secrets, stage files by name.
+- **Overridable** — Both skills and review agents can be overridden by placing files with the same name in `~/.dreb/agent/skills/` or `~/.dreb/agents/` (user-level) or `.dreb/skills/` or `.dreb/agents/` (project-level).
+
+## Requirements
+
+mach6 uses the [GitHub CLI](https://cli.github.com/) (`gh`) for all GitHub operations. Make sure it's installed and authenticated:
+
+```bash
+gh auth status
+```