From b2a34d07450c2fcb066537652366ad11f43b0748 Mon Sep 17 00:00:00 2001 From: Aboo Date: Thu, 2 Apr 2026 09:36:32 +1100 Subject: [PATCH 1/3] PAP-7021 Adds community guidelines and documentation for public release Prepares the repository for public release by adding standard project metadata, including LICENSE, CONTRIBUTING, and CODE_OF_CONDUCT files. Introduces GitHub issue and pull request templates, and significantly expands the documentation in the root and package READMEs to include detailed installation and usage instructions. Relates to PAP-7021 --- .github/ISSUE_TEMPLATE/bug_report.md | 29 +++++++ .github/ISSUE_TEMPLATE/feature_request.md | 21 +++++ .github/pull_request_template.md | 10 +++ CODE_OF_CONDUCT.md | 33 ++++++++ CONTRIBUTING.md | 77 ++++++++++++++++++ LICENSE | 21 +++++ README.md | 59 +++++++------- SECURITY.md | 20 +++++ packages/workbench-cli/README.md | 95 ++++++++++++++++------- 9 files changed, 307 insertions(+), 58 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..4bd15b7 --- /dev/null +++ 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 new file mode 100644 index 0000000..4237744 --- /dev/null +++ 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 new file mode 100644 index 0000000..95aa3e8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,10 @@ +## What does this PR do? + + + +## 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 new file mode 100644 index 0000000..3dde675 --- /dev/null +++ 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 new file mode 100644 index 0000000..302ea3a --- /dev/null +++ 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 new file mode 100644 index 0000000..9717537 --- /dev/null +++ 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 index 0563943..615ce92 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,27 @@ # 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 @@ -22,7 +29,7 @@ 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,13 +44,7 @@ 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: @@ -51,7 +52,7 @@ bun run packages/workbench-cli/src/index.ts workbench --init ``` -**Non-interactive init** — create with defaults: +**Non-interactive init:** ```bash workbench --init --no-tui --name my-project @@ -63,22 +64,24 @@ 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. + +## 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. + +## 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 new file mode 100644 index 0000000..eeba064 --- /dev/null +++ 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 diff --git a/packages/workbench-cli/README.md b/packages/workbench-cli/README.md index b73bdaa..ced3c93 100644 --- a/packages/workbench-cli/README.md +++ b/packages/workbench-cli/README.md @@ -1,6 +1,11 @@ -# Workbench +# workbench CLI -The `workbench` CLI provides a terminal UI for initializing the workbench repository. +[![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) + +A terminal UI for initializing a workbench repository — fork, clone, and wire up git submodules interactively or non-interactively. ## Prerequisites @@ -9,50 +14,43 @@ The `workbench` CLI provides a terminal UI for initializing the workbench reposi ## Installation -To install dependencies and link the CLI locally: - ```bash +cd packages/workbench-cli bun install bun link ``` -After linking, the `workbench` command will be available globally on your system. +After linking, the `workbench` command is available globally. -## Run (without installing) - -You can run the CLI directly from the source without linking: +## Run without installing ```bash bun run src/index.ts ``` -## Quick Start +## Quick start ### Interactive (TUI) -Create a new workbench from scratch: - ```bash workbench --init ``` -This launches an interactive flow: select a fork target (org or personal account), name your workbench, fork and clone the template repo, then optionally run the setup wizard. +Launches an interactive flow: select a fork target (org or personal account), name your workbench, fork and clone the template repo, then optionally run the setup wizard. ### Non-interactive -Create a workbench without prompts: - ```bash workbench --init --no-tui --name my-project ``` -### Combined (init + setup in one command) +### Init + setup in one command ```bash workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api ``` -### Manual Setup +### Existing repo If you already have a workbench repo cloned: @@ -60,7 +58,7 @@ If you already have a workbench repo cloned: workbench --tui ``` -## Init Flags +## Init flags | Flag | Description | Default | |------|-------------|---------| @@ -69,20 +67,22 @@ workbench --tui | `--no-fork` | Clone without forking (read-only) | `false` | | `--no-tui` | Skip TUI, use defaults or provided values | `false` | -## Setup Flags +## Setup flags These flags work with both `--init` and standalone usage: | Flag | Description | Default | |------|-------------|---------| | `--org ` | GitHub organization name | personal account | -| `--code-repository ` | Code repository URL (can be repeated) | - | -| `--resource-repository ` | Resource repository URL (can be repeated) | - | +| `--code-repository ` | Code repository URL (can be repeated) | — | +| `--resource-repository ` | Resource repository URL (can be repeated) | — | | `--code-branch ` | Branch for all code repositories | `main` | | `--resource-branch ` | Branch for all resource repositories | `main` | -| `--index ` | Run indexing after init | `on` | +| `--index ` | Run [ck](https://beaconbay.github.io/ck/) indexing after init | `on` | | `--tui` | Launch interactive TUI mode | `false` | +> **What is ck?** [ck](https://beaconbay.github.io/ck/) is 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. + ## Examples ```bash @@ -105,7 +105,19 @@ workbench --org myorg --code-repository https://github.com/myorg/backend workbench --tui ``` -## Error Scenarios +## What the setup wizard does + +Running init walks through: + +1. Select a GitHub organization or personal account. +2. Select code repositories — added as submodules under `projects/`. +3. Select resource repositories — added as submodules under `resources/`. +4. Configure the target branch per repository. +5. Optionally index with [ck](https://beaconbay.github.io/ck/). + +Afterwards, `.workbench/config.yaml` is written with the selected configuration. + +## Error scenarios | Error | Cause | Resolution | |-------|-------|------------| @@ -114,14 +126,37 @@ workbench --tui | `gh CLI is not authenticated` | `gh auth` not set up | Run `gh auth login` | | `Invalid name "X"` | Bad characters in name | Use only alphanumeric, `-`, `.`, `_` | -## Usage (Existing Repo) +## Development -Run the `workbench` command from the workbench repository root. Select `init` to walk through the interactive setup: +```bash +# Type-check +bun tsc --noEmit -1. Select a GitHub organization or personal account. -2. Select code repositories (added as submodules under the `projects/` directory). -3. Select resource repositories (added as submodules under the `resources/` directory). -4. Configure the target branch per repository. -5. Optionally index with `ck`. +# Build +bun run build + +# Smoke test the built output +./dist/index.js --help +``` + +Source lives in `src/`. The entry point is `src/index.ts`. + +## Releases + +Releases are tag-driven and publish to both npm and JSR automatically. Maintainers run: + +```bash +npm run release:patch # 0.1.x +npm run release:minor # 0.x.0 +npm run release:major # x.0.0 +``` + +See [GitHub Releases](https://github.com/plan-and-publish/workbench/releases) for the version history. + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for the full guide. + +## License -After initialization, the selected configuration is written to `.workbench/config.yaml`. +MIT — see [LICENSE](../../LICENSE). From 560cd486bd216a34ab8aa9c6cd5b0f79cd65ad6f Mon Sep 17 00:00:00 2001 From: Aboo Date: Thu, 2 Apr 2026 09:42:27 +1100 Subject: [PATCH 2/3] PAP-7021 Documents OpenCode development flow in README Adds a new section explaining the structured development workflow using OpenCode slash commands. Provides a command reference and examples for issue analysis, planning, execution, and review. Relates to PAP-7021 --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 615ce92..acd7026 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,51 @@ workbench --tui 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. From c6568710ea16dbfe91543ddd6249a233b291d4fd Mon Sep 17 00:00:00 2001 From: Aboo Date: Thu, 2 Apr 2026 10:36:53 +1100 Subject: [PATCH 3/3] PAP-7021 Adds Acknowledgements to README Credits Cluster444/agentic as the inspiration for the workbench structured agentic development workflow and slash commands. Relates to PAP-7021 --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index acd7026..e9c1764 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,10 @@ The commands are defined in [`.opencode/command/`](.opencode/command/) and can b 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 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, the development workflow, and how to submit a PR.