From be3a5e47bb569f97f74d4601be6c22b4e2eb16a0 Mon Sep 17 00:00:00 2001 From: Duncan McKinnon Date: Tue, 11 Aug 2026 11:28:38 -0700 Subject: [PATCH] Document claude-yolo adapter and plan-workbench skill (workbench#62, #63, #64) Syncs the docs with three workbench changes that landed after the Kimi sync: - claude-yolo adapter (workbench#63): eight built-in adapters now, and the agent table carries an explicit --agent name column. Adds a Permission modes section contrasting claude's tool allowlist, claude-yolo's --dangerously-skip-permissions, and codex's bypass flags (workbench#64), which is why Codex tasks can commit their own work. claude-yolo also overlays ANTHROPIC_BASE_URL under headroom. - plan-workbench skill (workbench#62): use-workbench was split into plan authoring (plan-workbench) and run execution (use-workbench). Five skills now; plan-authoring prose moves under plan-workbench and use-workbench is rewritten around running, resuming, and troubleshooting. - bundle-skill.sh fetched only three skills, so the download zip was missing generate-conventions as well as plan-workbench. Also refreshes the wb setup sample output (setup discovers all bundled skills and prompts for selection) and replaces two stale "Gemini CLI" agent lists in the landing metadata and llms.txt. Co-Authored-By: Claude Opus 5 --- app/(marketing)/page.tsx | 2 +- app/llms.txt/route.ts | 2 +- content/docs/agents.mdx | 40 +++++++++++++++++++++----------- content/docs/cli-reference.mdx | 2 +- content/docs/getting-started.mdx | 20 +++++++++++++--- content/docs/plan-format.mdx | 2 +- content/docs/skills.mdx | 34 ++++++++++++++++++++------- scripts/bundle-skill.sh | 2 +- 8 files changed, 74 insertions(+), 30 deletions(-) diff --git a/app/(marketing)/page.tsx b/app/(marketing)/page.tsx index 123cb1c..53ecd84 100644 --- a/app/(marketing)/page.tsx +++ b/app/(marketing)/page.tsx @@ -7,7 +7,7 @@ import { CodeExample } from "@/components/landing/code-example"; export const metadata: Metadata = { title: "workbench — Ultra-lightweight multi-agent orchestrator", description: - "Dispatch AI coding agents in parallel across isolated git worktrees. Supports Claude Code, Gemini CLI, and Codex.", + "Dispatch AI coding agents in parallel across isolated git worktrees. Supports Claude Code, Antigravity, OpenCode, Kimi Code, Codex, Cursor, and Copilot.", }; export default function LandingPage() { diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.ts index 486209f..c23d630 100644 --- a/app/llms.txt/route.ts +++ b/app/llms.txt/route.ts @@ -13,7 +13,7 @@ export function GET() { > Ultra-lightweight multi-agent orchestrator for any setup. Write a plan. Run one command. AI agents build your code in parallel — across isolated git worktrees. -workbench (\`wbcli\` on PyPI) is a Python CLI that dispatches AI coding agents in parallel across isolated git worktrees. Users write markdown plans with tasks, dependencies, and file ownership; workbench parses the plan into dependency waves, creates isolated worktrees, and runs each task through an implement → test → review → fix pipeline. Supports Claude Code, Gemini CLI, OpenAI Codex, Cursor CLI, and custom agent adapters. +workbench (\`wbcli\` on PyPI) is a Python CLI that dispatches AI coding agents in parallel across isolated git worktrees. Users write markdown plans with tasks, dependencies, and file ownership; workbench parses the plan into dependency waves, creates isolated worktrees, and runs each task through an implement → test → review → fix pipeline. Supports Claude Code (standard and permission-bypassing \`claude-yolo\`), Google Antigravity, OpenCode, Kimi Code, OpenAI Codex, Cursor CLI, GitHub Copilot CLI, and custom agent adapters. ## Documentation diff --git a/content/docs/agents.mdx b/content/docs/agents.mdx index 0439904..30820d5 100644 --- a/content/docs/agents.mdx +++ b/content/docs/agents.mdx @@ -6,17 +6,18 @@ order: 6 ## Supported Agents -Workbench ships with built-in adapters for seven agent CLIs, plus support for any custom CLI: - -| Agent | Command | Provider | -|---|---|---| -| Claude Code | `claude` | Anthropic | -| Google Antigravity | `agy` | Google | -| OpenCode | `opencode` | OpenCode | -| Kimi Code | `kimi` | Moonshot AI | -| OpenAI Codex | `codex` | OpenAI | -| Cursor CLI | `agent` | Cursor | -| Copilot CLI | `copilot` | GitHub | +Workbench ships with built-in adapters for eight agent CLIs, plus support for any custom CLI: + +| Agent | `--agent` name | Command | Provider | +|---|---|---|---| +| Claude Code | `claude` | `claude` | Anthropic | +| Claude Code (YOLO) | `claude-yolo` | `claude` | Anthropic | +| Google Antigravity | `antigravity` | `agy` | Google | +| OpenCode | `opencode` | `opencode` | OpenCode | +| Kimi Code | `kimi` | `kimi` | Moonshot AI | +| OpenAI Codex | `codex` | `codex` | OpenAI | +| Cursor CLI | `cursor` | `agent` | Cursor | +| Copilot CLI | `copilot` | `copilot` | GitHub | Each agent goes through the same pipeline stages: **implement → test → review → fix**. Workbench treats all agents as interchangeable — any agent can fill any role. @@ -24,6 +25,7 @@ Use `--agent` to select which agent to use: ```bash wb run plan.md --agent claude # default +wb run plan.md --agent claude-yolo # Claude Code with permission checks bypassed wb run plan.md --agent antigravity wb run plan.md --agent opencode wb run plan.md --agent kimi @@ -32,6 +34,18 @@ wb run plan.md --agent cursor wb run plan.md --agent copilot ``` +### Permission modes + +Dispatched agents run unattended, so each adapter pins a non-interactive permission posture: + +| Adapter | Posture | +|---|---| +| `claude` | Restricted allowlist — `Edit`, `Write`, `Read`, `Glob`, `Grep`, plus `git`, `uv run`, `cd`, `ls`, and `npx` shell commands | +| `claude-yolo` | Same CLI, invoked with `--dangerously-skip-permissions` — no tool allowlist at all | +| `codex` | Invoked as `codex exec --dangerously-bypass-approvals-and-sandbox --json`, so Codex tasks can commit their own work | + +Reach for `claude-yolo` when a task needs tools outside the default allowlist — installing packages, running an unusual test harness, or driving a build script — and you trust the plan's tasks. It is the same `claude` binary, so authentication, models, and cost reporting behave identically. + ## Setting Up Agents Use `wb setup` to install agent skill files for your platform: @@ -67,7 +81,7 @@ wb agents add my-agent --command new-cli # update an existing agent wb agents remove my-agent # remove a custom agent ``` -`wb agents init` creates `.workbench/agents.yaml` pre-populated with the configs for all built-in adapters (Claude, Antigravity, OpenCode, Kimi, Codex, Cursor, Copilot). Use this as a starting point to customize command flags, output parsing, or to add your own agents. +`wb agents init` creates `.workbench/agents.yaml` pre-populated with the configs for all built-in adapters (Claude, Claude YOLO, Antigravity, OpenCode, Kimi, Codex, Cursor, Copilot). Use this as a starting point to customize command flags, output parsing, or to add your own agents. ### Plan-scoped agents @@ -201,7 +215,7 @@ agents: - **One shared proxy per `wb run`** — not one per agent. - **Auto-start** if nothing is listening on `port`; **reuse** an existing listener if there is one. - **Teardown** only what workbench started — an existing proxy keeps running. -- **Wired today:** `claude` (overlays `ANTHROPIC_BASE_URL`) and `codex` (overlays `OPENAI_BASE_URL`). +- **Wired today:** `claude` and `claude-yolo` (overlay `ANTHROPIC_BASE_URL`) and `codex` (overlays `OPENAI_BASE_URL`). - **Other adapters** run normally with a one-time warning until their base-URL overrides are verified. - **Missing binary?** Workbench logs a warning with the install hint and continues — a run never fails over a cost optimization. diff --git a/content/docs/cli-reference.mdx b/content/docs/cli-reference.mdx index 1ab24fd..4df0403 100644 --- a/content/docs/cli-reference.mdx +++ b/content/docs/cli-reference.mdx @@ -51,7 +51,7 @@ wb run [options] | `--skip-test` | Skip the test phase | | `--skip-review` | Skip the review phase | | `--tdd` | Test-driven: write tests first, then implement | -| `--agent CMD` | Agent CLI command (default: `claude`) | +| `--agent CMD` | Agent CLI command (default: `claude`). Built-in names: `claude`, `claude-yolo`, `antigravity`, `opencode`, `kimi`, `codex`, `cursor`, `copilot`, or any custom agent from `agents.yaml` | | `--no-tmux` | Run agents as subprocesses instead of tmux | | `--name NAME` | Name for the session branch (default: `workbench-N`) | | `--base BRANCH` | Base branch to start from (default: `main`) | diff --git a/content/docs/getting-started.mdx b/content/docs/getting-started.mdx index 8ed6257..2750771 100644 --- a/content/docs/getting-started.mdx +++ b/content/docs/getting-started.mdx @@ -73,14 +73,28 @@ If you have multiple agent platforms installed, workbench will ask you to choose $ wb setup Multiple agent platforms found. Choose one (claude, antigravity): claude Created /path/to/your/project/.workbench/ -Installing 1 command(s) for claude... +Available skill file(s) for claude: + • configure-workbench + • generate-conventions + • install-workbench + • plan-workbench + • use-workbench + +Install all skills? [Y/n]: y + +Installing 5 skill file(s) for claude... + + Copied /configure-workbench → /path/to/your/project/.claude/skills/configure-workbench + Copied /generate-conventions → /path/to/your/project/.claude/skills/generate-conventions + Copied /install-workbench → /path/to/your/project/.claude/skills/install-workbench + Copied /plan-workbench → /path/to/your/project/.claude/skills/plan-workbench Copied /use-workbench → /path/to/your/project/.claude/skills/use-workbench - Use in Claude Code: /use-workbench + Use in Claude Code: /plan-workbench Also installed to /path/to/your/project/.agents/skills for cross-client discoverability. -Done. Installed 1 command(s) for claude. +Done. Installed 5 skill file(s) for claude. Repo is ready for workbench. ``` diff --git a/content/docs/plan-format.mdx b/content/docs/plan-format.mdx index 7cba4fe..e516fdc 100644 --- a/content/docs/plan-format.mdx +++ b/content/docs/plan-format.mdx @@ -15,7 +15,7 @@ Plans are referenced by **name**. `wb run myfeature` resolves to `.workbench/myf > **Tip:** You don't have to write plans by hand. Two options: > > - **`wb plan ""`** — dispatches a planner agent from the CLI. Generates a plan at `.workbench/plan/plan.md`. Can also transform an existing document with `--from`. See [CLI Reference](/docs/cli-reference#wb-plan). -> - **`/use-workbench` skill** — runs inside your agent session. Describe what you want to build and the agent produces a ready-to-run plan. See [Skills](/docs/skills#use-workbench). +> - **`/plan-workbench` skill** — runs inside your agent session. Describe what you want to build and the agent produces a ready-to-run plan. See [Skills](/docs/skills#plan-workbench). > > Both paths survey your codebase, design the task graph, and produce a plan in the format described below. diff --git a/content/docs/skills.mdx b/content/docs/skills.mdx index c388025..ae36e5f 100644 --- a/content/docs/skills.mdx +++ b/content/docs/skills.mdx @@ -10,17 +10,20 @@ order: 8 ## What Are Skills? -Skills are instruction files that teach your AI coding agent how to work with workbench. When installed, your agent can automatically install workbench, configure agents and profiles, and write execution plans — all from natural language prompts. +Skills are instruction files that teach your AI coding agent how to work with workbench. When installed, your agent can automatically install workbench, configure agents and profiles, write execution plans, and drive the runs that execute them — all from natural language prompts. -Workbench ships four skills: +Workbench ships five skills: | Skill | Trigger | What it does | |---|---|---| | `install-workbench` | "Install workbench", "set up wb" | Guides the agent through prerequisites, installation, and `wb setup` | | `configure-workbench` | "Configure agents", "set up profiles" | Helps configure agent adapters, profiles, and troubleshoot dispatch | -| `use-workbench` | "Write a plan", `/use-workbench` | Converts your ideas into workbench plans with proper task graphs | +| `plan-workbench` | "Write a plan", `/plan-workbench` | Converts your ideas into workbench plans with proper task graphs | +| `use-workbench` | "Run this plan", `/use-workbench` | Runs, resumes, and troubleshoots `wb` execution of an existing plan | | `generate-conventions` | "Generate conventions", `wb conventions init --generate` | Scans the codebase to draft `.workbench/conventions.md` shared by every agent | +> **Writing vs. running:** these were one skill until workbench split them. `plan-workbench` owns the plan file — structure, frontmatter, task decomposition, file ownership. `use-workbench` owns execution — pipeline stages, waves, failure recovery, TDD mode. `wb plan` uses `plan-workbench` as its planning guide, so the CLI and the skill produce plans the same way. + ## Installing Skills from the Download If you don't have workbench installed yet, you can bootstrap the process by downloading the skills and placing them manually. Your agent will then use the `install-workbench` skill to guide you through the rest. @@ -42,6 +45,8 @@ This creates: │ └── SKILL.md ├── configure-workbench/ │ └── SKILL.md +├── plan-workbench/ +│ └── SKILL.md ├── use-workbench/ │ └── SKILL.md └── generate-conventions/ @@ -54,6 +59,7 @@ This creates: mkdir -p .claude/skills cp -r .agents/skills/install-workbench .claude/skills/ cp -r .agents/skills/configure-workbench .claude/skills/ +cp -r .agents/skills/plan-workbench .claude/skills/ cp -r .agents/skills/use-workbench .claude/skills/ cp -r .agents/skills/generate-conventions .claude/skills/ ``` @@ -117,15 +123,15 @@ Ask your agent to draft a shared conventions file for the repo: The skill backs `wb conventions init --generate`: it surveys the codebase, captures language, framework, tooling, and style decisions, and writes the result to `.workbench/conventions.md`. Every workbench agent then loads that file automatically so plans and tasks share the same ground rules. See [Conventions](/docs/conventions) for the full file format. -### use-workbench +### plan-workbench **From an idea:** Ask your agent to write a plan from scratch: > "Write a workbench plan to add authentication to this app" -> `/use-workbench` +> `/plan-workbench` -The agent will survey your codebase, design a task graph with proper dependencies and file ownership, and produce a ready-to-run plan. +The agent will survey your codebase, design a task graph with proper dependencies and file ownership, and produce a ready-to-run plan at `.workbench//plan.md`. **From an existing plan:** You can also point the skill at an existing plan or spec to restructure it for workbench execution. This is useful when you have a rough plan, a design doc, or an implementation spec that isn't yet formatted for parallel agent dispatch: @@ -135,12 +141,22 @@ The agent will survey your codebase, design a task graph with proper dependencie The agent reads the existing document, identifies independent units of work, determines file ownership to avoid merge conflicts, sets up dependency ordering across waves, and fills in the detail each task needs to be self-contained — function signatures, interfaces from earlier tasks, test commands, and edge cases. The result is a plan at the right level of specificity for agents that can only see their own task description. -**Running the plan:** Once a plan is ready, the skill can also generate the `wb run` command with the right flags for your situation — TDD mode, specific base branches, named sessions, agent selection, directive overrides, and more: +**CLI alternative:** If you prefer to generate a plan from the command line rather than from inside an agent session, use `wb plan ""` or `wb plan --from `. This dispatches a planner agent using the same `plan-workbench` guidance, but without needing an active agent session. See [CLI Reference](/docs/cli-reference#wb-plan). + +See [Plan Format](/docs/plan-format) for details on the structure it generates. + +### use-workbench + +**Running a plan:** Once a plan is ready, this skill generates the `wb run` command with the right flags for your situation — TDD mode, specific base branches, named sessions, agent selection, directive overrides, and more: > "Run this plan with Antigravity for implementation and Claude for review" > "Run plan.md in TDD mode on the feature-auth branch" -**CLI alternative:** If you prefer to generate a plan from the command line rather than from inside an agent session, use `wb plan ""` or `wb plan --from `. This dispatches a planner agent the same way the skill does, but without needing an active agent session. See [CLI Reference](/docs/cli-reference#wb-plan). +**Resuming and troubleshooting:** It also covers what to do when a run doesn't finish cleanly — which failures `wb resume` can pick up, how waves and branches are reused, and how to read the pipeline stages: + +> "Wave 2 failed on the tester stage — how do I resume it?" + +> "Why did my run stop after the first wave?" -See [Plan Format](/docs/plan-format) for details on the structure it generates. \ No newline at end of file +See [Running Plans](/docs/running-plans) and [TDD Mode](/docs/tdd-mode) for the underlying behavior. \ No newline at end of file diff --git a/scripts/bundle-skill.sh b/scripts/bundle-skill.sh index 209c82c..4ed402c 100755 --- a/scripts/bundle-skill.sh +++ b/scripts/bundle-skill.sh @@ -6,7 +6,7 @@ set -e REPO="duncankmckinnon/workbench" BRANCH="main" BASE_URL="https://raw.githubusercontent.com/${REPO}/${BRANCH}/workbench/skills" -SKILLS=("use-workbench" "configure-workbench" "install-workbench") +SKILLS=("plan-workbench" "use-workbench" "configure-workbench" "install-workbench" "generate-conventions") TMPDIR=$(mktemp -d) trap "rm -rf $TMPDIR" EXIT