phpbotscout

phpbotscout

Support and moderation bot bridging Discord and GitLab

Built on gtb — an opinionated, batteries-included framework for Go CLI tools and services.

What is this?

Support happens in two places that do not talk to each other. Questions arrive in Discord, get answered from memory, scroll away, and are asked again a fortnight later. The problems worth tracking rarely become GitLab issues, and the ones that do lose the conversation that produced them — while the answer usually already existed, in a README nobody read at 22:40.

phpbotscout closes both loops. It sits in your Discord server, answers what is already documented (with citations), and when it cannot answer, offers to raise a GitLab issue on the asker's behalf with the thread attached. It also watches for moderation risk and routes it to a private mod queue rather than to nobody.

The side effect is the point: every question it cannot answer is a documentation gap with a timestamp on it. The escalation stream is a prioritised docs backlog that writes itself.

Status: pre-implementation. The project is bootstrapped and the requirements are drafted. See docs/development/specs/2026-07-25-phpbotscout-requirements.md for the governing requirements and delivery phases.

Prerequisites

• Go 1.26.5 or newer — required to build and install.

The following tools are only needed for development (they are not required to install or run the binary). Each is invoked by a just recipe:

• just — the task runner used by this repo.
• golangci-lint — linting (just lint).
• pre-commit — repo hooks (just check).
• zensical — docs site (just docs-serve).
• goreleaser — local snapshot builds (just snapshot).

Install

Install the latest release with go install:

go install gitlab.com/phpboyscout/phpbotscout/cmd/phpbotscout@latest

The main package lives at cmd/phpbotscout/, so the install path ends in /cmd/phpbotscout — installing the module root would fail because it has no main package.

Build & run

This repository ships a justfile with the common tasks. Build the binary with the default recipe:

just            # tidy + generate + build → bin/phpbotscout
just build      # the same, explicitly

Then run it:

./bin/phpbotscout --help

To install the built binary into $GOPATH/bin:

just install

Develop

Clone & verify

just test        # unit tests with coverage
just test-race   # tests under the race detector
just lint        # golangci-lint
just check       # pre-commit hooks across the tree
just ci          # the full local CI suite (tidy, generate, test, test-race, lint)

Run just ci before opening a pull/merge request — it mirrors what CI runs.

Project layout

Add your own commands under pkg/cmd/<command>/ and your reusable packages under pkg/.

The manifest & regeneration model

phpbotscout is scaffolded and kept in sync by GTB's generator. The .gtb/manifest.yaml file is the source of truth for the command tree and project settings. Two flows operate on it:

• gtb generate command <name> — scaffold a new command, recording it in the manifest.
• gtb regenerate — re-render the project from the manifest and the current GTB templates.

Generated files are hash-tracked in the manifest. If you hand-edit a generated file, the next regenerate detects the change as a conflict and prompts before overwriting it — so your edits are never silently lost. This README is one of those files: it is yours to edit, and regeneration will ask before replacing it.

Do not hand-edit generated files expecting silent re-generation. Put custom logic in your own packages, or accept the conflict prompt on the next regenerate.

Configuration

Configuration is layered (highest precedence first): command-line flags → environment variables → config file → embedded defaults. The shipped defaults live in pkg/cmd/root/assets/init/config.yaml.

Any setting can be overridden from the environment using the PHPBOTSCOUT prefix. For example, a log.level setting is overridden by PHPBOTSCOUT_LOG_LEVEL.

Enabled built-ins

GTB provides built-in commands. The following are always available in this project: self-update, first-run init, MCP server, embedded documentation, doctor checks, and changelog.

The following opt-in built-ins are also enabled:

• AI chat — interactive AI assistance.
• Config management — inspect and edit configuration.
• Telemetry — usage and diagnostics reporting.

Change the feature set with gtb enable <feature> / gtb disable <feature> (e.g. gtb enable ai) — this updates .gtb/manifest.yaml and re-renders the root command, so the change survives gtb regenerate project. Do not hand-edit pkg/cmd/root/cmd.go; it is generated and will be overwritten.

Run phpbotscout --help to see the full command list.

Documentation

The documentation site source lives in docs/ and is built with zensical. Serve it locally with:

just docs-serve

Then open the printed local URL in your browser.

Releasing

Releases are driven by Conventional Commits and run through the scaffolded CI pipeline (GitLab CI under .gitlab-ci.yml) together with GoReleaser (.goreleaser.yaml). Merging a release cuts the tag and publishes the build artefacts.

See the GTB release guide for the full workflow: https://gtb.phpboyscout.uk/how-to/custom-release-source/

Contributing

• Follow Conventional Commits for every commit — the changelog and version bumps are computed from them.
• Run just ci before opening a pull/merge request.
• Do not hand-edit generated files (those tracked in .gtb/manifest.yaml); the next gtb regenerate will flag them as conflicts.

Go deeper

GTB documentation:

• Framework docs — https://gtb.phpboyscout.uk/
• Generating commands — https://gtb.phpboyscout.uk/cli/command/
• Regeneration & the manifest — https://gtb.phpboyscout.uk/concepts/regeneration/
• Configuration — https://gtb.phpboyscout.uk/concepts/config/
• Testing — https://gtb.phpboyscout.uk/how-to/testing/
• Repository (source & issues) — https://gitlab.com/phpboyscout/go-tool-base