build2-community/build2-review

What does build2-review do?

Resolve ROOT

Let HERE be the directory that contains this SKILL.md (absolute path from the system context).

ROOT is the build2 skill tree. Use the first candidate whose guides/packaging-guide-review.md exists:

1. HERE/../build2 (sibling layout: this directory next to a build2 skill, including a copy into a user-level skills directory)
2. HERE/../.. (nested layout: this directory under the build2 skill's skills/ subdirectory)

If neither exists, stop.

All later read_file paths are ${ROOT}/....

This is a read-only, local sanity check. It exists to catch packaging problems before you publish, by running the same checklist a cppget.org reviewer would use against the repository. It must never create, comment on, or merge a GitHub issue or pull request, never push a branch, never send email, and never modify the repository under review (no commits, no tags, no file edits, no bdep release, no bdep publish, no git push). If a step below would make such a change, skip it and turn it into a reported finding instead. The repository under review must come out of this check exactly as it went in. Drafting a plan for the reported findings, without carrying it out, does not count as a change, see "Plan mode" below for when that applies.

The checklist and criteria in ${ROOT}/guides/packaging-guide-review.md are the source of truth. Copy the checklist items. Do not paraphrase the required criteria. Do not invent review criteria.

Reviews cover build and packaging support only. Ignore upstream source quality, upstream docs, and style of upstream C/C++.

Hard rules

1. No externally visible changes: never create, comment on, or merge a GitHub issue or pull request, never push a branch, never send email. This is unconditional, it holds even if the user explicitly asks for one of these mid-run: decline and point them to the separate manual review workflow (see "Stop and ask" below) rather than doing it here.
2. No changes to the repository under review: no commits, tags, or file edits, no git push, no bdep release, no bdep publish. Inspection only (git log, git show, git diff, reading files). If you build or test something to verify an item, do it out-of-tree in a scratch directory, never inside the reviewed repository's working tree.
3. If given a local path, use it in place, read-only. Do not check out a different ref, stash, or reset it.
4. If given a remote repo or URL, clone it read-only into a scratch directory under /tmp/claude/. Never use push-capable remotes or git push. Treat the clone as disposable.
5. Never tick a checklist item without personally verifying it on this run.
6. Blocking vs non-blocking follows the guide's criteria. When in doubt, say so rather than silently downgrading a conceptual buildfile error.
7. The output is a report in the conversation (optionally also written to a scratch file under /tmp/claude/). Never post it anywhere external.

Mandatory reads (before reporting findings)

Read these files in full with read_file before reporting any findings. Do not skim.

1. ${ROOT}/guides/packaging-guide-review.md
2. ${ROOT}/guides/packaging-guide-antipatterns.md
3. ${ROOT}/HOWTO/package-naming.md
4. ${ROOT}/guides/packaging-guide-testing.md, Step 9 ("Test the Package") only. Step 10 ("Publish") merges review into main and is out of scope here, ignore it.

Load on demand from the map at the end. The Initial Review Checklist inside packaging-guide-review.md is the checklist you work through. That file is the only copy.

Arguments

$ARGUMENTS is the text after /build2-review (or after /build2 review). Parse in order. The first matching rule wins.

First token	Kind
empty / omitted	auto-detect after resolving the target
initial	full initial-submission checklist
version	new upstream version, diff-based
revision	new packaging revision, diff-based plus extra checks
anything else	treat as <repo-or-local-path> and auto-detect kind

Remaining tokens: <repo-or-local-path> (GitHub URL, owner/repo, or a local clone path) and optional <version>. If the target is missing, ask.

Report the chosen kind and version to the user before starting.

Get the repository

If the user gave a local path, use it as-is, read-only.

Otherwise clone read-only into a scratch directory (never push to this clone, never add it as a push target for anything else):

git clone --recurse-submodules --shallow-submodules <url> /tmp/claude/<name>

Classify

Determine <VERSION> from the manifest version: field (the latest released tag if there are several packages). Determine kind:

Evidence	Kind
No released tag yet, or the reviewed ref is still the first bdep new commit	initial
A vX.Y.Z tag already exists and this version is X.Y.Z+R	revision
A previous version was tagged and this is a new X.Y.Z	version

Verify the first commit of the repository (read-only):

git log -p "$(git rev-list --all | tail -1)"

That commit must contain only files generated by bdep new, and its message must be the exact command line. Record any deviation as a finding. Do not ignore it.

Kind: initial

Work through every item in the Initial Review Checklist section of packaging-guide-review.md against the repository. Tick an item only after personally verifying it (tree, manifest, buildfiles, install layout, tests, tags). Use the linked HOWTO/guide for each item rather than memory.

Classify each finding exactly as the guide does:

Class	When
Blocking	high severity or impact, many users, conceptual error (wrong compile options in buildfiles), or cannot be fixed later without breaking compatibility
Non-blocking	should be fixed in a revision or the next version, does not fail the check
Note	observation only

Load on demand while checking:

• names: ${ROOT}/HOWTO/package-naming.md
• license: ${ROOT}/guides/packaging-license.md
• accompanying -tests summary / README: ${ROOT}/HOWTO/tests-extra-dependencies.md
• private headers: ${ROOT}/HOWTO/third-party-private-headers.md
• compile options: ${ROOT}/HOWTO/buildfile-compile-options.md
• what not to do: ${ROOT}/guides/packaging-guide-antipatterns.md
• diary-style comments or notes in buildfiles, manifest, or READMEs (process narration, an earlier approach that did not work, a mishap along the way): ${ROOT}/guides/packaging-guide-antipatterns.md, "Don't leave diary-style comments or notes"

When verifying "Uses git submodule and symlinks for upstream": also run find . -type l -exec test -d {} \; -print in each package directory and confirm every result has a matching symlink=dir entry in that package's own <pkg>/.gitattributes (see ${ROOT}/guides/packaging-guide-summary.md Step 5). git does not record symlink type, so a directory symlink missing this entry silently breaks a Windows checkout. Treat a missing entry as blocking.

Test install and distribution

Static inspection of the checklist is not enough. Also build the package out-of-tree to catch what only shows up at build time (missing or private headers reaching the install tree, files missing from the buildfile graph, broken clean rules). Do this in a scratch directory under /tmp/claude/, never inside the reviewed repository. Follow "Step 9: Test the Package" in ${ROOT}/guides/packaging-guide-testing.md:

1. Installed case: b install config.install.root=/tmp/claude/<name>-install, then build and run tests/ out-of-source against that installed copy. Confirm nothing unexpected got installed (no missing headers, no private headers installed by mistake).
2. Source distribution: b dist config.dist.root=/tmp/claude/<name>-dist config.dist.uncommitted=true, then in the extracted archive run configure, update, test, and clean. A green bdep test alone is not sufficient, this is how cppget.org actually builds the package.

Remove both scratch directories afterward. Record any failure as a finding (a package that fails to install or distribute correctly is normally blocking).

Report

Present the results to the user using the same section layout as the guide's outcome comment, but do not post it anywhere:

Blocking issues:

...

Non-blocking issues:

...

Notes:

...

Omit empty sections. If you wrote a scratch copy, mention its path.

Kind: version

Diff the base (previously reviewed) version against the target version. Prefer a local git diff <old-tag>..<new-tag> if both tags are available in the clone, otherwise the GitHub compare view:

https://github.com/<owner>/<project>/compare/vOLD...vNEW

Watch build-level compatibility: renamed exported targets or config variables are breaking even when upstream's API is stable.

Report one of:

1. No substantial packaging changes, no issues: say so plainly, no checklist needed.
2. No substantial packaging changes, there are issues: list them directly (no checklist).
3. Substantial packaging changes: run the full initial procedure above, checklist plus the install and distribution test.

Kind: revision

Same as version, plus flag it as a finding if any of these does not hold:

• Changes are limited to bug fixes in buildfiles, manifest, and similar packaging files.
• Upstream source fixes are limited to critical bugs backported from upstream.
• Strictly backwards-compatible with the version it replaces.
• No major structural changes (source layout, exported target names, config variable names).

Plan mode

This skill stays read-only either way, it never carries out the fixes itself. What changes is only whether a plan for the required changes and improvements gets drafted alongside the report.

• If the current session is in plan mode (the assistant is expected to propose an implementation plan for approval before making changes, rather than act right away): after reporting, also draft a plan that addresses the blocking and non-blocking findings, then present it through whatever plan-approval mechanism the environment provides. Scope the plan to blocking and non-blocking findings, skip notes unless the user asks. Group related fixes, and call out any that touch generated bdep new layout, manifest, or buildfile files needing particular care or ordering.
• Otherwise, follow the established reporting flow above and stop there. Do not draft, propose, or hint at an implementation plan, the fixes are for the user or a separate workflow to carry out.

Stop and ask

Stop rather than guess when any of these is true:

• You cannot determine the version or the kind.
• You cannot access the repository (clone fails, local path invalid).
• The first commit is not a bdep new commit and the user has not decided how to record that in the report.
• Blocking vs non-blocking is unclear for a finding that would break compatibility.
• The user asked to actually open the GitHub review issue/PR, merge something, or send the [email protected] email. That is a separate, out-of-scope workflow this skill does not perform.
• The user asked to create the package rather than check it (switch to build2-package).

On-demand map

Need	File
Checklist and criteria	${ROOT}/guides/packaging-guide-review.md
What not to do	${ROOT}/guides/packaging-guide-antipatterns.md
Names	${ROOT}/HOWTO/package-naming.md
License	${ROOT}/guides/packaging-license.md
Accompanying packages	${ROOT}/HOWTO/tests-extra-dependencies.md
Creating the package	../build2-package/SKILL.md