From e54165606c6b8fd9e11b9c6d0e52f75f1676ead4 Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Wed, 21 Oct 2026 14:01:58 +0200 Subject: [PATCH 1/4] docs: document shell completion, Windows support and the new conventions The CLI has shipped install-completion-files since it extended CompletionCommandRunner, but cli_completion hides those commands from --help, so nothing told anyone they existed. Windows is stated plainly rather than left open: macOS and Linux are supported, Windows through WSL, and jq has to be on PATH because the Codex, Copilot and Antigravity hooks are bash scripts. Native Windows and Git Bash are called untested, because the CLI builds paths with the host separator while those scripts expect POSIX ones. AGENTS.md and CONTRIBUTING.md pick up release-please, the link check, the shared test harness and the constructor doc rule. --- AGENTS.md | 9 +++++++++ CONTRIBUTING.md | 9 +++++++++ packages/vgv_ai_cli/README.md | 19 ++++++++++++++++++- 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 047948d..1322906 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,10 @@ The repo is a **pub workspace** monorepo: the root `pubspec.yaml` declares `work | `jq` | Agent hooks parse their payloads with it | Guard hooks error out; the analyze and format hooks silently do nothing | | `gh`, authenticated with org access | This repo is private | Push and PR creation fail | +macOS and Linux are supported; on Windows, use WSL. `jq` must be on `PATH` for the Codex, Copilot +and Antigravity hooks. Native Windows, including Git Bash, is untested: the CLI builds paths with +the host separator and the hook scripts expect POSIX ones. + Upgrading `very_good_cli` does not reach the MCP server until the agent session restarts — the server binds its binary at session start. ## Common Commands @@ -116,6 +120,8 @@ Both packages release together. release-please bumps each package's own `pubspec The CLI is tagged `vX.Y.Z` and `plugin_source` as `plugin_source-vX.Y.Z`; `pub_publish.yaml` fires on the former. +You should not need to bump the version by hand at all: release-please owns it. Because it writes the bump straight into `pubspec.yaml`, `.github/workflows/release_please.yaml` regenerates this file on the release branch, otherwise `verify-version` fails on the release PR. + ## Code Conventions - Linting: `very_good_analysis` ^11.0.0, with `public_member_api_docs` disabled. Public classes still carry `/// {@template name}` / `/// {@macro name}` doc comments. @@ -127,6 +133,7 @@ The CLI is tagged `vX.Y.Z` and `plugin_source` as `plugin_source-vX.Y.Z`; `pub_p - **100% test coverage required.** New code needs tests covering success, failure, and usage-error paths. - Mocking with `mocktail`. - Tests exercise commands **through** `VgvAiCliCommandRunner.run(['update'])` rather than instantiating the `Command` directly, so argument parsing and the runner's error handling are covered too. +- `test/helpers/command_helper.dart` holds `TestRunner`, the mocked `Logger`, `Progress` and `PubUpdater` every command test shares, already stubbed. Go through its `run`/`build` instead of constructing a `VgvAiCliCommandRunner` in the test, and re-stub a mock only where a test needs a different answer. - Assertions verify logger calls (`verify(() => logger.info(...)).called(1)`) alongside the exit code. ## Agent tooling @@ -148,6 +155,8 @@ Each workflow under `.github/workflows/` is path-filtered, and every reusable wo - `vgv_ai_cli.yaml` runs on changes to itself, `.github/cspell.json`, `packages/vgv_ai_cli/lib/**`, `packages/vgv_ai_cli/test/**`, `packages/vgv_ai_cli/pubspec.yaml`, `packages/plugin_source/lib/**`, `packages/plugin_source/pubspec.yaml`, `bricks/**` and `tool/**`. Its jobs are `semantic-pull-request`, `build` (the reusable `dart_package.yml` in `packages/vgv_ai_cli`), `spell-check`, `verify-bundle` and `verify-pins`. - `plugin_source.yaml` runs on changes to itself and `packages/plugin_source/**`. Its jobs are `semantic-pull-request` and `build` (the reusable `dart_package.yml` in `packages/plugin_source`). - Both `build` jobs also run the cognitive complexity check on their package's `lib`, which fails when any function scores above 15. Split a function that crosses it into smaller ones rather than raising the threshold. Run it locally with the `cognitive_complexity` scanner from [kevmoo/analytica.dart](https://github.com/kevmoo/analytica.dart/tree/main/packages/cognitive_complexity). +- `release_please.yaml` runs on every push to `main`. release-please owns versions and changelogs (`.release-please-config.json`, `.release-please-manifest.json`); it opens or updates one release PR covering both packages, and merging it tags `vgv_ai_cli-vX.Y.Z` and `plugin_source-vX.Y.Z`. Never bump a version or edit a `CHANGELOG.md` by hand. Because the bump lands straight in `pubspec.yaml`, the workflow regenerates `lib/src/version.dart` on the release branch, otherwise `verify-version` fails on the release PR. +- `check_links.yaml` runs lychee over every markdown and Dart file on PRs and weekly. Placeholder URLs in fixtures, and links into private sibling repos, are listed in `.lycheeignore`. - `license_check.yaml` runs on changes to itself and either package's `pubspec.yaml`. Dependency licenses are restricted to `MIT`, `BSD-3-Clause`, `BSD-2-Clause`, `Apache-2.0`. - A PR that touches only markdown or other files outside these filters triggers no CI at all. - PR titles must be [conventional commits](https://www.conventionalcommits.org). The `semantic-pull-request` job checks this, but only on PRs that trigger one of the first two workflows. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40cf3b3..2ed6ebb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,6 +147,15 @@ open coverage/index.html - Leave every `CHANGELOG.md` and version bump alone, the `agents` brick's included. Release automation owns them. +## Releases + +[release-please](https://github.com/googleapis/release-please) owns versions and changelogs. +Every push to `main` opens or updates a release pull request that bumps `pubspec.yaml`, +regenerates `lib/src/version.dart` and writes `CHANGELOG.md`. Merge it only when a release is +intended; merging it tags the release and publishes the notes. + +Do not bump a version or edit a `CHANGELOG.md` by hand. + ## Breaking changes `vgv_ai` writes into config files people already own, and the install manifest diff --git a/packages/vgv_ai_cli/README.md b/packages/vgv_ai_cli/README.md index 08756c4..89ed5eb 100644 --- a/packages/vgv_ai_cli/README.md +++ b/packages/vgv_ai_cli/README.md @@ -14,13 +14,21 @@ current, and removes them again without touching your own configuration. `vgv_ai` is a Dart package. You need the [Dart SDK](https://dart.dev/get-dart) 3.13 or later. +It is not published on [pub.dev](https://pub.dev) yet, so install it from a +checkout of this repository: + ```sh -dart pub global activate vgv_ai_cli +dart pub global activate --source=path ``` This puts the `vgv_ai` executable on your path. Run `vgv_ai --help` to confirm that it's installed. +macOS and Linux are supported. On Windows, use WSL. The Codex, Copilot and +Antigravity hooks are `#!/bin/bash` scripts that call `jq`, so `jq` has to be +on your path. Native Windows, including Git Bash, is untested: `vgv_ai` builds +paths with the host separator while those scripts expect POSIX ones. + ## Supported harnesses `vgv_ai` calls each coding agent a harness. The flag name is what you pass to @@ -181,6 +189,15 @@ vgv_ai install --help vgv_ai install --verbose ``` +## Shell completion + +```sh +vgv_ai install-completion-files +``` + +Installs shell completion for bash and zsh. Remove it again with +`vgv_ai uninstall-completion-files`. + ## Contributing To work on `vgv_ai`, see the From 006fae0438227ccbea39260e6ae90a38b71f520a Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Mon, 26 Oct 2026 13:58:50 +0100 Subject: [PATCH 2/4] docs: describe the single release unit --- AGENTS.md | 2 +- CONTRIBUTING.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1322906..549af13 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,7 +155,7 @@ Each workflow under `.github/workflows/` is path-filtered, and every reusable wo - `vgv_ai_cli.yaml` runs on changes to itself, `.github/cspell.json`, `packages/vgv_ai_cli/lib/**`, `packages/vgv_ai_cli/test/**`, `packages/vgv_ai_cli/pubspec.yaml`, `packages/plugin_source/lib/**`, `packages/plugin_source/pubspec.yaml`, `bricks/**` and `tool/**`. Its jobs are `semantic-pull-request`, `build` (the reusable `dart_package.yml` in `packages/vgv_ai_cli`), `spell-check`, `verify-bundle` and `verify-pins`. - `plugin_source.yaml` runs on changes to itself and `packages/plugin_source/**`. Its jobs are `semantic-pull-request` and `build` (the reusable `dart_package.yml` in `packages/plugin_source`). - Both `build` jobs also run the cognitive complexity check on their package's `lib`, which fails when any function scores above 15. Split a function that crosses it into smaller ones rather than raising the threshold. Run it locally with the `cognitive_complexity` scanner from [kevmoo/analytica.dart](https://github.com/kevmoo/analytica.dart/tree/main/packages/cognitive_complexity). -- `release_please.yaml` runs on every push to `main`. release-please owns versions and changelogs (`.release-please-config.json`, `.release-please-manifest.json`); it opens or updates one release PR covering both packages, and merging it tags `vgv_ai_cli-vX.Y.Z` and `plugin_source-vX.Y.Z`. Never bump a version or edit a `CHANGELOG.md` by hand. Because the bump lands straight in `pubspec.yaml`, the workflow regenerates `lib/src/version.dart` on the release branch, otherwise `verify-version` fails on the release PR. +- `release_please.yaml` runs on every push to `main`. release-please owns versions and changelogs (`.release-please-config.json`, `.release-please-manifest.json`). The repository releases as one unit, so any change can open or update the release PR, and merging it tags `vX.Y.Z`. Never bump a version or edit a `CHANGELOG.md` by hand. - `check_links.yaml` runs lychee over every markdown and Dart file on PRs and weekly. Placeholder URLs in fixtures, and links into private sibling repos, are listed in `.lycheeignore`. - `license_check.yaml` runs on changes to itself and either package's `pubspec.yaml`. Dependency licenses are restricted to `MIT`, `BSD-3-Clause`, `BSD-2-Clause`, `Apache-2.0`. - A PR that touches only markdown or other files outside these filters triggers no CI at all. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ed6ebb..43a02b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,9 +150,10 @@ open coverage/index.html ## Releases [release-please](https://github.com/googleapis/release-please) owns versions and changelogs. -Every push to `main` opens or updates a release pull request that bumps `pubspec.yaml`, -regenerates `lib/src/version.dart` and writes `CHANGELOG.md`. Merge it only when a release is -intended; merging it tags the release and publishes the notes. +Every push to `main` opens or updates a release pull request that bumps the root `pubspec.yaml`, +carries that version into the CLI's `pubspec.yaml` and `lib/src/version.dart`, and writes +`CHANGELOG.md`. Merge it only when a release is intended; merging it tags the release and +publishes the notes. Do not bump a version or edit a `CHANGELOG.md` by hand. From 5aa014f8251c630ce31b31e32163c626c300dbac Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Mon, 26 Oct 2026 14:07:25 +0100 Subject: [PATCH 3/4] docs: install the CLI from pub.dev --- packages/vgv_ai_cli/README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/vgv_ai_cli/README.md b/packages/vgv_ai_cli/README.md index 89ed5eb..77b3589 100644 --- a/packages/vgv_ai_cli/README.md +++ b/packages/vgv_ai_cli/README.md @@ -14,11 +14,8 @@ current, and removes them again without touching your own configuration. `vgv_ai` is a Dart package. You need the [Dart SDK](https://dart.dev/get-dart) 3.13 or later. -It is not published on [pub.dev](https://pub.dev) yet, so install it from a -checkout of this repository: - ```sh -dart pub global activate --source=path +dart pub global activate vgv_ai_cli ``` This puts the `vgv_ai` executable on your path. Run `vgv_ai --help` to confirm From a2470ec3be101fe9c5cc45346017a509f95ed94d Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Mon, 26 Oct 2026 14:19:06 +0100 Subject: [PATCH 4/4] docs: describe the lockstep release --- AGENTS.md | 2 +- CONTRIBUTING.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 549af13..974cc0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,7 +155,7 @@ Each workflow under `.github/workflows/` is path-filtered, and every reusable wo - `vgv_ai_cli.yaml` runs on changes to itself, `.github/cspell.json`, `packages/vgv_ai_cli/lib/**`, `packages/vgv_ai_cli/test/**`, `packages/vgv_ai_cli/pubspec.yaml`, `packages/plugin_source/lib/**`, `packages/plugin_source/pubspec.yaml`, `bricks/**` and `tool/**`. Its jobs are `semantic-pull-request`, `build` (the reusable `dart_package.yml` in `packages/vgv_ai_cli`), `spell-check`, `verify-bundle` and `verify-pins`. - `plugin_source.yaml` runs on changes to itself and `packages/plugin_source/**`. Its jobs are `semantic-pull-request` and `build` (the reusable `dart_package.yml` in `packages/plugin_source`). - Both `build` jobs also run the cognitive complexity check on their package's `lib`, which fails when any function scores above 15. Split a function that crosses it into smaller ones rather than raising the threshold. Run it locally with the `cognitive_complexity` scanner from [kevmoo/analytica.dart](https://github.com/kevmoo/analytica.dart/tree/main/packages/cognitive_complexity). -- `release_please.yaml` runs on every push to `main`. release-please owns versions and changelogs (`.release-please-config.json`, `.release-please-manifest.json`). The repository releases as one unit, so any change can open or update the release PR, and merging it tags `vX.Y.Z`. Never bump a version or edit a `CHANGELOG.md` by hand. +- `release_please.yaml` runs on every push to `main`. release-please owns versions and changelogs (`.release-please-config.json`, `.release-please-manifest.json`). Both packages release together at one version, and merging the release PR tags the CLI `vX.Y.Z` and `plugin_source` as `plugin_source-vX.Y.Z`. Never bump a version or edit a `CHANGELOG.md` by hand. - `check_links.yaml` runs lychee over every markdown and Dart file on PRs and weekly. Placeholder URLs in fixtures, and links into private sibling repos, are listed in `.lycheeignore`. - `license_check.yaml` runs on changes to itself and either package's `pubspec.yaml`. Dependency licenses are restricted to `MIT`, `BSD-3-Clause`, `BSD-2-Clause`, `Apache-2.0`. - A PR that touches only markdown or other files outside these filters triggers no CI at all. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43a02b9..6e2ade4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,9 +150,8 @@ open coverage/index.html ## Releases [release-please](https://github.com/googleapis/release-please) owns versions and changelogs. -Every push to `main` opens or updates a release pull request that bumps the root `pubspec.yaml`, -carries that version into the CLI's `pubspec.yaml` and `lib/src/version.dart`, and writes -`CHANGELOG.md`. Merge it only when a release is intended; merging it tags the release and +Every push to `main` opens or updates a release pull request that bumps both packages to the +same version and writes their `CHANGELOG.md`. Merge it only when a release is intended; merging it tags the release and publishes the notes. Do not bump a version or edit a `CHANGELOG.md` by hand.