Build and Report

Post-implementation close for a forge run. Merges work-unit worktrees (if any), bumps the version per the consuming project's convention, runs the project's build, and emits the final report. Stack-agnostic: concrete commands live in the consuming project's own CLAUDE.md.

This skill handles two paths:

• Parallel-implementation path — /forge:dispatch-implementation ran; one or more work-unit worktrees need merging into the active branch before build.
• In-session path — the orchestrator implemented the plan directly in the main session; no worktrees to merge. Skip merge, go straight to version bump + build.

Required Inputs

• The approved master plan in conversation context (the report references its steps + risks).
• One of:
• All implementer reports from the most recent /forge:dispatch-implementation run (parallel path), OR
• The orchestrator's in-session edit summary (in-session path).
• The consuming project's CLAUDE.md, which provides stack-specific build commands and the version-bump rule. (Note: this is the user's project CLAUDE.md, NOT the forge plugin's own files.)

Procedure

1. Aggregate implementation status

Parallel path: for each implementer report:

• Confirm "done-when criterion: yes" (not "no" / "partial-because"). Any "no" or "partial" is a blocker — surface to the user before proceeding.
• Confirm the Blockers section is empty. If a hard blocker exists, route to the user; do NOT silently proceed to merge.

Tabulate:

| Unit | Status | Files changed | Tests | Notes |
|------|--------|---------------|-------|-------|
| W1 | Done | … | passed | … |
| W2 | Blocked | … | n/a | <blocker summary, link to implementer report> |

If any unit is blocked, STOP. Surface the blocker to the user; do not merge worktrees with incomplete work.

In-session path: restate the orchestrator's edit summary with file:line for each change, mapped to the plan's steps. Confirm each step's done-when criterion was met before proceeding.

2. Merge work-unit worktrees (parallel path only)

Skip this step on the in-session path — there are no worktrees to merge.

Each implementer ran in isolation: "worktree" and committed once. Aggregate by merging each unit branch back to the working branch in dependency order (the plan's contract clause numbering is a reasonable proxy when there is no explicit dependency graph).

MUST invoke Bash for each merge with a clear description:

Bash(
  command: "git merge --no-ff <unit-branch>",
  description: "Merge work unit W<N> back into the active branch"
)

Resolve any merge conflict by reading both sides + the plan's contract clauses; never blindly accept either side. Conflicts usually signal that two units' "Files touched" sets overlapped — that's a planning gap to note in the final report's "what we'd improve" section.

3. Re-verify each step's done-when criterion against the merged tree

The step's Done when criterion is the canonical verification step (preferred form: a verification command). Run it against the merged tree, regardless of which path you took.

For each step:

• If the criterion is a command, invoke Bash. Record pass/fail + output snippet on fail.
• If the criterion is a manual smoke test, surface it in the final report as "manual-smoke-required: <steps>" so the user knows what to verify by hand.

If a command-based criterion fails, STOP. The merge is complete but the feature does not satisfy the plan. Surface to the user before bumping versions or producing the final report.

4. Bump the version, then run the project's build / verification commands

Forge is stack-agnostic; the actual commands depend on the consuming project. Read the consuming project's CLAUDE.md "Build Commands" section (or the closest equivalent it carries) for:

• The version-bump file(s) and the conventional bump rule (semver patch / minor / major). Examples: plugin.xml + build.gradle.kts for IntelliJ plugins; package.json for Node; Cargo.toml for Rust; pyproject.toml for Python; .claude-plugin/plugin.json for Claude Code plugins.
• The build command (e.g. ./gradlew buildPlugin, npm run build, cargo build, etc.).
• The verification command (test suite, type-check, lint, smoke build) appropriate to the change set.

Bump the version BEFORE running the build, so the build artifact carries the new version number.

If the consuming project's CLAUDE.md does not specify these, MUST invoke AskUserQuestion with the full schema below — populate the first 2–3 option labels with concrete commands you discovered from the project (Makefile target, package.json script, build tool config, etc.) and keep "Skip build" as the last option. Do NOT invent commands you did not see in the project.

AskUserQuestion(questions: [{
  question: "The project's CLAUDE.md does not specify build commands. Which should I run?",
  header: "Build",
  multiSelect: false,
  options: [
    { label: "<discovered command 1>", description: "<what this command does, with the file/script it came from>" },
    { label: "<discovered command 2>", description: "<what this command does, with the file/script it came from>" },
    { label: "Skip build", description: "Complete the workflow without building. The final report will note that build verification was skipped." }
  ]
}])

For each command, MUST invoke Bash with a description:

Bash(
  command: "<project's build command from CLAUDE.md>",
  description: "Run project build to verify the merged change set compiles"
)

If the build fails: STOP. Surface the failure to the user with the failing output; do not paper over with --no-verify or skip flags.

5. Produce the final report

Append a single markdown report to the conversation, following the structure in references/final-report.md. The report MUST include these two sections, named exactly:

Pitch both sections at a developer who did NOT follow the implementation and will skim. Technical terms and concrete commands are fine — this reader is a dev; a tour of the change's internals is not — that depth trains readers to accept without reading.

• How to test this feature — step-by-step the reader can execute cold. Name the entry point (menu item / URL / command), concrete commands where they help (npm run dev, the curl call, the test target), the inputs to try, what counts as success, and which edge cases to poke. Skip the change's internals — the reader is verifying behavior, not reviewing the diff.
• How is this feature useful? — the user-visible benefit. Lead with the pain or goal; describe what changes; what they can now do that they couldn't before. Technical terms are fine; module/class walkthroughs are not. If the section needs a map of the implementation to make sense, it has gone too deep.

For the full report template, see references/final-report.md.

Critical Constraints

• NEVER skip the merge-conflict resolution step (parallel path). Auto-accepting one side discards the other implementer's work.
• NEVER skip a failing done-when criterion. Step 3 verifies the merged change matches the plan's behaviour, not just that it compiles.
• NEVER skip a failing build. --no-verify or equivalent flags hide regressions; the build is the workflow's last safety net.
• NEVER invent build commands. If the project's CLAUDE.md does not name them, ask the user. Inventing a command risks silent breakage.
• NEVER write the final report without both mandatory sections. "How to test this feature" and "How is this feature useful?" are workflow contract; report renderers downstream rely on those exact headings.
• NEVER write the report in implementer jargon. Both mandatory sections are user-facing — pitched at a developer who didn't follow the run. Commands, endpoints, and technology names are fine; plan machinery (W-IDs, contract clauses), file-by-file change lists, and class-level internals are not.

Next Step

Final step. The workflow is complete when this skill returns the report to the user.

Additional resources

• For the full final-report template (with the two mandatory sections in their canonical form), see references/final-report.md