workbench

A generic development workbench for setting up and maintaining multiple projects from a single repository. Built and used internally by PAP — a no-code mobile building platform — and open for community use.

The repository acts as a hub: engineers fork it, configure their code and resource repositories as submodules, and get a consistent environment across the team.

Folder structure

Folder	Purpose
packages/workbench-cli/	The workbench CLI tool (TypeScript, Bun)
projects/	Git submodules for code repositories
resources/	Git submodules for documentation/resource repositories
scripts/	Helper scripts for managing the codebase
thoughts/	Planning notes, research, and ticket documentation (Not checked in)

MCP — Linear

Linear is used for project management. To authenticate the Linear MCP (defined in .opencode/opencode.json), run:

opencode mcp auth linear

workbench CLI

The workbench CLI provides a terminal UI for initializing a workbench repository — forking, cloning, and wiring up submodules interactively or non-interactively.

Prerequisites

• Bun installed
• gh CLI installed and authenticated (gh auth login)

Install

cd packages/workbench-cli
bun install
bun link

Quick start

Interactive init — fork, clone, and set up in one flow:

workbench --init

Non-interactive init:

workbench --init --no-tui --name my-project

Init + setup combined:

workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api

Already have a workbench repo cloned?

workbench --tui

See packages/workbench-cli/README.md for the full flag reference and examples.

Working on issues with OpenCode

Once your workbench is set up, the primary way to work on issues is through OpenCode using the built-in slash commands. These commands implement a structured flow from issue analysis through to review.

Prerequisites

• OpenCode installed
• Linear MCP authenticated (see MCP — Linear above)

The development flow

/ticket → /research → /plan → /execute → /commit → /review

Each command takes a Linear issue ID as its argument and is best run in a fresh OpenCode session:

Command	What it does
/ticket {issue-id}	Analyses the Linear issue and structures it for development
/research {issue-id}	Researches the codebase in context of the issue
/plan {issue-id}	Creates a detailed implementation plan
/execute {issue-id}	Implements the plan
/commit	Commits the changes in atomic commits, ready for review
/review {issue-id}	Reviews the execution against the plan

Example

# Start a new OpenCode session, then:
/ticket PAP-1234
# Read the output, open a new session
/research PAP-1234
# Open a new session
/plan PAP-1234
# Open a new session
/execute PAP-1234
# Once done:
/commit
# Open a new session
/review PAP-1234

The commands are defined in .opencode/command/ and can be customised for your own workflow.

Code indexing with ck

The setup wizard optionally indexes your repositories with ck — a hybrid code search tool by BeaconBay that fuses lexical (BM25/grep) precision with embedding-based recall, so you can find the right code even when the exact keywords aren't there.

Acknowledgements

workbench is inspired by Cluster444/agentic, which pioneered the idea of a structured agentic development workflow using slash commands.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, the development workflow, and how to submit a PR.

Please read our Code of Conduct before participating.

License

MIT — see LICENSE.