Skip to content

chore: migrate goreleaser to v2 APIs and add release documentation#122

Merged
michaelmcnees merged 3 commits intomainfrom
chore/goreleaser-v2-migration-and-release-docs
Apr 6, 2026
Merged

chore: migrate goreleaser to v2 APIs and add release documentation#122
michaelmcnees merged 3 commits intomainfrom
chore/goreleaser-v2-migration-and-release-docs

Conversation

@michaelmcnees
Copy link
Copy Markdown
Collaborator

@michaelmcnees michaelmcnees commented Apr 6, 2026

Summary

  • goreleaser v2 migration — silences all three deprecation warnings from the current release run:
    • archives.format (scalar) → formats (list)
    • dockers + docker_manifestsdockers_v2; updates Dockerfile.goreleaser to use $TARGETPLATFORM for multi-arch build context
    • Adds order: 0/1 to changelog.groups (was missing on Features and Bug Fixes entries)
  • LICENSE bundled in archives — adds a files stanza to .goreleaser.yaml so every release tarball includes LICENSE, satisfying BUSL-1.1's notice requirement
  • RELEASING.md — new contributor-facing release process guide covering: prerequisites, the full changeset → Version PR → tag → artifact flow, partial-failure recovery, pre-release instructions, and rollback steps
  • docs/superpowers/specs/ — adds historical spec files to version control (specs are tracked; plans remain gitignored)

Behavioral changes to call out

  • Platform-specific image tags are gone in production. The old pipeline published ghcr.io/dvflw/mantle:<version>-amd64 and -arm64 as intermediary tags. dockers_v2 only pushes the final multi-arch manifest tags (e.g. ghcr.io/dvflw/mantle:0.4.0). Update any CI or deploy configs referencing the suffixed form.
  • Floating tag behavior is unchangedlatest, major, major.minor are still only pushed for stable releases (pre-release versions get the versioned tag only).

Out of scope — tracked as follow-up issues

  • Rename release-please.ymlchangeset-version.yml
  • Pin alpine:3.21 in Dockerfile.goreleaser to a digest
  • Add go-licenses NOTICE generation step to the release pipeline

Test plan

  • Confirm goreleaser deprecation warnings are gone on next engine/v* tag push
  • Confirm release tarballs include a LICENSE file
  • Confirm multi-arch Docker manifest is published (no -amd64/-arm64 tags in production)
  • Review RELEASING.md for accuracy against the live pipeline

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Designed CLI commands for workflow validate/apply, migrations, health endpoints, workflow composition, parallel AI/tool steps, multi-node execution, data transformations, and an artifacts system.
  • Documentation

    • Added a release process guide plus comprehensive design specs for CI, local dev, config, scaffold, workflows, connectors, safety-net/versioning, env mapping, and more.
  • Chores

    • Updated packaging and Docker image publishing to support multi-arch tagging and adjusted changelog/tag behavior.

- Migrate archives.format (scalar) to formats (list) per goreleaser v2 deprecation
- Migrate dockers + docker_manifests to dockers_v2; update Dockerfile.goreleaser
  to use $TARGETPLATFORM for multi-arch build context
- Add order fields to changelog groups (Features=0, Bug Fixes=1)
- Bundle LICENSE in release archives to satisfy BUSL-1.1 notice requirement
- Add RELEASING.md with full release process documentation
- Add docs/superpowers/specs/ files to version control

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 6, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0a11710e-d1a3-4463-8679-51f1b850f7ef

📥 Commits

Reviewing files that changed from the base of the PR and between 491743c and d05ab0e.

📒 Files selected for processing (1)
  • docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md

📝 Walkthrough

Walkthrough

Adds a new release process guide, multiple design/spec documents covering CI, config, scaffold, workflows, DB/migrations, connectors, AI/tooling, multi-node distribution, data transforms, and packaging updates for engine goreleaser/Dockerfile.

Changes

