Workbench

The portable intelligence and engineering-guidance layer for my development environment.

Workbench is where I version the behavior I want Pi, Claude Code, and Codex to share: agent rules, skills, prompts, safety policy, engineering doctrine, and reusable project-health tools. It turns those canonical sources into each harness’s native configuration and verifies the live result.

This is a personal, opinionated repository. It optimizes one workflow rather than trying to become a general agent platform.

Position in the Stack

Workbench is the agent-intelligence layer of the capability stack described canonically in STACK.md:

dotfiles   host foundation and machine capabilities
    ↓
workbench  reusable agent intelligence and engineering standards
    ↓
private workflow layers

dotfiles provisions the host and installs Workbench; private workflow layers may apply both public layers through their CLI contracts. Each layer stands alone - integration is composition and provisioning order, never cross-repository Python imports.

What It Does

Workbench gives me one place to answer four questions:

1. How should my coding agents behave? Shared rules, safety boundaries, reusable skills, and review guidance live under agents/.
2. How do those instructions reach each harness? workbench sync translates and deploys the canonical sources into Pi, Claude Code, and Codex configuration.
3. Has live configuration drifted? workbench drift compares the deployed files and installed plugins directly with the repository.
4. What engineering judgment should carry between projects? The playbook, health kit, and review skills preserve reusable decisions without coupling them to a particular codebase.

                    canonical sources
              agents/   playbook/   health/
                           │
                  workbench sync all
                           │
          ┌───────────────┼───────────────┐
          │               │               │
         Pi          Claude Code         Codex
  rules, settings,   rules, settings,   rules, TOML,
  skills, extensions skills, plugins    skills, plugins
          │               │               │
          └───────────────┼───────────────┘
                          │
                workbench drift all
                    live drift report

The repository is both the source material and the deployment contract. It does not store a snapshot of the machine and compare against that stale observation.

Ownership Boundaries

Dotfiles installs Workbench and links workbench plus its short alias wb into ~/.local/bin; Workbench then configures the supported agents. Individual projects remain authoritative for their own AGENTS.md, architecture, domain vocabulary, and safety policy.

Capabilities

Agent configuration

• One shared instruction file for Pi, Claude Code, and Codex, with a small Codex appendix where the harnesses genuinely differ.
• Reusable skills installed for all three harnesses.
• Vendor-native hooks, permission rules, sandbox defaults, and status lines.
• Declarative plugin installation for Claude and Codex.
• A shared MCP registry that preserves intentional external additions and removes explicitly retired integrations.

Engineering guidance

• The playbook groups reusable knowledge by agents, engineering, languages, systems, and product. Filenames expose the subjects; the watchlist holds only unresolved questions and triggers.
• health/ provides deterministic project-check patterns and adoption contracts; advisory review behavior lives in the relevant skills.
• agents/prompts/ contains reusable prompts that do not warrant an always-on skill.
• docs/decisions/tombstones.md prevents rejected tools and approaches from being casually rediscovered and reintroduced.
• docs/agents/pi/decisions.md records what the Pi harness adopts, rejects, and holds for evidence, while docs/agents/pi/README.md records current behavior.

Install

On a fresh Mac, the normal entry point is the dotfiles installer:

mkdir -p ~/code/public
git clone https://github.com/e-m-albright/dotfiles.git ~/code/public/dotfiles
~/code/public/dotfiles/install.sh

Dotfiles clones this repository, installs the workbench and wb launchers in ~/.local/bin, runs workbench sync all, and requires workbench drift all to pass.

For a standalone checkout:

git clone https://github.com/e-m-albright/workbench.git ~/code/public/workbench
cd ~/code/public/workbench
./bin/workbench --help
pnpm install --frozen-lockfile
just check

Requirements are deliberately small: uv (which provisions the Python 3.13 development line pinned in .python-version and the Typer/Rich CLI environment on first run), Bash, Node 24 LTS and pnpm for the locked Pi extension test and development tools, and the installed Pi/Claude/Codex CLIs. Pandoc is required only to render and verify the maintained call-script document template. Workbench stages and atomically replaces managed skills; Pi and Codex discover one shared real-file deployment under ~/.agents/skills, avoiding duplicate Pi skill warnings.

TypeScript formatting stays with Biome. just lint-ts runs the two selected Oxlint promise checks; just check includes formatting, linting, tests, and type checking. Vite+ remains on the watchlist.

Most skills are tracked directly. Reviewed third-party skills may instead be declared in agents/shared/external-skills.json with an immutable release URL and SHA-256. Sync downloads a missing or invalid archive into ~/.cache/workbench/external-skills, verifies and safely extracts it, applies the tracked wrapper under agents/external-skills/, and deploys the composed tree atomically. Drift verifies the cache and deployment offline.

Daily Workflows

Reconcile everything

workbench sync all
workbench drift all

sync preserves unmanaged vendor settings, writes only Workbench-owned values, and keeps one .bak file before replacing live configuration. By default it also reconciles skills and declared plugins.

Use narrower targets while developing or diagnosing one integration:

workbench sync claude
workbench drift claude

workbench sync codex
workbench drift codex

Skip the slower external installers when only configuration files need repair:

workbench sync all --no-skills --no-plugins

Managed work computers use the fail-closed work profile:

workbench sync all --profile work
workbench drift all --profile work

That profile targets only Claude Code and Pi. It keeps shared rules, tracked skills, hooks, permission guards, shared shell launchers, and the native Claude and Pi harness projections while omitting Codex, Claude plugins and Desktop configuration, MCP servers, externally downloaded skills, local-model routing, and browser and personal connector extensions.

