workbench-codes · aboo · Apr 2, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a bug in the workbench CLI or setup flow
+labels: bug
+---
+
+## Describe the bug
+
+A clear description of what the bug is.
+
+## Steps to reproduce
+
+1. Run `workbench ...`
+2. ...
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened. Include full terminal output if relevant.
+
+## Environment
+
+- OS:
+- Bun version (`bun --version`):
+- workbench version (`workbench --version`):
+- `gh` CLI version (`gh --version`):
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an improvement or new feature
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve? What is currently missing or frustrating?
+
+## Proposed solution
+
+Describe what you'd like to happen.
+
+## Alternatives considered
+
+Any alternative solutions or workarounds you've already thought about.
+
+## Additional context
+
+Any other context, screenshots, or examples.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,10 @@
+## What does this PR do?
+
+<!-- A short description of the change and its motivation. -->
+
+## Checklist
+
+- [ ] `bun tsc --noEmit` passes
+- [ ] `bun run build` succeeds
+- [ ] `./dist/index.js --help` runs without error
+- [ ] README updated if flags or behavior changed
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated and will result in a response deemed necessary and appropriate to the circumstances.
+
+Maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,77 @@
+# Contributing to workbench
+
+Thank you for your interest in contributing! This document covers how to get set up, the project structure, and how to submit changes.
+
+## Who uses this
+
+workbench is built and used by the [PAP](https://pap.dev) team internally and is open for community contributions.
+
+## Project structure
+
+```
+workbench/
+├── packages/
+│   └── workbench-cli/   # The `workbench` CLI tool (TypeScript, Bun)
+├── projects/            # Git submodules for code repos
+├── resources/           # Git submodules for documentation repos
+├── scripts/             # Helper scripts
+└── thoughts/            # Planning notes and research docs
+```
+
+## Setting up locally
+
+**Prerequisites:**
+- [Bun](https://bun.sh) installed
+- [gh CLI](https://cli.github.com) installed and authenticated
+
+```bash
+git clone https://github.com/plan-and-publish/workbench.git
+cd workbench/packages/workbench-cli
+bun install
+```
+
+## Development workflow
+
+All CLI source lives in `packages/workbench-cli/src/`.
+
+```bash
+# Type-check
+bun tsc --noEmit
+
+# Build
+bun run build
+
+# Run directly without building
+bun run src/index.ts --help
+
+# Smoke test the built output
+./dist/index.js --help
+```
+
+## Submitting a pull request
+
+1. Fork the repo and create a branch from `main`.
+2. Make your changes in `packages/workbench-cli/src/`.
+3. Run type-check and build to make sure nothing is broken.
+4. Open a PR against `main` — the CI workflow will run automatically.
+5. Describe what you changed and why in the PR description.
+
+## Releases
+
+Releases are tag-driven. Maintainers run one of:
+
+```bash
+npm run release:patch   # 0.1.x
+npm run release:minor   # 0.x.0
+npm run release:major   # x.0.0
+```
+
+This bumps the version, commits, and tags. Pushing the tag triggers the publish workflow, which publishes to both [npm](https://www.npmjs.com/package/@pap.dev/workbench) and [JSR](https://jsr.io/@pap/workbench).
+
+## Reporting bugs
+
+Open an issue using the [bug report template](https://github.com/plan-and-publish/workbench/issues/new?template=bug_report.md).
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plan-and-publish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,28 +1,35 @@
 # workbench
 
-- This repository will be used as a generic workbench for development and maintaining of different projects code and documentation.
+[![CI](https://github.com/plan-and-publish/workbench/actions/workflows/ci-workbench-cli.yml/badge.svg)](https://github.com/plan-and-publish/workbench/actions/workflows/ci-workbench-cli.yml)
+[![npm](https://img.shields.io/npm/v/@pap.dev/workbench)](https://www.npmjs.com/package/@pap.dev/workbench)
+[![JSR](https://jsr.io/badges/@pap/workbench)](https://jsr.io/@pap/workbench)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Folder Structure
+A generic development workbench for setting up and maintaining multiple projects from a single repository. Built and used internally by [PAP](https://pap.dev) — a no-code mobile building platform — and open for community use.
 
-- 'resources' folder contains mostly documentation and information.
-- 'projects' folder continas source codes that an engineer will pull to work on
-- 'scrips' contains helper codes that facilitate certain activities to give easier access to manage the codebase
+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.
 
-## MCP
+## Folder structure
 
-### Linear Authentication
+| 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) |
 
-Linear is a project management tool that is used to track the progress of projects. It is used to manage the tasks, issues, and other information related to the projects.
+## MCP — Linear
 
-To authenticate the Linear MCP (defined in [.opencode/opencode.json](.opencode/opencode.json)), run the following command for interactive authentication:
+[Linear](https://linear.app) is used for project management. To authenticate the Linear MCP (defined in [.opencode/opencode.json](.opencode/opencode.json)), run:
 
 ```bash
 opencode mcp auth linear
 ```
 
 ## workbench CLI
 
-The `workbench` CLI provides a terminal UI for initialising the workbench repository.
+The `workbench` CLI provides a terminal UI for initializing a workbench repository — forking, cloning, and wiring up submodules interactively or non-interactively.
 
 ### Prerequisites
 
@@ -37,21 +44,15 @@ bun install
 bun link
 ```
 
-### Run (without installing)
-
-```bash
-bun run packages/workbench-cli/src/index.ts
-```
-
-### Quick Start
+### Quick start
 
 **Interactive init** — fork, clone, and set up in one flow:
 
 ```bash
 workbench --init
 ```
 
-**Non-interactive init** — create with defaults:
+**Non-interactive init:**
 
 ```bash
 workbench --init --no-tui --name my-project
@@ -63,22 +64,73 @@ workbench --init --no-tui --name my-project
 workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api
 ```
 
-**Manual alternative** — fork/clone the repo yourself, then:
+**Already have a workbench repo cloned?**
 
 ```bash
 workbench --tui
 ```
 
-### Usage
+See [packages/workbench-cli/README.md](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](https://opencode.ai/) using the built-in slash commands. These commands implement a structured flow from issue analysis through to review.
+
+### Prerequisites
+
+- [OpenCode](https://opencode.ai/) installed
+- Linear MCP authenticated (see [MCP — Linear](#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
+
+```bash
+# 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/`](.opencode/command/) and can be customised for your own workflow.
+
+## Code indexing with ck
+
+The setup wizard optionally indexes your repositories with [ck](https://beaconbay.github.io/ck/) — a hybrid code search tool by [BeaconBay](https://github.com/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](https://github.com/Cluster444/agentic), which pioneered the idea of a structured agentic development workflow using slash commands.
+
+## Contributing
 
-Run `workbench` from the workbench repository root. Select `init` to walk through:
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, the development workflow, and how to submit a PR.
 
-1. Select GitHub org or personal account
-2. Select code repositories (submodules under `projects/`)
-3. Select resource repositories (submodules under `resources/`)
-4. Configure branch per repository
-5. Optionally index with `ck`
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
 
-After init, `.workbench/config.yaml` is written with the selected configuration.
+## License
 
-See [packages/workbench-cli/README.md](packages/workbench-cli/README.md) for full documentation.
+MIT — see [LICENSE](LICENSE).
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| latest  | Yes       |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+To report a vulnerability, open a [GitHub Security Advisory](https://github.com/plan-and-publish/workbench/security/advisories/new) on this repository. You can expect an acknowledgement within 48 hours and a resolution timeline within 7 days depending on severity.
+
+Please include as much of the following as possible:
+
+- Type of vulnerability
+- Steps to reproduce
+- Affected versions
+- Any potential impact