Cohort / File(s) Summary
Release Process
RELEASING.md
New Changesets-driven release process doc: prerequisites, CI control flow, tag-driven artifact outputs, floating tag rules, Trivy behavior, and manual recovery procedures.
Engine Packaging
packages/engine/.goreleaser.yaml, packages/engine/Dockerfile.goreleaser
Goreleaser refactor to dockers_v2, conditional floating tags (skip for prereleases), include LICENSE in archives, and Dockerfile uses ARG TARGETPLATFORM for multi-arch binary selection.
Project Scaffold & CI
docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md, .../2026-03-18-ci-pipeline-design.md, .../2026-03-18-docker-compose-design.md
Adds Go project scaffold spec, CI workflow and golangci-lint rules, and local dev Docker Compose + Makefile target proposals.
Config & Env
docs/superpowers/specs/2026-03-18-config-system-design.md, .../2026-03-27-env-map-config-design.md
Viper-based config design with CLI/env precedence and --config semantics; introduces top-level env map and mandates wiring Config.Env into CEL evaluator APIs.
Health, Migrations & DB
docs/superpowers/specs/2026-03-18-health-endpoints-design.md, .../2026-03-18-migrations-design.md
Health endpoint handlers spec and DB Open contract; Goose-based migration runner, CLI migration commands, and initial SQL migration design.
Workflow Validation & Apply
docs/superpowers/specs/2026-03-18-workflow-validation-design.md, .../2026-03-18-workflow-apply-design.md
Offline YAML parse/validation with line/column errors and mantle validate; immutable workflow persistence with SHA-256 content-hash, versioning, and mantle apply CLI behavior.
Workflow Composition & Multi-node
docs/superpowers/specs/2026-03-27-workflow-composition-design.md, .../2026-03-19-multi-node-distribution-design.md
Child-workflow synchronous invocation, depth limits, cancellation cascade; multi-node coordination via Postgres claims, leases, reapers, and schema changes.
AI, Parallelism & Tooling
docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md
Phase 8 design: DAG-based implicit parallelism, LLM-driven tool-call loops, cached LLM responses for deterministic recovery, idempotent child creation, limits and observability metrics.
Data Transformation & Docker Connector
docs/superpowers/specs/2026-03-24-data-transformation-design.md, .../2026-03-25-docker-connector-artifacts-design.md
CEL custom functions/macros spec; Docker run connector and artifact system with artifact metadata types, tmp storage model, engine context helpers, and new workflow type fields.
Safety Net / v0.4.0
docs/superpowers/specs/2026-03-26-v040-safety-net-design.md
v0.4.0 design: mantle.yaml version guard, tmpstorage rename with deprecation path, key rotation CLI, queued executions, hooks, retry/rollback semantics, and migration summary.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐇 I hopped through pages, specs in tow,

Diagrams dreamed where ideas grow.
From tags to charts and CEL’s bright tune,
I nibble notes beneath the moon.
Tiny hop — big plans — onward soon!

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and accurately summarizes the primary changeset: migrating goreleaser to v2 APIs and adding release documentation, which aligns with the main changes in RELEASING.md and .goreleaser.yaml.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/goreleaser-v2-migration-and-release-docs

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 9

🧹 Nitpick comments (1)
docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md (1)

261-264: Consider varying sentence structure to improve readability.

Three consecutive validation rules begin with "Tool". While this is clear and correct, varying the sentence structure can enhance readability.

✍️ Suggested alternative phrasing
 - Tool `name` is unique within a step's tool list.
-- Tool `action` references a valid connector.
-- Tool params are valid for that connector (same validation as regular steps).
+- Each tool's `action` references a valid connector.
+- Parameters for each tool are valid for that connector (same validation as regular steps).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md`
around lines 261 - 264, The three validation bullets starting with "Tool" should
be rephrased to vary sentence structure and improve flow: change "Tool `name` is
unique within a step's tool list." to "Ensure each tool's `name` is unique
within a step's tool list.", change "Tool `action` references a valid
connector." to "Each tool's `action` must reference a valid connector.", change
"Tool params are valid for that connector (same validation as regular steps)."
to "Validate a tool's params against the corresponding connector's parameter
schema (same validation as regular steps).", and keep "`max_tool_rounds` is
within bounds." as "Ensure `max_tool_rounds` falls within the allowed bounds."
Use the symbols `name`, `action`, tool params, and `max_tool_rounds` to locate
and update the three bullets.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/superpowers/specs/2026-03-18-config-system-design.md`:
- Around line 19-25: The fenced code block in the markdown (the
package-structure snippet) is missing a language identifier; update the opening
triple-backtick for that block to include a language such as "text" (e.g.,
change ``` to ```text) so markdownlint rule MD040 is satisfied; locate the block
around the package layout in the
docs/superpowers/specs/2026-03-18-config-system-design.md file and add the
identifier to the existing fenced block.

In `@docs/superpowers/specs/2026-03-18-docker-compose-design.md`:
- Around line 47-53: The markdown fences around the Postgres DSN examples are
unlabeled and trigger MD040; add a language hint (e.g., use "text") to both
fenced code blocks that contain
"postgres://localhost:5432/mantle?sslmode=disable" and
"postgres://mantle:mantle@localhost:5432/mantle?sslmode=disable" so the blocks
become ```text ... ``` to satisfy markdownlint; ensure both occurrences are
updated consistently.

