{"id":47727007,"url":"https://github.com/duncankmckinnon/workbench","last_synced_at":"2026-05-09T02:24:56.070Z","repository":{"id":347683382,"uuid":"1194796041","full_name":"duncankmckinnon/workbench","owner":"duncankmckinnon","description":"Ultra-lightweight multi-agent orchestrator anywhere you work","archived":false,"fork":false,"pushed_at":"2026-04-18T20:30:35.000Z","size":387,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-18T22:33:15.314Z","etag":null,"topics":["agents","cli","coding-agent","harness","multi-agent"],"latest_commit_sha":null,"homepage":"https://www.wbcli.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duncankmckinnon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T20:30:58.000Z","updated_at":"2026-04-18T20:07:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/duncankmckinnon/workbench","commit_stats":null,"previous_names":["duncankmckinnon/workbench"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/duncankmckinnon/workbench","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncankmckinnon%2Fworkbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncankmckinnon%2Fworkbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncankmckinnon%2Fworkbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncankmckinnon%2Fworkbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duncankmckinnon","download_url":"https://codeload.github.com/duncankmckinnon/workbench/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncankmckinnon%2Fworkbench/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32143674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T15:33:03.595Z","status":"ssl_error","status_checked_at":"2026-04-22T15:30:42.712Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","cli","coding-agent","harness","multi-agent"],"created_at":"2026-04-02T20:47:27.560Z","updated_at":"2026-05-09T02:24:56.063Z","avatar_url":"https://github.com/duncankmckinnon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Workbench\n\n[![CI](https://github.com/duncankmckinnon/workbench/actions/workflows/ci.yml/badge.svg)](https://github.com/duncankmckinnon/workbench/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/duncankmckinnon/workbench/graph/badge.svg)](https://codecov.io/gh/duncankmckinnon/workbench)\n[![PyPI](https://img.shields.io/pypi/v/wbcli?v=2)](https://pypi.org/project/wbcli/)\n[![Homebrew](https://img.shields.io/badge/homebrew-duncankmckinnon%2Ftap-orange?logo=homebrew)](https://github.com/duncankmckinnon/homebrew-tap)\n[![Python](https://img.shields.io/pypi/pyversions/wbcli?v=3)](https://pypi.org/project/wbcli/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nMulti-agent orchestrator that dispatches AI coding agents in parallel across isolated git worktrees.\n\nWrite a markdown plan, run `wb run plan.md`, and workbench parses it into tasks, groups them into dependency waves, and runs each task through an **implement → test → review → fix** pipeline.\n\n## Requirements\n\n**Required:**\n\n- **Python 3.11+**\n  - macOS: `brew install python` or [python.org](https://www.python.org/downloads/)\n  - Linux: `apt install python3` / `dnf install python3`\n  - Windows: [python.org](https://www.python.org/downloads/) or `winget install Python.Python.3.13`\n\n- **Git**\n  - macOS: `xcode-select --install` or `brew install git`\n  - Linux: `apt install git` / `dnf install git`\n  - Windows: [git-scm.com](https://git-scm.com/downloads) or `winget install Git.Git`\n\n- **An agent CLI** — at least one of:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (default)\n  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n  - [Codex](https://github.com/openai/codex)\n  - [Cursor CLI](https://cursor.com/docs/cli/overview)\n  - [Copilot CLI](https://github.com/features/copilot/cli)\n  - Any custom CLI via `.workbench/agents.yaml`\n\n**Optional:**\n\n- **tmux** — enables live monitoring of agent sessions. Use `--no-tmux` to run without it.\n  - macOS: `brew install tmux`\n  - Linux: `apt install tmux` / `dnf install tmux`\n  - Windows: available via WSL\n\n## Install\n\n```bash\npip install wbcli\n```\n\n## Getting started\n\n### 1. Set up your repo\n\n```bash\nwb setup\n```\n\nThis creates a `.workbench/` directory in your repo and installs the bundled skill file for your agent platform. The skill teaches your agent how to write effective workbench plans and use the CLI to configure and execute them.\n\n```bash\nwb setup                           # auto-detect agent, install skills locally\nwb setup --agent claude            # install to \u003crepo\u003e/.claude/skills/ + .agents/skills/\nwb setup --agent gemini            # install to \u003crepo\u003e/.agents/skills/\nwb setup --agent manual            # print paths for manual setup\nwb setup --global                  # install skills to user-level paths only (no .workbench/)\nwb setup --global --agent claude   # install to ~/.claude/skills/\nwb setup --global --agent gemini   # install to ~/.agents/skills/\nwb setup --symlink                 # symlink instead of copy (stays in sync with updates)\nwb setup --update                  # force-update skills to the latest installed version\nwb setup --profile                 # also create a profile.yaml with the detected agent\n```\n\nIf the skill file already exists and is unchanged, it's skipped. If it differs, you'll be prompted before overwriting. Use `--update` to force-overwrite.\n\n### 2. Write a plan\n\nYou can generate a plan automatically or write one by hand.\n\n**Generate with `wb plan`:**\n\n```bash\nwb plan \"Add JWT authentication to the FastAPI app\"\nwb plan \"Refactor the database layer\" --name db-refactor\nwb plan --from existing-spec.md\nwb plan \"Focus on security\" --from claude-plan.md --name secure-auth\n```\n\nThe planner agent explores your codebase — reading project structure, existing patterns, test infrastructure, and conventions — then writes a detailed plan to `.workbench/plans/\u003cname\u003e.md`. On completion it prints commands for reviewing, previewing, and running the result.\n\nUse `--from` to transform an existing document (e.g. a Claude plan, a spec, or rough notes) into workbench format. Add a prompt alongside `--from` for additional guidance on the transformation.\n\n**Write by hand:**\n\nCreate a markdown file (e.g. `plan.md`) with tasks for workbench to execute:\n\n```markdown\n# Plan title\n\n## Context\n\n\u003cBackground about the project, what's being built, and why.\nInjected into every agent's prompt so each task has full context.\u003e\n\n## Conventions\n\n\u003cProject-specific patterns agents must follow: language version,\ntest framework, import style, naming conventions, etc.\nAlso injected into every agent's prompt.\u003e\n\n## Task: Short title\nFiles: path/to/file.py, path/to/other.py\n\n\u003cDetailed description of what to implement. Each task runs in an\nisolated git worktree — the agent only sees this description,\nnot the rest of the plan. Be specific and self-contained.\u003e\n\n## Task: Another task\nFiles: path/to/different.py\nDepends: short-title\n\n\u003cThis task depends on \"Short title\" (referenced by its slug).\nIt won't start until the dependency completes. Describe the\ninterfaces from the earlier task that this task needs.\u003e\n```\n\n**Plan sections:**\n\n| Section | Purpose |\n|---|---|\n| `# Title` | Plan name (shown in status output) |\n| `## Context` | Project background — injected into every agent's prompt |\n| `## Conventions` | Code style rules — injected into every agent's prompt |\n| `## Task: \u003ctitle\u003e` | A unit of work, becomes an independent agent session |\n| `Files:` | File ownership — prevents parallel tasks from conflicting |\n| `Depends:` | Task slugs this depends on (title → lowercase, non-alphanumeric → `-`) |\n\nTasks without dependencies run in the earliest wave. Keep titles short (2-4 words) — they become dependency slugs.\n\nUse `wb preview plan.md` to dry-run and verify tasks and waves before executing.\n\n### Plan frontmatter (optional)\n\nPlans can declare run-time defaults in a YAML frontmatter block at the top of the file (before `# Title`). Without frontmatter, plans behave exactly as today.\n\n```markdown\n---\nsession_branch: workbench-auth\nbase: feature-auth\ntdd: true\nmax_concurrent: 6\n---\n# Auth refactor\n\n## Context\n...\n```\n\nCLI flags always override frontmatter values. See [Frontmatter-readable flags](#frontmatter-readable-flags) in the CLI reference for the full schema.\n\n### 3. Run the plan\n\n```bash\nwb run plan.md\n```\n\nWorkbench parses the plan, groups tasks into dependency waves, creates isolated git worktrees, and dispatches agents in parallel. Each task goes through:\n\n```\nimplement → test → fix  → review → fix (retry up to --max-retries)\n```\n\nAfter each wave, successful task branches are merged into a session branch (`workbench-N`). Merge conflicts between parallel branches are automatically resolved by a merger agent. Task outcomes are tracked in `.workbench/status-\u003cplan\u003e.yaml` as each task completes, keyed by session branch.\n\nUse `--push` to push the session branch to origin when done:\n\n```bash\nwb run plan.md --push\n```\n\n### 4. Control which waves run\n\nBy default, all waves run sequentially. Use wave flags to run a subset:\n\n```bash\nwb run plan.md -w 2                          # run only wave 2\nwb run plan.md --start-wave 2                # run waves 2 through end\nwb run plan.md --start-wave 2 --end-wave 4   # run waves 2 through 4\n```\n\nOut-of-range values are clamped automatically: `--start-wave` defaults to 1 and `--end-wave` defaults to the last wave, with a warning printed.\n\n### 5. Handle failures\n\nIf some tasks fail, you have options:\n\n```bash\n# Resume a session: re-run every task that isn't done + merged\nwb resume workbench-1\n\n# Same thing, manual form (use this if you need to override flags)\nwb run plan.md -b workbench-1 --only-incomplete\n\n# Auto-retry tasks that crashed (not those that exhausted fix retries)\nwb run plan.md --retry-failed\n\n# Stop immediately if any task in a wave fails\nwb run plan.md --fail-fast\n\n# Combine: retry crashes, then stop if still failing\nwb run plan.md --retry-failed --fail-fast\n```\n\n`wb resume \u003csession\u003e` looks up the session in `.workbench/status-*.yaml`, finds the original plan, and re-runs every task that isn't `done + merged`. This includes tasks that failed AND tasks that never started (e.g., a crash before the wave reached them — the status file is seeded with every plan task as `pending` at run start so this case is handled correctly).\n\n`--retry-failed` distinguishes between transient failures (agent crash, timeout) and deliberate failures (exhausted all fix cycles). Only transient failures are retried.\n\n`--only-incomplete` reads the plan's status file to determine which tasks already completed. It requires `-b` to specify the session branch to resume.\n\nYou can also re-run specific tasks by ID or slug:\n\n```bash\n# Re-run a single task in an existing session\nwb run plan.md -b workbench-1 --task task-2\n\n# Re-run multiple specific tasks\nwb run plan.md -b workbench-1 --task task-1 --task task-3\n\n# Re-run a task by its slug (title converted to lowercase-dashes)\nwb run plan.md -b workbench-1 --task my-feature-name\n\n# Run specific tasks in a new session (no -b needed)\nwb run plan.md --task task-2\n```\n\n`--task` accepts task IDs (e.g. `task-2`) or slugs (e.g. `my-feature-name`). Only the specified tasks run — all other tasks are left untouched. If a task has an existing branch from a prior run, it is cleaned up and started fresh. Status records for non-targeted tasks are preserved.\n\n### 6. Merge unmerged branches\n\nIf a run was interrupted or some merges failed due to conflicts, use `wb merge` to attempt merging without re-running pipelines:\n\n```bash\nwb merge -b workbench-1\nwb merge -b workbench-1 --plan plan.md    # explicit plan\nwb merge -b workbench-1 --push            # merge and push to origin\n```\n\nThis scans the status files for the session branch, finds tasks with `status=done` that haven't been merged yet, and attempts each merge. Conflicts are handled by a merge resolver agent. Branches that were already merged manually (via git) are detected and skipped. If the session branch exists in multiple plan status files, use `--plan` to disambiguate.\n\n### 7. Monitor progress\n\nA live status table shows task progress in the terminal. With tmux (default), you can also attach to watch any agent work:\n\n```bash\ntmux attach -t wb-task-1-implementor\n```\n\nSessions are named `wb-task-\u003cN\u003e-\u003crole\u003e`.\n\n## Branching strategy\n\nWhen you run `wb run plan.md`, workbench creates this branch structure:\n\n```\nmain (or --base branch)\n └── workbench-N (or --name)         ← session branch (all work merges here)\n      ├── wb/task-1-short-title       ← worktree branch for task 1\n      ├── wb/task-2-another-task   ← worktree branch for task 2\n```\n\nEach task gets its own branch and worktree. Tasks in the same wave run in parallel. After a wave completes, successful task branches are merged into the session branch. If merge conflicts arise between parallel branches, a merger agent resolves them automatically. The next wave then branches from the updated session branch.\n\nWhen all waves finish, the session branch (`workbench-N`) contains the combined work and is ready for review or merging into your base branch.\n\nBy default, workbench fetches `origin/main` and creates the session branch from the latest remote state.\n\n`--name` and `-b` / `--session-branch` are aliases — both declare the session branch identity. The orchestrator creates the branch from `--base` if it doesn't yet exist, or reuses it on resume.\n\n| Flag | Session branch | Base | Source | Use case |\n|------|----------------|------|--------|----------|\n| *(default)* | `workbench-N` | `main` | `origin/main` (fetched) | Start from latest remote |\n| `--name my-feature` | `my-feature` | `main` | `origin/main` (fetched) | Named session branch (created or reused) |\n| `-b my-feature` | `my-feature` | `main` | `origin/main` (fetched) | Same as `--name` |\n| `--local` | `workbench-N` | `main` | local `main` | Build on unpushed local work |\n| `--base \u003cbranch\u003e` | `workbench-N` | `\u003cbranch\u003e` | `origin/\u003cbranch\u003e` (fetched) | Branch from a specific remote branch |\n| `--base \u003cbranch\u003e --local` | `workbench-N` | `\u003cbranch\u003e` | local `\u003cbranch\u003e` | Branch from a local feature branch |\n| `-b my-session` | `my-session` | *(existing)* | *(existing)* | Resume a previous session |\n\n## Profiles\n\nProfiles configure which agent CLI and instructions are used for each pipeline role. When no profile exists, built-in defaults apply.\n\n### Create a profile\n\n```bash\nwb profile init                                            # create .workbench/profile.yaml from defaults\nwb profile init --global                                   # create ~/.workbench/profile.yaml\nwb profile init --set reviewer.agent=gemini                # create with inline overrides\nwb profile init --set reviewer.agent=gemini --set tester.directive_extend=\"Run with -x\"\n```\n\n### Named profiles\n\nCreate multiple profiles for different workflows:\n\n```bash\nwb profile init --name fast --set reviewer.agent=gemini --set implementor.agent=codex\nwb profile init --name security --set reviewer.directive=\"Focus only on security vulnerabilities.\"\nwb run plan.md --profile-name fast                         # use a named profile\n```\n\nNamed profiles are stored as `profile.\u003cname\u003e.yaml` alongside the default `profile.yaml`.\n\n### Customize roles\n\n```bash\nwb profile set reviewer.agent gemini                       # update default profile\nwb profile set tester.directive_extend \"Run pytest with -x flag.\"\nwb profile set reviewer.agent codex --name fast            # update a named profile\n```\n\nOr edit `.workbench/profile.yaml` directly:\n\n```yaml\nroles:\n  reviewer:\n    agent: gemini\n    directive: \"Focus on security and correctness.\"\n  tester:\n    directive_extend: \"Also check edge cases for null inputs.\"\n```\n\nUse `directive` to replace the default instructions, or `directive_extend` to append to them.\n\n### Profile fields\n\n| Role | Description |\n|---|---|\n| `implementor` | Writes code to fulfill the task |\n| `tester` | Runs and writes tests, reports PASS/FAIL |\n| `reviewer` | Reviews the diff for correctness and quality |\n| `fixer` | Addresses feedback from failed tests or reviews |\n| `merger` | Resolves merge conflicts between parallel branches |\n\nEach role supports these fields:\n\n| Field | Description |\n|---|---|\n| `agent` | CLI command to use for this role (default: `claude`) |\n| `directive` | Full replacement for the role's default instructions |\n| `directive_extend` | Text appended to the default instructions (cannot be combined with `directive`) |\n\n### View and compare\n\n```bash\nwb profile show                    # print resolved profile\nwb profile show --name fast        # show a named profile\nwb profile diff                    # show differences from defaults\nwb profile diff --name fast        # diff a named profile\n```\n\n### Merge order\n\nProfiles merge in order: built-in defaults \u003c `~/.workbench/profile.yaml` \u003c `.workbench/profile.yaml` \u003c `--profile` flag \u003c CLI flags. Named profiles (`--profile-name`) replace the default filename at each level.\n\n## TDD mode\n\n```bash\nwb run plan.md --tdd\n```\n\nPipeline becomes: **write tests → implement → verify tests → review → fix**\n\nThe tester writes comprehensive failing tests first. The implementor writes code to make them pass and reports whether the tests are comprehensive. Cannot be combined with `--skip-test`.\n\n## Agents\n\nWorkbench ships with built-in adapters for Claude Code, Gemini CLI, Codex, Cursor CLI, and Copilot CLI. Use `--agent` to select one:\n\n```bash\nwb run plan.md --agent claude     # default\nwb run plan.md --agent gemini\nwb run plan.md --agent codex\nwb run plan.md --agent cursor\nwb run plan.md --agent copilot\n```\n\n### Custom agents\n\nDefine custom adapters via `wb agents add` or by editing `.workbench/agents.yaml` directly:\n\n```bash\nwb agents add my-agent --command my-cli --args \"--headless,{prompt}\" --output-format json\nwb run plan.md --agent my-agent\n```\n\nThis creates an entry in `.workbench/agents.yaml`:\n\n```yaml\nagents:\n  my-agent:\n    command: my-cli\n    args: [\"--headless\", \"{prompt}\"]\n    output_format: json\n    json_result_key: result\n    json_cost_key: cost_usd\n```\n\nThe `{prompt}` placeholder in `args` is replaced with the agent's prompt at runtime. Set `output_format: json` to parse structured output with configurable result and cost keys.\n\n### Managing agents\n\n```bash\nwb agents init                    # create agents.yaml with all built-in adapter configs\nwb agents list                    # show built-in and custom agents\nwb agents show my-agent           # show full config for an agent\nwb agents add my-agent --command my-cli --args \"--headless,{prompt}\"\nwb agents add my-agent --command new-cli   # update an existing agent\nwb agents remove my-agent         # remove a custom agent\n```\n\n`wb agents init` creates `.workbench/agents.yaml` pre-populated with the configs for all built-in adapters (Claude, Gemini, Codex, Cursor, Copilot). Use this as a starting point to customize command flags, output parsing, or to add your own agents.\n\n## Directive overrides\n\nOverride the instructions given to any agent role:\n\n```bash\nwb run plan.md --reviewer-directive \"Focus only on security issues.\"\nwb run plan.md --tester-directive \"Run pytest with -x flag, fail fast.\"\n```\n\nAvailable: `--implementor-directive`, `--tester-directive`, `--reviewer-directive`, `--fixer-directive`.\n\n## CLI reference\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `wb plan \"\u003cprompt\u003e\"` | Generate a plan from a natural language description |\n| `wb run \u003cplan\u003e` | Execute a plan with parallel agents |\n| `wb merge -b \u003cbranch\u003e` | Merge completed-but-unmerged task branches (auto-detects plan) |\n| `wb preview \u003cplan\u003e` | Dry-run: show parsed tasks and waves |\n| `wb setup` | Create `.workbench/`, install skills, and optionally create a profile |\n| `wb status` | Show active worktrees |\n| `wb stop` | Kill all running agent tmux sessions |\n| `wb clean` | Remove all workbench worktrees and `wb/` branches |\n| `wb agents init` | Create agents.yaml with built-in adapter configs |\n| `wb agents list` | List built-in and custom agent adapters |\n| `wb agents show \u003cname\u003e` | Show details for an agent adapter |\n| `wb agents add \u003cname\u003e` | Add or update a custom agent adapter |\n| `wb agents remove \u003cname\u003e` | Remove a custom agent adapter |\n| `wb profile init` | Create profile.yaml from defaults |\n| `wb profile show` | Show resolved profile |\n| `wb profile set \u003ckey\u003e \u003cvalue\u003e` | Update a profile field |\n| `wb profile diff` | Show differences from defaults |\n\n### `wb plan`\n\nTakes an optional prompt argument and/or `--from` flag. At least one must be provided.\n\nThe planner agent surveys the codebase (project structure, patterns, test infrastructure) and writes a detailed plan to `.workbench/plans/\u003cname\u003e.md`. Use `--from` to transform an existing document into workbench format.\n\n| Flag | Description |\n|---|---|\n| `--from FILE` | Transform an existing document into workbench plan format |\n| `-n NAME` / `--name` | Plan file name (default: `plan`). Produces `.workbench/plans/\u003cname\u003e.md` |\n| `--agent CMD` | Agent CLI command (default: `claude`) |\n| `--no-tmux` | Run without tmux |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb run`\n\n| Flag | Description |\n|---|---|\n| `-j N` | Max concurrent agents (default: 4) |\n| `--max-retries N` / `-r N` | Max fix cycles per failed stage (default: 2) |\n| `--skip-test` | Skip the test phase |\n| `--skip-review` | Skip the review phase |\n| `--tdd` | Test-driven: write tests first, then implement |\n| `--agent CMD` | Agent CLI command (default: `claude`) |\n| `--no-tmux` | Run agents as subprocesses instead of tmux |\n| `--base BRANCH` | Base branch to start from (default: `main`) |\n| `--local` | Branch from local ref instead of fetching origin |\n| `-b NAME` / `--session-branch` | Session branch name; created from `--base` if missing, reused if it exists. Alias of `--name`. |\n| `-w N` / `--wave` | Run only wave N (clamped to valid range) |\n| `--start-wave N` | Start from wave N, run through end (default: 1) |\n| `--end-wave N` | Stop after wave N (default: last wave) |\n| `--retry-failed` | Auto-retry tasks that crashed (not those that exhausted fix retries) |\n| `--fail-fast` | Stop after the first wave with any failed tasks |\n| `--only-incomplete` | Skip completed tasks from a prior run (requires `-b`) |\n| `--task ID` | Run only specific tasks by ID or slug (repeatable) |\n| `--cleanup` | Remove worktrees after completion |\n| `--keep-branches` | Keep task branches after merging (default: auto-delete on success) |\n| `--push` | Push the session branch to origin after merging (sets upstream tracking) |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n| `--profile PATH` | Use a specific profile.yaml |\n| `--profile-name NAME` | Use a named profile (`profile.\u003cname\u003e.yaml`) |\n| `--*-directive TEXT` | Override instructions for a specific agent role |\n\n#### Frontmatter-readable flags\n\nPlans may declare these keys in a YAML frontmatter block (`---` delimiters) at the top of the file. Values act as defaults; explicit CLI flags always win. Unknown keys raise an error.\n\n| Key | CLI flag | Type |\n|---|---|---|\n| `session_branch` | `-b` / `--session-branch` | string (alias of `name`) |\n| `name` | `--name` | string (alias of `session_branch`) |\n| `base` | `--base` | string |\n| `local` | `--local` | bool |\n| `agent` | `--agent` | string |\n| `profile` | `--profile` | string (path) |\n| `profile_name` | `--profile-name` | string |\n| `max_concurrent` | `-j` / `--max-concurrent` | int (\u003e= 1) |\n| `max_retries` | `--max-retries` | int (\u003e= 0) |\n| `tdd` | `--tdd` | bool |\n| `skip_test` | `--skip-test` | bool |\n| `skip_review` | `--skip-review` | bool |\n| `retry_failed` | `--retry-failed` | bool |\n| `fail_fast` | `--fail-fast` | bool |\n| `cleanup` | `--cleanup` | bool |\n| `keep_branches` | `--keep-branches` | bool |\n| `push` | `--push` | bool |\n\n### `wb resume`\n\nSugar over `wb run \u003cplan\u003e -b \u003csession\u003e --only-incomplete`. Looks up the session in `.workbench/status-*.yaml`, finds the original plan via the recorded `plan_source`, and re-runs every task that isn't `done + merged`. Frontmatter is read from the plan referenced by the session's `plan_source`; same precedence rules as `wb run`.\n\n```bash\nwb resume workbench-1\nwb resume workbench-1 --tdd          # if the original session was TDD\nwb resume workbench-1 --no-tmux\n```\n\n| Flag | Description |\n|---|---|\n| `--no-tmux` | Run agents as subprocesses instead of tmux |\n| `--agent CMD` | Agent CLI command (default: `claude`) |\n| `-j N` / `--max-concurrent` | Max parallel tasks per wave (default: 4) |\n| `--max-retries N` | Max fix attempts after a failed test or review (default: 2) |\n| `--tdd` | Run pending tasks in TDD mode |\n| `--profile PATH` | Use a specific profile.yaml |\n| `--name NAME` | Named profile to resolve |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\nFor finer-grained control (waves, directive overrides, selective tasks), use `wb run` directly.\n\n### `wb setup`\n\n| Flag | Description |\n|---|---|\n| `--agent NAME` | Target platform: `claude`, `gemini`, `cursor`, `codex`, `copilot`, `manual` (auto-detected if omitted) |\n| `--global` | Install skills to user-level paths only (skip `.workbench/` creation) |\n| `--symlink` | Symlink instead of copy (stays in sync with package updates) |\n| `--profile` | Also create a profile.yaml with the detected agent |\n| `--update` | Force-update skills to the latest version |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb merge`\n\n| Flag | Description |\n|---|---|\n| `-b NAME` / `--session-branch` | Session branch to merge into (required) |\n| `--plan PATH` | Plan file to determine status file (auto-detected if omitted) |\n| `--agent CMD` | Agent CLI for conflict resolution (default: `claude`) |\n| `--no-tmux` | Run resolver agents as subprocesses instead of tmux |\n| `--keep-branches` | Keep task branches after merging |\n| `--push` | Push the session branch to origin after merging (sets upstream tracking) |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb stop`\n\n| Flag | Description |\n|---|---|\n| `--cleanup` | Also remove worktrees and `wb/` branches |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb status`\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb clean`\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n| `--yes` | Skip confirmation prompt |\n\n### `wb agents init`\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb agents list`\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb agents show`\n\nTakes a single argument: the agent name.\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb agents add`\n\nTakes a single argument: the agent name.\n\n| Flag | Description |\n|---|---|\n| `--command CMD` | CLI command to invoke (required) |\n| `--args TEMPLATE` | Argument template, comma-separated (default: `{prompt}`) |\n| `--output-format FMT` | `text` or `json` (default: `text`) |\n| `--json-result-key KEY` | JSON key for result (default: `result`) |\n| `--json-cost-key KEY` | JSON key for cost (default: `cost_usd`) |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb agents remove`\n\nTakes a single argument: the agent name.\n\n| Flag | Description |\n|---|---|\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb profile init`\n\n| Flag | Description |\n|---|---|\n| `--global` | Create in `~/.workbench/` instead of `.workbench/` |\n| `--name NAME` | Create a named profile (`profile.\u003cname\u003e.yaml`) |\n| `--set KEY=VALUE` | Set role fields inline (repeatable) |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb profile show`\n\n| Flag | Description |\n|---|---|\n| `--name NAME` | Show a named profile |\n| `--profile PATH` | Path to a specific profile.yaml |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb profile set`\n\n| Flag | Description |\n|---|---|\n| `--global` | Update `~/.workbench/` instead of local |\n| `--name NAME` | Update a named profile |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n### `wb profile diff`\n\n| Flag | Description |\n|---|---|\n| `--name NAME` | Diff a named profile |\n| `--profile PATH` | Path to a specific profile.yaml |\n| `--repo PATH` | Repository path (auto-detected if omitted) |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, code style, testing, and release instructions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduncankmckinnon%2Fworkbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduncankmckinnon%2Fworkbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduncankmckinnon%2Fworkbench/lists"}