Workbench (wb)

A Claude Code plugin for structured software development workflows: project planning, research, design, execution, and validation with TDD enforcement and beads integration.

Overview

A personal workbench of tools and workflows for Claude Code. Streamlines software development through structured planning, research, and persistent task tracking with beads.

Complete Workflow Guide

Quick Start

Installation

# Add the marketplace and install the plugin
claude plugin marketplace add gvarela/workbench
claude plugin install wb@gvarela-workbench

For local development:

# Clone and test locally (changes take effect immediately)
git clone git@github.com:gvarela/workbench.git
claude --plugin-dir /path/to/workbench

Updating

Bump version in .claude-plugin/plugin.json, push to GitHub, then:

claude plugin update wb@gvarela-workbench

Using Commands

# Initialize -> Research -> Design -> Implement -> Validate
/wb:create_project my-feature docs/plans TICKET-123
/wb:create_research docs/plans/2025-01-15-TICKET-123-my-feature
/wb:create_mockup docs/plans/... "UI component"  # Optional for UI
/wb:create_design docs/plans/...
/wb:create_execution docs/plans/...
/wb:implement_tasks docs/plans/...
/wb:validate_execution docs/plans/...

Skills (auto-activated): project-structure, mockup-iteration, tdd-discipline, verification-before-completion, status-sync, review-prep

Full Commands Reference

What's Inside

Commands (/wb:*)

Slash commands for project documentation and task management:

• /wb:create_project - Initialize structured documentation with rich metadata
• /wb:create_research - Document codebase using parallel research agents
• /wb:create_mockup - Research UI patterns and create HTML mockups with visual validation
• /wb:create_design - Create architectural design decisions (WHAT and WHY)
• /wb:create_execution - Transform design into phased execution plan (HOW)
• /wb:implement_tasks - Implement with TDD (Red-Green-Refactor)
• /wb:implement_coordinated - Coordinate implementation with worker agents
• /wb:validate_execution - Validate implementation matches plan
• /wb:validate_project - Validate project documentation structure
• /wb:create_handoff - Create session handoff for work continuity
• /wb:resume_handoff - Resume from handoff document
• /wb:update_status - Intelligently sync status across all documentation files
• /wb:help - Quick reference for all commands

Agents

Specialized agents for codebase analysis:

• codebase-locator - Find specific components and files
• codebase-analyzer - Analyze implementation details with file:line references
• pattern-finder - Find similar patterns and implementations
• task-verifier - Verify task completion against requirements

Skills (auto-activated)

Background capabilities that Claude automatically invokes:

• project-structure - Enforces document separation (research.md, design.md, tasks.md)
• mockup-iteration - Iterate on UI mockups with KEEP/REMOVE/CHANGE tracking
• tdd-discipline - Enforces RED-GREEN-REFACTOR cycle before writing production code
• verification-before-completion - Requires running verification before claiming work is done
• status-sync - Monitors for status drift and reminds to sync
• review-prep - Interactive code review walkthrough using tmux and nvim

Hooks

• SessionStart - Auto-detects beads mode (stealth/git)
• PostToolUse - Lints markdown files after Write/Edit operations

Plugin Structure

workbench/
├── .claude-plugin/     # Plugin manifest + marketplace
│   ├── plugin.json
│   └── marketplace.json
├── commands/           # Slash commands (/wb:*)
├── agents/             # Specialized subagents
├── skills/             # Auto-activated capabilities
├── hooks/              # Event handlers
├── scripts/            # Utility scripts (lint)
├── docs/               # Guides and documentation
└── general/            # General-purpose prompts

Beads Integration

Requires beads for persistent task tracking:

bd init --stealth   # Stealth: .beads/ not committed (work repos)
bd init             # Git: .beads/ in git (personal projects)

Commands create/track beads issues for phases, tasks, and UI questions. SessionStart hook detects mode automatically.

Core Philosophy

• Document, Don't Judge: Research describes what EXISTS, not what should change
• Explicit Barriers: Synchronization points prevent rushing ahead
• Dual Verification: Automated (tests, CI) + Manual (UX, edge cases)
• Zero Scope Creep: Tasks only from plans - no ad-hoc additions

Development

Linting

./scripts/lint           # Lint changed files
./scripts/lint --fix     # Auto-fix issues
./scripts/lint --all     # Lint all markdown files

Testing Changes

# Run with local plugin
claude --plugin-dir /path/to/this/repo

# Reload after changes (inside Claude Code)
/reload-plugins

License

MIT