In `@docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md`:
- Around line 18-45: The three unlabeled fenced code blocks (the directory
listing block and the two version-output blocks) are triggering MD040; update
each opening triple-backtick to include a language label (e.g., change ``` to
```text) so the blocks become labeled (directory listing, default version
output, and ldflags version output). Ensure you only modify the three fences
surrounding the block starting with "cmd/mantle/" and the two blocks showing
"mantle dev ..." and "mantle v0.1.0 ..." so markdownlint no longer flags MD040.

In `@docs/superpowers/specs/2026-03-18-workflow-validation-design.md`:
- Line 24: The spec currently documents two different validator signatures —
Validate(*Workflow) at line 24 and Validate(result *ParseResult) at line 97 —
causing inconsistency; pick one canonical signature and update all mentions so
they match (e.g., change the heading/entry at line 24 or the definition at line
97) so the same symbol Validate and its single parameter type (either *Workflow
or *ParseResult) is used throughout the document and in the referenced
validate.go note; ensure any surrounding text that describes the parameter name
(result vs workflow) is updated to match the chosen signature.

In `@docs/superpowers/specs/2026-03-19-multi-node-distribution-design.md`:
- Line 196: The spec uses inconsistent table names: change the singular
identifier `workflow_execution` to the plural `workflow_executions` in the
sentence "If retries are exhausted, marks the `workflow_execution` as
`failed`..." so the doc consistently refers to `workflow_executions` (search for
`workflow_execution` occurrences and replace them with `workflow_executions`,
e.g., in the sentence mentioning marking as `failed` and cancelling pending
steps).

In `@docs/superpowers/specs/2026-03-27-workflow-composition-design.md`:
- Around line 59-64: The spec suggests adding a duplicate field MaxWorkflowDepth
to EngineConfig; instead, remove the add-field instruction and update the
document to describe setting the default and env binding for the existing
EngineConfig.MaxWorkflowDepth: state that the configuration loader should call
v.SetDefault("engine.max_workflow_depth", 10) and
v.BindEnv("engine.max_workflow_depth", "MANTLE_ENGINE_MAX_WORKFLOW_DEPTH") to
provide a default and environment override for the existing MaxWorkflowDepth
field on EngineConfig rather than re-defining the struct field.

In `@packages/engine/.goreleaser.yaml`:
- Around line 50-63: Add the QEMU setup action into the release workflow by
inserting a step that uses docker/setup-qemu-action@v3 immediately before the
docker/setup-buildx-action@v3 step in .github/workflows/release-engine.yml;
ensure the new step mirrors the existing action steps (name, uses:
docker/setup-qemu-action@v3) so QEMU is initialized prior to buildx for
multi-platform builds that rely on $TARGETPLATFORM in Dockerfile.goreleaser.

