Profiles

Save per-project agent configurations with profiles — assign agents to roles and customize directives.

Overview

Profiles configure which agent CLI and instructions are used for each pipeline role. When no profile exists, built-in defaults apply (Claude Code for all roles, no custom directives).

Creating a Profile

wb profile init                                            # create .workbench/profile.yaml from defaults
wb profile init --global                                   # create ~/.workbench/profile.yaml
wb profile init --set reviewer.agent=gemini                # create with inline overrides
wb profile init --set reviewer.agent=gemini --set tester.directive_extend="Run with -x"

Named Profiles

Create multiple profiles for different workflows:

wb profile init --name fast --set reviewer.agent=gemini --set implementor.agent=codex
wb profile init --name security --set reviewer.directive="Focus only on security vulnerabilities."
wb run plan.md --profile-name fast                         # use a named profile

Named profiles are stored as profile.<name>.yaml alongside the default profile.yaml.

Customizing Roles

Use wb profile set to update individual fields:

wb profile set reviewer.agent gemini                       # update default profile
wb profile set tester.directive_extend "Run pytest with -x flag."
wb profile set reviewer.agent codex --name fast            # update a named profile

Or edit .workbench/profile.yaml directly:

roles:
  reviewer:
    agent: gemini
    directive: "Focus on security and correctness."
  tester:
    directive_extend: "Also check edge cases for null inputs."

Use directive to replace the default instructions, or directive_extend to append to them.

Profile Fields

Roles

Role	Description
`implementor`	Writes code to fulfill the task
`tester`	Runs and writes tests, reports PASS/FAIL
`reviewer`	Reviews the diff for correctness and quality
`fixer`	Addresses feedback from failed tests or reviews
`merger`	Resolves merge conflicts between parallel branches
`planner`	Generates workbench plans (`wb plan`)
`summarizer`	Extracts a requirements digest from the plan during final review
`branch_reviewer`	Reviews the whole session branch diff against the requirements digest

Fields per Role

Field	Description
`agent`	CLI command to use for this role (default: `claude`)
`directive`	Full replacement for the role's default instructions
`directive_extend`	Text appended to the default instructions (cannot be combined with `directive`)

Viewing and Comparing

wb profile show                    # print resolved profile
wb profile show --name fast        # show a named profile
wb profile show --full             # show full directive text, including built-in defaults
wb profile diff                    # show differences from defaults
wb profile diff --name fast        # diff a named profile

Merge Order

Profiles merge in order of specificity. Later sources override earlier ones:

Built-in defaults
~/.workbench/profile.yaml (global)
.workbench/profile.yaml (project)
.workbench/<plan>/profile.yaml (per-plan)
--profile flag (explicit path)
CLI flags (--*-directive)

Named profiles (--profile-name) replace the default filename at each level.

The per-plan layer (step 4) lets you freeze a plan's agent configuration independently of the project-level config. Use wb plan copy-settings <name> or the --copy-settings flag on wb plan to populate it from the current effective config. Agents are resolved the same way — .workbench/<plan>/agents.yaml takes precedence over .workbench/agents.yaml.

Directive Overrides

Override the instructions given to any agent role directly from the CLI, without modifying the profile:

wb run plan.md --reviewer-directive "Focus only on security issues."
wb run plan.md --tester-directive "Run pytest with -x flag, fail fast."

Available flags: --implementor-directive, --tester-directive, --reviewer-directive, --fixer-directive, --summarizer-directive, --branch-reviewer-directive.

These replace the role's instructions for that run and take precedence over profile values.

Sub-mode Directives

Some roles have sub-modes — variants used in specific execution contexts. Sub-modes inherit the parent role's agent but can have their own directive.

Sub-mode	Supported roles	When used
`tdd`	`implementor`, `tester`	`wb run --tdd` — write failing tests first, then implement
`followup`	`reviewer`	Re-review after a fix (attempt > 1)

Configure sub-mode directives in YAML using the <role>.<sub_mode> key:

roles:
  tester:
    tdd:
      directive_extend: "Use pytest fixtures for shared setup. Prefer parametrized tests."
  reviewer:
    followup:
      directive: "Focus only on whether the fix addresses the original feedback."
  implementor:
    tdd:
      directive_extend: "Make only the minimal changes needed to pass the failing tests."

Or via wb profile set:

wb profile set tester.tdd.directive_extend "Use pytest fixtures for shared setup."
wb profile set reviewer.followup.directive "Focus only on the fix."

Sub-mode keys are validated: tdd is only valid under implementor and tester; followup is only valid under reviewer. Setting them elsewhere raises an error.

Full directive map

Workbench uses 11 directive variants in total:

Directive	YAML path	When used
Implementor	`implementor.directive`	Standard implement stage
Tester	`tester.directive`	Standard test stage
Reviewer (first pass)	`reviewer.directive`	First review of a task
Reviewer follow-up	`reviewer.followup.directive`	Re-review after a fix (attempt > 1)
Fixer	`fixer.directive`	After test or review failure
Merger	`merger.directive`	When merging branches produces conflicts
TDD Tester	`tester.tdd.directive`	`wb run --tdd` — writing failing tests first
TDD Implementor	`implementor.tdd.directive`	`wb run --tdd` — making failing tests pass
Planner	`planner.directive`	`wb plan <prompt>`
Summarizer	`summarizer.directive`	`wb final-review` — extracts requirements digest from plan
Branch Reviewer	`branch_reviewer.directive`	`wb final-review` — reviews session branch against requirements

All 11 support both directive (full replace) and directive_extend (append to default) at their respective YAML paths. CLI flags (--*-directive) are available for the main task-pipeline roles (implementor, tester, reviewer, fixer) and the final-review roles (summarizer, branch_reviewer); they always do a full replacement for that run.

When to Use Profiles

Speed-optimized — use Gemini for implementation (faster output) and Claude for review (thorough analysis)
Cost-optimized — use a less expensive agent for testing and fixing, reserve the most capable agent for implementation
Provider diversity — spread work across providers to avoid rate limits on large plans
Team consistency — commit .workbench/profile.yaml to the repo so every team member uses the same agent configuration