Sync and drift use DOTFILES_PROFILE when set, otherwise personal; an explicit --profile overrides that default. just deploy chains sync and drift so a deploy is verified in one command.

Validate repository sources

just check       # format, lint, types, tests, and source validation
just test        # deterministic unit tests only
just lint        # skills, links, JSON, TOML, and shell syntax
just check-documents  # render-smoke the maintained call-script template

Understand an unexpected live item

workbench drift all

DRIFT (managed value missing or different, non-zero exit) is distinguished from EXTERNAL (valid unmanaged addition, reported but passing). Details in docs/configuration.md.

Command Tree

Run workbench, wb, or either launcher’s --help flag for the complete tree:

workbench
├── sync [claude|codex|pi|all] deploy canonical configuration
│   ├── --profile              personal or work; defaults to DOTFILES_PROFILE
│   ├── --no-skills            skip shared-skill installation
│   ├── --no-plugins           skip declared-plugin installation
│   └── --rules-only           deploy only global instruction files
├── drift [claude|codex|pi|all] report managed drift and external additions
│   └── --profile              personal or work; defaults to DOTFILES_PROFILE
├── lint                       validate canonical repository sources
└── native
    ├── prepare [--authorize]  install the managed runtime and optional model logins
    ├── authorize      enroll one login; --replace backs up and replaces it
    ├── status [vendor]        inspect paths and login metadata without token reads
    └── run  -- ...    launch codex, claude, pi, or a diagnostic shell

Run just for the repository-development command list. The CLI manages live agent configuration; Just recipes develop and validate this repository.

What sync Manages

sync deploys each harness’s managed subset: global instructions, configuration, command policy, extensions or hooks, skills, plugins, and MCP servers where supported. The per-harness file map and drift semantics live in docs/configuration.md.

Repository Tour

agents/
├── shared/              cross-vendor rules, hooks, and MCP registry
├── claude/              Claude settings fragments and plugin declarations
├── codex/               Codex rules, hooks, status line, and plugins
├── pi/                  Pi settings, models, presets, permission policy, and extensions
├── skills/              reusable on-demand workflows
└── prompts/             reusable prompts below the skill threshold

playbook/                reusable knowledge, discovered by subject
├── agents/              models, harnesses, tools, orchestration, and authority
├── engineering/         design, verification, review, and delivery practices
├── languages/           language idioms, libraries, and framework guides
├── systems/             services, data, infrastructure, and host tools
└── product/             discovery, design tools, and interfaces

health/                  portable deterministic project-check patterns
docs/                    current Workbench behavior, architecture, and decisions
src/workbench/           Typer + Rich deployment and verification CLI
pyproject.toml           uv-managed project (Typer, Rich; pytest/Ruff/Pyright dev gate)
tests/                   deterministic CLI, sync, drift, guard-hook, and Pi extension tests
bin/workbench            relocatable shell launcher (execs via uv)

Extending Workbench

Choose the smallest durable surface that fits the need:

1. Update agents/shared/rules.md only for behavior that should always apply to Pi, Claude Code, and Codex.
2. Add or revise a skill for a recurring workflow that should load on demand.
3. Add a prompt when reusable wording is useful but executable workflow or automatic triggering is not.
4. Add an MCP or plugin declaration only when the integration has recurring value and a clear owner.
5. Put project-specific guidance in that project’s AGENTS.md, not here.
6. Put private workflow instances and generated state in the private repository that owns their context.

After changing managed configuration:

just check
workbench sync all
workbench drift all

When removing a supported capability, record the reason where its off-switch lives: the RETIRED_* mappings in src/workbench/core.py, _*_disabled entries in the MCP registry, or docs/decisions/tombstones.md for decisions with no code enforcement.

Safety and Publishing Boundary

Workbench is public. It must never contain credentials, personal records, conversations, generated memory, or private operational state.

The shortcuts co, cc, and p run the entire agent process and its children inside Workbench’s native macOS boundary. They show cloud > managed and admit the selected ordinary Git checkout, ~/code/public, ~/Desktop, and ~/Downloads, while retaining private-file exclusions. Full commands codex, claude, and pi keep their native behavior and shared configuration without adding this outer boundary. A native binary started inside a managed session still inherits that session’s restrictions. The old authority flags and alternate host/repository aliases are retired. The isolated HOME maps Desktop and Downloads to the host directories. Explicit private/local intent is rejected in managed Pi; start native Pi from the host for local inference. The launch design catalogue compares these routes and records the incorporated fixes and remaining limits. The six-model review disposition separates corrected defects from accepted risks, including provider-token exposure, pre-existing admitted hardlinks, host callbacks, and later execution of edits. The isolation contract owns filesystem and network permissions, credential exceptions, uncovered host interfaces, and accepted risks. Permission rules and PreToolUse hooks add defense in depth against destructive commands. Database and infrastructure policy remains the responsibility of the project that owns those resources.

For an independent read-only fact-check, use the adversarial audit prompt.

Completion and approval notifications use each vendor’s native notification channel. Workbench installs no notification daemon or background service.

Design Rules

1. Prefer declarative files and small scripts over a framework.
2. Add executable behavior only for an evidenced recurring workflow.
3. Keep deterministic checks separate from stochastic assessments.
4. Preserve unmanaged vendor configuration unless it violates an explicit retirement or safety rule.
5. Treat generated agent state as private and disposable.
6. Preserve rejected decisions as tombstones instead of repeatedly evaluating the same tools.

Reuse

Workbench is fork-and-adapt material, not a framework or a package to depend on. If you want something similar, take the shapes that fit your workflow — the canonical-source-to-sync/drift model, the skills layout, the health kit — and replace the opinions with your own. See STACK.md for how it composes with the neighboring repositories.