In `@RELEASING.md`:
- Around line 139-156: The prose inconsistently uses “pre-release” and
“prerelease”; standardize all prose occurrences to “pre-release” while keeping
the config key backtick-quoted as `prerelease: auto` (do not change the config
key). Update the header, descriptive sentences, and any inline text (e.g., the
paragraph that explains goreleaser's behavior and the sentence “goreleaser's
`prerelease: auto` publishes...”) so every non-code mention reads “pre-release”,
and ensure the code/config examples remain exactly as-is.
- Line 31: Replace the placeholder link text "[the relevant issue]" in
RELEASING.md with the actual issue URL referencing the tracked rename of the
workflow (the one noting release-please.yml → changeset-version.yml); locate the
sentence mentioning "release-please.yml" and update the bracketed reference to
point to the concrete issue link (e.g.,
https://github.com/your-repo/your-project/issues/NNN) so readers can follow the
tracked rename.

---

Nitpick comments:
In `@docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md`:
- Around line 261-264: The three validation bullets starting with "Tool" should
be rephrased to vary sentence structure and improve flow: change "Tool `name` is
unique within a step's tool list." to "Ensure each tool's `name` is unique
within a step's tool list.", change "Tool `action` references a valid
connector." to "Each tool's `action` must reference a valid connector.", change
"Tool params are valid for that connector (same validation as regular steps)."
to "Validate a tool's params against the corresponding connector's parameter
schema (same validation as regular steps).", and keep "`max_tool_rounds` is
within bounds." as "Ensure `max_tool_rounds` falls within the allowed bounds."
Use the symbols `name`, `action`, tool params, and `max_tool_rounds` to locate
and update the three bullets.
🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3ba41f4b-adb6-4b23-b7cf-8447c2922301

📥 Commits

Reviewing files that changed from the base of the PR and between 80d4c14 and a21fe70.

📒 Files selected for processing (18)
  • RELEASING.md
  • docs/superpowers/specs/2026-03-18-ci-pipeline-design.md
  • docs/superpowers/specs/2026-03-18-config-system-design.md
  • docs/superpowers/specs/2026-03-18-docker-compose-design.md
  • docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md
  • docs/superpowers/specs/2026-03-18-health-endpoints-design.md
  • docs/superpowers/specs/2026-03-18-migrations-design.md
  • docs/superpowers/specs/2026-03-18-workflow-apply-design.md
  • docs/superpowers/specs/2026-03-18-workflow-validation-design.md
  • docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md
  • docs/superpowers/specs/2026-03-19-multi-node-distribution-design.md
  • docs/superpowers/specs/2026-03-24-data-transformation-design.md
  • docs/superpowers/specs/2026-03-25-docker-connector-artifacts-design.md
  • docs/superpowers/specs/2026-03-26-v040-safety-net-design.md
  • docs/superpowers/specs/2026-03-27-env-map-config-design.md
  • docs/superpowers/specs/2026-03-27-workflow-composition-design.md
  • packages/engine/.goreleaser.yaml
  • packages/engine/Dockerfile.goreleaser

workflow/
workflow.go # Workflow, Step, Input, RetryPolicy structs
parse.go # Parse(filename) — YAML parsing with yaml.Node line tracking
validate.go # Validate(*Workflow) — structural validation rules
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Align the validator signature in both sections.

Line 24 documents Validate(*Workflow), but Line 97 defines Validate(result *ParseResult). Please keep one signature throughout the spec.

Suggested doc fix
-    validate.go        # Validate(*Workflow) — structural validation rules
+    validate.go        # Validate(*ParseResult) — structural validation rules

Also applies to: 97-97

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/superpowers/specs/2026-03-18-workflow-validation-design.md` at line 24,
The spec currently documents two different validator signatures —
Validate(*Workflow) at line 24 and Validate(result *ParseResult) at line 97 —
causing inconsistency; pick one canonical signature and update all mentions so
they match (e.g., change the heading/entry at line 24 or the definition at line
97) so the same symbol Validate and its single parameter type (either *Workflow
or *ParseResult) is used throughout the document and in the referenced
validate.go note; ensure any surrounding text that describes the parameter name
(result vs workflow) is updated to match the chosen signature.

Comment on lines +50 to 63
dockers_v2:
- ids: [mantle]
dockerfile: Dockerfile.goreleaser
build_flag_templates:
- "--platform=linux/amd64"
- image_templates:
- "ghcr.io/dvflw/mantle:{{ .Version }}-arm64"
use: buildx
ids: [mantle]
goos: linux
goarch: arm64
dockerfile: Dockerfile.goreleaser
build_flag_templates:
- "--platform=linux/arm64"

docker_manifests:
- name_template: "ghcr.io/dvflw/mantle:{{ .Version }}"
image_templates:
- "ghcr.io/dvflw/mantle:{{ .Version }}-amd64"
- "ghcr.io/dvflw/mantle:{{ .Version }}-arm64"
- name_template: "ghcr.io/dvflw/mantle:{{ .Major }}.{{ .Minor }}"
image_templates:
- "ghcr.io/dvflw/mantle:{{ .Version }}-amd64"
- "ghcr.io/dvflw/mantle:{{ .Version }}-arm64"
skip_push: auto
- name_template: "ghcr.io/dvflw/mantle:{{ .Major }}"
image_templates:
- "ghcr.io/dvflw/mantle:{{ .Version }}-amd64"
- "ghcr.io/dvflw/mantle:{{ .Version }}-arm64"
skip_push: auto
- name_template: "ghcr.io/dvflw/mantle:latest"
image_templates:
- "ghcr.io/dvflw/mantle:{{ .Version }}-amd64"
- "ghcr.io/dvflw/mantle:{{ .Version }}-arm64"
skip_push: auto
images:
- "ghcr.io/dvflw/mantle"
tags:
- "{{ .Version }}"
# Floating tags (major.minor, major, latest) are only pushed for stable
# releases. Empty template results are skipped by goreleaser, so these
# evaluate to "" and are dropped for any pre-release version.
- "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}{{ end }}"
- "{{ if not .Prerelease }}{{ .Major }}{{ end }}"
- "{{ if not .Prerelease }}latest{{ end }}"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== release workflow setup steps =="
rg -n -C2 'setup-qemu-action|setup-buildx-action|goreleaser-action|docker/login-action' .github/workflows/release-engine.yml

echo
echo "== goreleaser docker v2 config =="
rg -n -C2 'dockers_v2|ids:|images:|tags:' packages/engine/.goreleaser.yaml

echo
echo "== Dockerfile multi-platform binary path =="
rg -n -C2 'ARG TARGETPLATFORM|COPY \\$TARGETPLATFORM/mantle' packages/engine/Dockerfile.goreleaser

Repository: dvflw/mantle

Length of output: 989


Add docker/setup-qemu-action before Buildx in the release workflow.

The release workflow is missing QEMU initialization for multi-platform Docker builds. With dockers_v2 configured for multi-platform images and Dockerfile.goreleaser expecting platform-specific binaries via $TARGETPLATFORM, ARM64 RUN layers will fail without QEMU. Add docker/setup-qemu-action@v3 immediately before docker/setup-buildx-action@v3 in .github/workflows/release-engine.yml (around line 32).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/engine/.goreleaser.yaml` around lines 50 - 63, Add the QEMU setup
action into the release workflow by inserting a step that uses
docker/setup-qemu-action@v3 immediately before the docker/setup-buildx-action@v3
step in .github/workflows/release-engine.yml; ensure the new step mirrors the
existing action steps (name, uses: docker/setup-qemu-action@v3) so QEMU is
initialized prior to buildx for multi-platform builds that rely on
$TARGETPLATFORM in Dockerfile.goreleaser.

5b. release-helm.yml → helm push OCI + GitHub Release
```

> **Note on workflow naming:** `release-please.yml` is named after a tool we evaluated but didn't adopt — it actually runs the Changesets CLI. A rename to `changeset-version.yml` is tracked in [the relevant issue].
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Replace placeholder link text with an actual URL.

Line 31 references [the relevant issue] but does not point to a concrete issue link, so readers cannot follow up.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@RELEASING.md` at line 31, Replace the placeholder link text "[the relevant
issue]" in RELEASING.md with the actual issue URL referencing the tracked rename
of the workflow (the one noting release-please.yml → changeset-version.yml);
locate the sentence mentioning "release-please.yml" and update the bracketed
reference to point to the concrete issue link (e.g.,
https://github.com/your-repo/your-project/issues/NNN) so readers can follow the
tracked rename.

Comment on lines +139 to +156
## Pre-releases

To cut a pre-release (e.g. `0.5.0-rc.1`), no changeset is needed — bump the version manually and tag directly:

```bash
# 1. Set the pre-release version in package.json
# Edit packages/engine/package.json: "version": "0.5.0-rc.1"
git add packages/engine/package.json
git commit -m "chore: bump engine to 0.5.0-rc.1"
git push origin main

# 2. Tag and push
git tag engine/v0.5.0-rc.1
git push origin engine/v0.5.0-rc.1
```

goreleaser's `prerelease: auto` publishes the GitHub Release as a pre-release when the version contains a pre-release identifier. The versioned Docker image (`0.5.0-rc.1`) is pushed; floating tags (`latest`, `major`, `major.minor`) are not.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Standardize “pre-release” wording in prose.

The document mixes “pre-release” and “prerelease.” Keep prerelease: auto as-is (config key), but use one prose variant consistently for readability.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~155-~155: Do not mix variants of the same word (‘prerelease’ and ‘pre-release’) within a single text.
Context: ...in engine/v0.5.0-rc.1 ``` goreleaser's prerelease: auto publishes the GitHub Release as ...

(EN_WORD_COHERENCY)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@RELEASING.md` around lines 139 - 156, The prose inconsistently uses
“pre-release” and “prerelease”; standardize all prose occurrences to
“pre-release” while keeping the config key backtick-quoted as `prerelease: auto`
(do not change the config key). Update the header, descriptive sentences, and
any inline text (e.g., the paragraph that explains goreleaser's behavior and the
sentence “goreleaser's `prerelease: auto` publishes...”) so every non-code
mention reads “pre-release”, and ensure the code/config examples remain exactly
as-is.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 6, 2026

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

An unexpected error occurred while generating fixes: Resource not accessible by integration - https://docs.github.com/rest/git/trees#create-a-tree

@michaelmcnees
Copy link
Copy Markdown
Collaborator Author

Actionable comments posted: 9

🧹 Nitpick comments (1)

docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md (1)> 261-264: Consider varying sentence structure to improve readability.

Three consecutive validation rules begin with "Tool". While this is clear and correct, varying the sentence structure can enhance readability.

✍️ Suggested alternative phrasing

 - Tool `name` is unique within a step's tool list.
-- Tool `action` references a valid connector.
-- Tool params are valid for that connector (same validation as regular steps).
+- Each tool's `action` references a valid connector.
+- Parameters for each tool are valid for that connector (same validation as regular steps).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md`
around lines 261 - 264, The three validation bullets starting with "Tool" should
be rephrased to vary sentence structure and improve flow: change "Tool `name` is
unique within a step's tool list." to "Ensure each tool's `name` is unique
within a step's tool list.", change "Tool `action` references a valid
connector." to "Each tool's `action` must reference a valid connector.", change
"Tool params are valid for that connector (same validation as regular steps)."
to "Validate a tool's params against the corresponding connector's parameter
schema (same validation as regular steps).", and keep "`max_tool_rounds` is
within bounds." as "Ensure `max_tool_rounds` falls within the allowed bounds."
Use the symbols `name`, `action`, tool params, and `max_tool_rounds` to locate
and update the three bullets.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/superpowers/specs/2026-03-18-config-system-design.md`:
- Around line 19-25: The fenced code block in the markdown (the
package-structure snippet) is missing a language identifier; update the opening
triple-backtick for that block to include a language such as "text" (e.g.,
change ``` to ```text) so markdownlint rule MD040 is satisfied; locate the block
around the package layout in the
docs/superpowers/specs/2026-03-18-config-system-design.md file and add the
identifier to the existing fenced block.

In `@docs/superpowers/specs/2026-03-18-docker-compose-design.md`:
- Around line 47-53: The markdown fences around the Postgres DSN examples are
unlabeled and trigger MD040; add a language hint (e.g., use "text") to both
fenced code blocks that contain
"postgres://localhost:5432/mantle?sslmode=disable" and
"postgres://mantle:mantle@localhost:5432/mantle?sslmode=disable" so the blocks
become ```text ... ``` to satisfy markdownlint; ensure both occurrences are
updated consistently.

In `@docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md`:
- Around line 18-45: The three unlabeled fenced code blocks (the directory
listing block and the two version-output blocks) are triggering MD040; update
each opening triple-backtick to include a language label (e.g., change ``` to
```text) so the blocks become labeled (directory listing, default version
output, and ldflags version output). Ensure you only modify the three fences
surrounding the block starting with "cmd/mantle/" and the two blocks showing
"mantle dev ..." and "mantle v0.1.0 ..." so markdownlint no longer flags MD040.

In `@docs/superpowers/specs/2026-03-18-workflow-validation-design.md`:
- Line 24: The spec currently documents two different validator signatures —
Validate(*Workflow) at line 24 and Validate(result *ParseResult) at line 97 —
causing inconsistency; pick one canonical signature and update all mentions so
they match (e.g., change the heading/entry at line 24 or the definition at line
97) so the same symbol Validate and its single parameter type (either *Workflow
or *ParseResult) is used throughout the document and in the referenced
validate.go note; ensure any surrounding text that describes the parameter name
(result vs workflow) is updated to match the chosen signature.

In `@docs/superpowers/specs/2026-03-19-multi-node-distribution-design.md`:
- Line 196: The spec uses inconsistent table names: change the singular
identifier `workflow_execution` to the plural `workflow_executions` in the
sentence "If retries are exhausted, marks the `workflow_execution` as
`failed`..." so the doc consistently refers to `workflow_executions` (search for
`workflow_execution` occurrences and replace them with `workflow_executions`,
e.g., in the sentence mentioning marking as `failed` and cancelling pending
steps).

In `@docs/superpowers/specs/2026-03-27-workflow-composition-design.md`:
- Around line 59-64: The spec suggests adding a duplicate field MaxWorkflowDepth
to EngineConfig; instead, remove the add-field instruction and update the
document to describe setting the default and env binding for the existing
EngineConfig.MaxWorkflowDepth: state that the configuration loader should call
v.SetDefault("engine.max_workflow_depth", 10) and
v.BindEnv("engine.max_workflow_depth", "MANTLE_ENGINE_MAX_WORKFLOW_DEPTH") to
provide a default and environment override for the existing MaxWorkflowDepth
field on EngineConfig rather than re-defining the struct field.

In `@packages/engine/.goreleaser.yaml`:
- Around line 50-63: Add the QEMU setup action into the release workflow by
inserting a step that uses docker/setup-qemu-action@v3 immediately before the
docker/setup-buildx-action@v3 step in .github/workflows/release-engine.yml;
ensure the new step mirrors the existing action steps (name, uses:
docker/setup-qemu-action@v3) so QEMU is initialized prior to buildx for
multi-platform builds that rely on $TARGETPLATFORM in Dockerfile.goreleaser.

In `@RELEASING.md`:
- Around line 139-156: The prose inconsistently uses “pre-release” and
“prerelease”; standardize all prose occurrences to “pre-release” while keeping
the config key backtick-quoted as `prerelease: auto` (do not change the config
key). Update the header, descriptive sentences, and any inline text (e.g., the
paragraph that explains goreleaser's behavior and the sentence “goreleaser's
`prerelease: auto` publishes...”) so every non-code mention reads “pre-release”,
and ensure the code/config examples remain exactly as-is.
- Line 31: Replace the placeholder link text "[the relevant issue]" in
RELEASING.md with the actual issue URL referencing the tracked rename of the
workflow (the one noting release-please.yml → changeset-version.yml); locate the
sentence mentioning "release-please.yml" and update the bracketed reference to
point to the concrete issue link (e.g.,
https://github.com/your-repo/your-project/issues/NNN) so readers can follow the
tracked rename.

---

Nitpick comments:
In `@docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md`:
- Around line 261-264: The three validation bullets starting with "Tool" should
be rephrased to vary sentence structure and improve flow: change "Tool `name` is
unique within a step's tool list." to "Ensure each tool's `name` is unique
within a step's tool list.", change "Tool `action` references a valid
connector." to "Each tool's `action` must reference a valid connector.", change
"Tool params are valid for that connector (same validation as regular steps)."
to "Validate a tool's params against the corresponding connector's parameter
schema (same validation as regular steps).", and keep "`max_tool_rounds` is
within bounds." as "Ensure `max_tool_rounds` falls within the allowed bounds."
Use the symbols `name`, `action`, tool params, and `max_tool_rounds` to locate
and update the three bullets.

🪄 Autofix (Beta)
❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info

@claude address these items, please

@claude
Copy link
Copy Markdown

claude bot commented Apr 6, 2026

Claude finished @michaelmcnees's task in 2m 20s —— View job


Addressing CodeRabbit Review Comments

Tasks

  • Read files to understand current state
  • Fix MD040: add text language identifier to fenced block in config-system-design.md
  • Fix MD040: add text language identifiers to 2 fenced blocks in docker-compose-design.md
  • Fix MD040: add text language identifiers to 3 fenced blocks in go-project-scaffold-design.md
  • Fix validator signature inconsistency in workflow-validation-design.md — updated Validate(*Workflow)Validate(*ParseResult) to match the actual function definition at line 97
  • Fix table name inconsistency in multi-node-distribution-design.mdworkflow_executionworkflow_executions
  • Fix duplicate field description in workflow-composition-design.md — reworded to "Ensure EngineConfig.MaxWorkflowDepth uses default 10 and is bound to env/config"
  • Fix sentence structure in ai-tool-use-parallel-execution-design.md — varied the validation rule bullets
  • "pre-release" wording in RELEASING.md — already consistent (prose uses pre-release; prerelease: auto is a config key in backticks and cannot be changed)
  • Commit and push changes (commit 491743c)

Not addressed

  • Placeholder link in RELEASING.md line 31 ([the relevant issue]) — I couldn't look up the GitHub issue number for the release-please.ymlchangeset-version.yml rename. Please replace it with the actual issue link once you locate it.
  • Add docker/setup-qemu-action to .github/workflows/release-engine.yml — I cannot modify files in .github/workflows/ due to GitHub App permissions. You'll need to add this step manually before docker/setup-buildx-action@v3:
    - uses: docker/setup-qemu-action@v3
    
    - uses: docker/setup-buildx-action@v3
    This is important for correct multi-platform ARM64 builds via $TARGETPLATFORM in Dockerfile.goreleaser.
    |

- Add language identifiers to unlabeled fenced code blocks (MD040) in
  config-system, docker-compose, and go-project-scaffold specs
- Align Validate() signature to Validate(*ParseResult) throughout
  workflow-validation-design.md
- Fix singular/plural table name: workflow_execution → workflow_executions
  in multi-node-distribution-design.md
- Reword EngineConfig field to avoid implying a duplicate struct field
  in workflow-composition-design.md
- Vary sentence structure in ai-tool-use validation rule bullets

Co-authored-by: Michael McNees <michaelmcnees@users.noreply.github.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 6, 2026

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 6, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md`:
- Line 151: Three fenced code blocks are missing language identifiers (MD040)
causing lint/render issues; update the three unlabeled fences by adding explicit
languages: mark the first block (step_executions YAML-like snippet containing
keys like step_executions, id, execution_id) with "text" or "yaml", mark the
pseudocode block that defines conversation handling and child step
creation/lookup (contains variables conversation, cached_llm_responses,
tool_calls, child_row) with "python" or "text", and mark the execution tree
block (starts with "EXECUTION abc123" and multiline status lines) with "text";
ensure each opening triple-backtick includes the chosen language identifier to
satisfy MD040.
- Around line 69-72: The spec statement claiming "No `continue_on_failure`
option in V1.1" contradicts the orchestrator's existing behavior for steps
tagged `continue_on_error=true`; reconcile by updating the spec text and
terminology: explicitly reference the existing `continue_on_error` flag used by
the orchestrator (and note there is no separate `continue_on_failure` setting),
describe that steps with `continue_on_error=true` are considered resolved for
downstream scheduling even when they fail, and clarify that V1.1's cascading
failure model only applies to steps without `continue_on_error=true`; update the
paragraph mentioning V1.1 and the cascading model and add a short note naming
the orchestrator behavior (`continue_on_error`) so implementers know which flag
controls downstream scheduling.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ff4af8b9-6c8e-45f9-9538-618b7ba5b107

📥 Commits

Reviewing files that changed from the base of the PR and between a21fe70 and 491743c.

📒 Files selected for processing (7)
  • docs/superpowers/specs/2026-03-18-config-system-design.md
  • docs/superpowers/specs/2026-03-18-docker-compose-design.md
  • docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md
  • docs/superpowers/specs/2026-03-18-workflow-validation-design.md
  • docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md
  • docs/superpowers/specs/2026-03-19-multi-node-distribution-design.md
  • docs/superpowers/specs/2026-03-27-workflow-composition-design.md
✅ Files skipped from review due to trivial changes (4)
  • docs/superpowers/specs/2026-03-18-docker-compose-design.md
  • docs/superpowers/specs/2026-03-18-go-project-scaffold-design.md
  • docs/superpowers/specs/2026-03-18-config-system-design.md
  • docs/superpowers/specs/2026-03-18-workflow-validation-design.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/superpowers/specs/2026-03-27-workflow-composition-design.md

@michaelmcnees
Copy link
Copy Markdown
Collaborator Author

@claude:

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @docs/superpowers/specs/2026-03-19-ai-tool-use-parallel-execution-design.md:

  • Line 151: Three fenced code blocks are missing language identifiers (MD040)
    causing lint/render issues; update the three unlabeled fences by adding explicit
    languages: mark the first block (step_executions YAML-like snippet containing
    keys like step_executions, id, execution_id) with "text" or "yaml", mark the
    pseudocode block that defines conversation handling and child step
    creation/lookup (contains variables conversation, cached_llm_responses,
    tool_calls, child_row) with "python" or "text", and mark the execution tree
    block (starts with "EXECUTION abc123" and multiline status lines) with "text";
    ensure each opening triple-backtick includes the chosen language identifier to
    satisfy MD040.
  • Around line 69-72: The spec statement claiming "No continue_on_failure
    option in V1.1" contradicts the orchestrator's existing behavior for steps
    tagged continue_on_error=true; reconcile by updating the spec text and
    terminology: explicitly reference the existing continue_on_error flag used by
    the orchestrator (and note there is no separate continue_on_failure setting),
    describe that steps with continue_on_error=true are considered resolved for
    downstream scheduling even when they fail, and clarify that V1.1's cascading
    failure model only applies to steps without continue_on_error=true; update the
    paragraph mentioning V1.1 and the cascading model and add a short note naming
    the orchestrator behavior (continue_on_error) so implementers know which flag
    controls downstream scheduling.

@claude
Copy link
Copy Markdown

claude bot commented Apr 6, 2026

Claude finished @michaelmcnees's task in 1m 8s —— View job


Addressing CodeRabbit Review Comments

Tasks

  • Read file to verify findings
  • Fix MD040: add text language identifier to 3 fenced code blocks (lines 151, 203, 270)
  • Fix continue_on_failure vs continue_on_error inconsistency (line 71) — replaced the inaccurate "No continue_on_failure option" note with an accurate description of the existing continue_on_error behavior
  • Commit and push (commit d05ab0e)

…uracy

- Add `text` language identifier to three unlabeled fenced code blocks
- Replace inaccurate `continue_on_failure` note with accurate `continue_on_error` description

Co-authored-by: Michael McNees <michaelmcnees@users.noreply.github.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 6, 2026

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 6, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@michaelmcnees michaelmcnees merged commit 821a97c into main Apr 6, 2026
7 checks passed
michaelmcnees pushed a commit that referenced this pull request Apr 7, 2026
- release-engine.yml: add docker/setup-qemu-action@v3 before Buildx
  to support multi-platform (ARM64) Docker builds; without QEMU,
  ARM64 RUN layers fail in buildx emulation
- RELEASING.md: replace [the relevant issue] placeholder with actual
  link to #123 (rename release-please.yml to changeset-version.yml)

https://claude.ai/code/session_01CuTGMFzUAdw5L5p5n9vEa5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant