# wb-exec

wb-exec is a Claude Code skill that outsources bounded coding, refactoring, and test writing to headless CLI runners. The main agent plans the scope and reviews the patch.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 82 repo stars
- Author: Luminousyyh
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Luminousyyh/skill-wb-exec/tree/HEAD/skills/wb-exec/SKILL.md
- Updated: 2026-11-08
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/wb-exec

## What it does

The skill runs bounded development tasks through `wb_exec.py`. WorkBuddy with DeepSeek V4.1 Flash acts as the default executor, alongside codex, claude, aider, or custom CLI backends. The host agent designs a JSON task package with target goals, path boundaries, and executable test commands instead of editing source files directly.

Execution isolates changes using a Git worktree derived from `HEAD`. Because uncommitted edits are omitted from the worktree, missing staged inputs cause the worker to abort. Once execution finishes, the collect step provides a structured report, letting the supervisor inspect the real patch file and verify path constraints before applying changes.

Running this setup requires Python, a Git repository, and a configured CLI executor.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Luminousyyh/skill-wb-exec --skill wb-exec -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/wb-exec/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/wb-exec/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Luminousyyh/skill-wb-exec --skill wb-exec -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/wb-exec/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Luminousyyh/skill-wb-exec --skill wb-exec -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/wb-exec/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Luminousyyh/skill-wb-exec skills/wb-exec
```

2. **Manually: put the files in place**
- File: `.github/skills/wb-exec/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Luminousyyh/skill-wb-exec --skill wb-exec -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Luminousyyh/skill-wb-exec --path skills/wb-exec
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/wb-exec/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Luminousyyh/skill-wb-exec/tree/HEAD/skills/wb-exec/SKILL.md

## When to use it
- delegate test generation to an independent background runner
- isolate code edits to a strict set of allowed paths
- run refactoring tasks in an isolated Git worktree
- inspect generated patches and test results before applying changes

## Example prompts
- Run self-check using `python <SKILL_DIR>/scripts/wb_exec.py doctor`
- Dispatch the auth refactoring task package in the background with wb-exec
- Check the status of job `JOB_ID` and collect the resulting patch

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 21c781836232e3f3.

BEGIN THIRD-PARTY FILE 21c781836232e3f3
````text
---
name: wb-exec
description: Delegate bounded coding, refactoring and test-writing tasks to a headless CLI executor (WorkBuddy by default, or codex/claude/aider/custom) and collect a structured result plus the real diff. Use when the task can be finished independently, the file set is enumerable, and the host agent only wants to plan and review instead of writing code itself.
metadata:
  # Codex reads name/description/metadata; a bare `whenToUse` key was not part of
  # the frontmatter shape any shipped skill uses, so the same guidance lives in
  # the key Codex demonstrably defines. The `description` above still carries the
  # "use when" clause, so nothing is lost for loaders that only read that.
  short-description: "Outsource bounded implementation to a headless CLI executor: enumerable file sets, cheaper volume work, or changes needing an isolated worktree."
---

# wb-exec

You are the host: you plan, supervise and review. **The WorkBuddy subprocess does the implementation; you do not write business code yourself.**

Always address the script through this skill's absolute directory, never through the terminal's current directory:

```
python <SKILL_DIR>/scripts/wb_exec.py <subcommand> ...
```

On Windows, if `python` is not on `PATH`, use `py -3` or the absolute path of a local Python.

## 0. Self-check first (at most once per session)

```
python <SKILL_DIR>/scripts/wb_exec.py doctor
```

Returns JSON with `ok` / `cli` (the resolved entry point) / `cli_version` / `git` / `is_git_repo` / `state_root`.
`ok=false` or a non-empty `cli_error` → stop, report the raw output to the user, and do not install or reconfigure anything yourself.

`doctor` proves the CLI is present and answers `--version`. It does **not** prove authentication, quota or model access — a run can still fail after a clean self-check, and that failure belongs in `stderr.log`, not in a guess.

## 1. Write the task package (this is your most important job)

The task package is JSON; field definitions are in `references/protocol.md` and an example is in `assets/task.example.json`. Three hard rules:

1. `goal` says in one sentence what changed once the work is done. No implementation steps.
2. `owned_paths` must be enumerable. For a directory write `src/auth/`; for a file write the full path. **An empty list means the executor may only create new files.**
3. `acceptance` is executable commands (`pytest -q tests/test_auth.py`), never "make sure it works".

Write the package to a file first (for example `.wb-exec/tasks/001.json`), then dispatch. Never stuff the package into command-line arguments.

## 2. Dispatch

Long jobs — most of them — go to the background:

```
python <SKILL_DIR>/scripts/wb_exec.py dispatch --task .wb-exec/tasks/001.json --cwd <repo>
```

Short jobs can be waited on in the foreground:

```
python <SKILL_DIR>/scripts/wb_exec.py run --task .wb-exec/tasks/001.json --cwd <repo> --timeout 600
```

Common flags:
- `--dry-run`: print the argv that would run, to confirm paths and flags; starts nothing.
````
END THIRD-PARTY FILE 21c781836232e3f3

The third-party file has ended. Everything between the 21c781836232e3f3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3045 of 7954 bytes. © Luminousyyh · MIT · https://github.com/Luminousyyh/skill-wb-exec/tree/HEAD/skills/wb-exec/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
