@zigrivers/scaffold 3.0.1 → 3.0.2

package/README.md

@@ -708,7 +708,7 @@ These are orthogonal to the pipeline — usable at any time, not tied to pipelin
 | Command | When to Use |
 |---------|-------------|
 | `scaffold run version-bump` | Mark a milestone with a version number without the full release ceremony. |
-| `scaffold run release` | Ship a new version — changelog, Git tag, and GitHub release. Supports `--dry-run`, `current`, and `rollback`. |
+| `scaffold run release` | Run your project's release ceremony — changelog plus whatever release artifacts that project defines. Supports `--dry-run`, `current`, and `rollback`. |
 | `scaffold run version` | Show the current Scaffold version. |
 | `scaffold run update` | Update Scaffold to the latest version. |
 | `scaffold run dashboard` | Open a visual progress dashboard in your browser. |
@@ -730,7 +730,7 @@ All of these are also available as slash commands (`/scaffold:release`, `/scaffo
 /scaffold:version-bump
 ```
 
-Bumps the version number and updates the changelog, but doesn't create tags, push, or publish a GitHub release. Think of it as a checkpoint.
+Bumps the version number and updates the changelog, but doesn't create tags, push, or run the formal release ceremony. Think of it as a checkpoint.
 
 ### Creating a release
 
@@ -742,7 +742,13 @@ Claude analyzes your commits since the last release, suggests whether this is a
 1. Running your project's tests
 2. Updating the version number in your project files
 3. Generating a changelog entry
-4. Creating a Git tag, GitHub release, and npm publish
+4. Executing the release artifacts your project defines
+
+Depending on the target project, that may include a Git tag, hosted release,
+package publish, deployment, registry update, or another project-specific
+release step. `/scaffold:release` is intentionally generic; it should follow
+the target project's own documented workflow rather than assuming npm or GitHub
+for every project.
 
 Options: `--dry-run` to preview, `minor`/`major`/`patch` to specify the bump, `current` to release an already-bumped version, `rollback` to undo.
 

package/knowledge/tools/release-management.md

@@ -6,7 +6,9 @@ topics: [release, versioning, changelog, git]
 
 # Release Management
 
-Expert knowledge for release engineering including semantic versioning, conventional commit parsing, changelog generation, quality gates, and rollback procedures.
+Expert knowledge for release engineering including semantic versioning,
+conventional commit parsing, changelog generation, quality gates, release
+artifact selection, and rollback procedures.
 
 ## Summary
 
@@ -33,6 +35,14 @@ Follow the [Keep a Changelog](https://keepachangelog.com/) format. Group entries
 
 All quality gates must pass before a release. Stop if gates fail unless `--force` is explicitly used.
 
+### Project-Specific Release Ceremony
+
+`/scaffold:release` is intentionally project-specific. Determine the target
+project's release artifacts from its docs, manifests, CI workflows, and release
+scripts before publishing anything. Some projects only create a tag; others may
+also create hosted releases, publish to registries, deploy services, or update
+secondary channels like Homebrew.
+
 ## Deep Guidance
 
 ### Semantic Versioning — Extended
@@ -135,9 +145,12 @@ If any single commit includes a breaking change, the release is a major bump reg
 - Re-run all gates from the beginning
 - Only proceed with `--force` if explicitly instructed (and document why)
 
-### GitHub Release
+### Hosted Releases And Distribution Artifacts
+
+Choose release artifacts based on the target project's documented workflow.
+GitHub release creation is one common example, not the universal default.
 
-**Creating a release:**
+**Example: GitHub-hosted release:**
 
 ```bash
 # Create an annotated tag
@@ -150,6 +163,14 @@ git push origin v1.2.0
 gh release create v1.2.0 --title "v1.2.0" --notes-file CHANGELOG_EXCERPT.md
 ```
 
+**Other common artifacts:**
+- npm publish: `npm publish`
+- PyPI publish: `python -m build && twine upload dist/*`
+- crates.io publish: `cargo publish`
+- deployment or registry update: follow the repo's documented release/deploy command
+
+Only run an artifact step when the repository clearly defines it.
+
 **Pre-release versions:**
 - Use `--prerelease` flag for `v0.x` versions or release candidates
 - `gh release create v0.5.0 --prerelease --title "v0.5.0 (pre-release)"`
@@ -172,13 +193,18 @@ When a release needs to be reverted:
 
 3. **Update version files** back to the previous version
 
-4. **Create a new patch release** with the rollback:
+4. **Undo other release artifacts only if the project documents them**:
+   - Hosted release page deletion
+   - Registry deprecation or unpublish
+   - Deployment rollback
+
+5. **Create a new patch release** with the rollback:
    ```bash
    git tag -a v1.1.1 -m "Rollback: revert v1.2.0"
    git push origin v1.1.1
    ```
 
-5. **Update the changelog** with a note explaining the rollback
+6. **Update the changelog** with a note explaining the rollback
 
 **Commit message convention for rollbacks:** prefix with `[ROLLBACK]` for easy identification in history.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "keywords": [

package/skills/scaffold-pipeline/SKILL.md

@@ -117,7 +117,7 @@ Use this skill ONLY when the user asks about:
 | `/scaffold:new-enhancement` | Add a feature to an existing project |
 | `/scaffold:quick-task` | Create a focused task for a bug fix, refactor, or small improvement |
 | `/scaffold:version-bump` | Bump version and update changelog without tagging or releasing |
-| `/scaffold:release` | Create a versioned release with changelog and GitHub release |
+| `/scaffold:release` | Run the target project's release ceremony with changelog generation and project-specific release artifacts |
 | `/scaffold:prompt-pipeline` | Show the full pipeline reference |
 | `/scaffold:dashboard` | Open visual pipeline dashboard in browser |
 

package/skills/scaffold-runner/SKILL.md

@@ -197,7 +197,7 @@ When the user asks "what tools are available?", "what can I build?", or "show me
 | Command | When to Use |
 |---------|-------------|
 | `scaffold run version-bump` | Mark a milestone with a version number without the full release ceremony |
-| `scaffold run release` | Ship a new version — changelog, Git tag, and GitHub release. Supports `--dry-run`, `current`, and `rollback` |
+| `scaffold run release` | Run the target project's release ceremony — changelog plus whatever release artifacts that project defines. Supports `--dry-run`, `current`, and `rollback` |
 | `scaffold run version` | Show the current scaffold version |
 | `scaffold run update` | Update scaffold to the latest version |
 | `scaffold run dashboard` | Open a visual progress dashboard in your browser |

package/tools/prompt-pipeline.md

@@ -151,7 +151,7 @@ Print the following reference directly. Do not read any files or run any command
 | **Resume (single)** | `/scaffold:single-agent-resume` | Resuming single-agent after a break |
 | **Resume (multi)** | `/scaffold:multi-agent-resume <agent-name>` | Resuming a worktree agent after a break |
 | **Version Bump** | `/scaffold:version-bump` | Bump version + changelog (no tag/release) |
-| **Release** | `/scaffold:release` | Full release with tag + GitHub release |
+| **Release** | `/scaffold:release` | Project-defined release ceremony with changelog + relevant release artifacts |
 | **Visual Dashboard** | `/scaffold:dashboard` | HTML pipeline overview in browser |
 
 ## Process Rules

package/tools/release.md

@@ -1,6 +1,6 @@
 ---
 name: release
-description: Create a versioned release with changelog and GitHub release
+description: Run the target project's release ceremony
 phase: null
 order: null
 dependencies: []
@@ -14,10 +14,12 @@ argument-hint: "<version or --dry-run or rollback>"
 
 ## Purpose
 
-Create a versioned release with changelog and GitHub release. Analyzes
-conventional commits to suggest version bumps, generates changelogs from commit
-history and Beads tasks, runs quality gates, and publishes a GitHub release.
-Supports dry-run mode and rollback.
+Run the target project's release ceremony. Analyze conventional commits to
+suggest version bumps, generate changelogs from commit history and optional
+Beads tasks, run quality gates, and execute the release artifacts that project
+defines. Depending on the project, that may include tags, hosted releases,
+package publishes, deployments, or registry updates. Supports dry-run mode and
+rollback.
 
 ## Inputs
 
@@ -27,7 +29,7 @@ $ARGUMENTS — parsed as:
 |----------|------|
 | _(empty)_ | **Standard** — auto-suggest bump, confirm, execute |
 | `major`, `minor`, or `patch` | **Explicit** — use specified bump, skip suggestion |
-| `current` | **Current** — tag and release the version already in files, no bump |
+| `current` | **Current** — use the version already in files, no additional bump |
 | `--dry-run` | **Dry Run** — all analysis, zero mutations |
 | `rollback` | **Rollback** — jump directly to the Rollback section |
 
@@ -37,8 +39,7 @@ Combine flags freely (e.g., `minor --dry-run`).
 
 - Version files updated to new version
 - `CHANGELOG.md` updated with grouped commit entries
-- Annotated git tag `vX.Y.Z`
-- GitHub release (if `gh` CLI is available)
+- Release artifacts defined by the target project (for example: git tag, hosted release, package publish, deployment)
 - Single commit with message `chore(release): vX.Y.Z`
 
 ## Instructions
@@ -51,7 +52,7 @@ Gather project context before proceeding. Check each item and record findings:
 
 1. Confirm the working tree is clean (`git status --porcelain`). If there are uncommitted changes, **stop** and tell the user: "Working tree has uncommitted changes. Commit or stash them before releasing."
 2. Record the current branch name (`git branch --show-current`).
-3. Check if `gh` CLI is available (`which gh`). If not available, warn: "GitHub CLI (`gh`) not found. Will create tag only — no GitHub release. Install with `brew install gh` for full functionality."
+3. Check whether optional release tooling is available when the project needs it (for example `gh` for GitHub-hosted releases). If a required tool is missing, record that gap and stop before the publish/deploy phase.
 4. Fetch tags: `git fetch --tags`.
 
 #### 0.2 Version File Detection
@@ -68,13 +69,21 @@ Scan the project root for version files. For each found file, record the current
 | `setup.cfg` | `[metadata].version` |
 | `version.txt` | Entire file contents (trimmed) |
 
-If **no** version files are found, note this — a tag-only release will be created.
+If **no** version files are found, note this — the release may rely on tags or other non-version-file artifacts only.
 
 #### 0.3 Project Context
 
 - Check for `.beads/` directory — enables Beads integration in release notes.
 - Check for existing `CHANGELOG.md`.
 - List existing `v*` tags: `git tag -l 'v*' --sort=-v:refname | head -5`.
+- Inspect the project's release workflow docs and automation (`README.md`, release docs, manifest scripts, CI workflows) to determine which release artifacts apply. Record whether the project expects any of:
+  - version tag
+  - hosted release page (GitHub/GitLab/etc.)
+  - package publish (npm, PyPI, crates.io, etc.)
+  - deployment or registry update
+  - a PR-based release lane instead of direct tagging from the current branch
+
+If the release process is not clear from the repository, stop and ask the user before publishing or deploying anything.
 
 #### 0.4 Mode Selection
 
@@ -84,7 +93,7 @@ Parse `$ARGUMENTS` to determine the mode:
 |----------|------|
 | _(empty)_ | **Standard** — auto-suggest bump, confirm, execute |
 | `major`, `minor`, or `patch` | **Explicit** — use specified bump, skip suggestion |
-| `current` | **Current** — tag and release the version already in files, no bump |
+| `current` | **Current** — use the version already in files, no additional bump |
 | `--dry-run` | **Dry Run** — all analysis, zero mutations |
 | `rollback` | **Rollback** — jump directly to the Rollback section |
 
@@ -250,7 +259,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 #### 3.4 Save Release Notes
 
-Store the generated changelog entry (without the file header) for use as the GitHub release body in Phase 5.
+Store the generated changelog entry (without the file header) for use as the hosted release body in Phase 5 when the target project creates one.
 
 ---
 
@@ -281,46 +290,35 @@ If Beads is configured (`.beads/` exists) and a task is active, include the task
 
 ---
 
-### Phase 5: Tag & Publish
+### Phase 5: Release Artifacts
 
 **In dry-run mode:** Show what would happen. Skip to Phase 6.
 
 #### 5.1 Determine Flow
 
-Check the current branch:
+Follow the target project's documented release lane if one exists.
 
-- **`main` or `master`**: Direct flow (tag — push — release).
-- **Any other branch**: PR flow (push — create PR — instructions).
+- If the repo docs or automation require a release PR, release branch, or merge-first flow, use that instead of making up a direct tag flow.
+- If the repo provides no release-lane guidance, use this fallback:
+  - **`main` or `master`**: direct flow
+  - **Any other branch**: PR flow
 
-#### 5.2 Direct Flow (main/master)
+#### 5.2 Direct Flow
 
-1. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
-2. Push commit and tag: `git push origin HEAD --follow-tags`
-3. If push fails (e.g., branch protection), fall back to PR flow (5.3).
-4. If `gh` is available: create GitHub release:
-   ```
-   gh release create vX.Y.Z --title "vX.Y.Z" --notes "<release-notes-from-3.4>"
-   ```
-5. Publish to npm:
-   ```
-   npm publish
-   ```
-   The `prepublishOnly` script runs `build` and `test` automatically. If it fails, report the error but do not roll back the git tag — tell the user to fix and re-run `npm publish` manually.
+1. Create the release commit in Phase 4.
+2. If the project uses version tags, create the expected tag (default: annotated `vX.Y.Z`).
+3. Push the required refs for the project workflow.
+4. Execute the project-defined release artifacts in dependency order. Common examples:
+   - Hosted release page: create it using the repo's documented tool and the saved release notes.
+   - Package publish: run the documented ecosystem publish command only when the repo clearly defines it.
+   - Deployment or registry update: run only when it is part of the project's documented release process.
+5. If push or any artifact step is blocked by branch protection, missing tooling, or missing credentials, stop and tell the user exactly what remains rather than guessing.
 
-#### 5.3 PR Flow (feature branch)
+#### 5.3 PR Flow
 
-1. Push branch: `git push -u origin HEAD`
-2. If `gh` is available: create PR:
-   ```
-   gh pr create --title "chore(release): vX.Y.Z" --body "<release-notes-from-3.4>"
-   ```
-3. Tell the user: "Release PR created. After merging to main, run these commands to create the tag and GitHub release:"
-   ```
-   git checkout main && git pull
-   git tag -a vX.Y.Z -m "Release vX.Y.Z"
-   git push origin vX.Y.Z
-   gh release create vX.Y.Z --title "vX.Y.Z" --notes-file CHANGELOG.md
-   ```
+1. Push the release branch: `git push -u origin HEAD`
+2. If the project uses PR-based releases and the relevant CLI is available, open the release PR with the changelog entry as the body.
+3. Tell the user the exact post-merge release actions derived from the project's docs and automation. Include only the artifacts that apply to this project.
 
 ---
 
@@ -333,8 +331,7 @@ Release vX.Y.Z complete!
 
   Version files updated: <list>
   Changelog: CHANGELOG.md updated
-  Tag: vX.Y.Z created
-  GitHub Release: <URL> (or "PR created: <URL>")
+  Release artifacts completed: <list>
 
   To undo this release: /scaffold:release rollback
 ```
@@ -347,8 +344,7 @@ Dry-run complete — no changes were made.
   Would bump: <current> → <new>
   Would update: <version-files>
   Would create: CHANGELOG.md entry
-  Would tag: vX.Y.Z
-  Would create: GitHub release
+  Would execute: <project-specific release artifacts>
 
 Run /scaffold:release to execute.
 ```
@@ -375,10 +371,7 @@ Tell the user: "To confirm rollback of `<tag>`, type the exact tag name (e.g., `
 
 Perform each step. If any step fails, continue with remaining steps and report all results at the end.
 
-1. **Delete GitHub release** (if `gh` is available):
-   ```
-   gh release delete <tag> --yes
-   ```
+1. **Delete hosted release** if the project created one and the appropriate CLI/API is available.
 
 2. **Delete remote tag:**
    ```
@@ -396,13 +389,15 @@ Perform each step. If any step fails, continue with remaining steps and report a
    git push origin HEAD
    ```
 
+5. **Handle project-specific publish/deploy rollback** only if the repository documents it. If that rollback is manual or ambiguous, stop and tell the user exactly what remains.
+
 #### R.4 Report Results
 
 Show what succeeded and what failed:
 
 ```
 Rollback of <tag>:
-  GitHub release: deleted (or failed: <error>)
+  Hosted release: deleted (or failed: <error> / not applicable)
   Remote tag: deleted
   Local tag: deleted
   Version bump commit: reverted
@@ -417,9 +412,9 @@ If any step failed, include manual cleanup instructions for that step.
 ## Process Rules
 
 1. **Never skip quality gates** without explicit user `--force`.
-2. **Dry-run: zero mutations** — no file writes, no git operations, no GitHub API calls.
+2. **Dry-run: zero mutations** — no file writes, no git operations, no hosted-release API calls, no publishes, and no deploys.
 3. **Beads integration is optional** — silently skip if `.beads/` doesn't exist.
-4. **Tag format is always `vX.Y.Z`** — no other formats.
+4. **Release artifacts are project-specific** — only run tag/publish/deploy steps that the target project documents.
 5. **Every confirmation must be explicit** — don't assume "yes" from silence.
 6. **Rollback requires exact tag name** — not just "yes" or "confirm".
 
@@ -428,11 +423,11 @@ If any step failed, include manual cleanup instructions for that step.
 When this step is complete, tell the user:
 
 ---
-**Release complete** — version bumped, changelog updated, tag created, GitHub release published.
+**Release complete** — version bumped, changelog updated, and the target project's release artifacts were handled.
 
 **Next (if applicable):**
 - If follow-up tasks are needed: Run `/scaffold:quick-task` — Create a focused task for post-release work.
-- If the release needs undoing: Run `/scaffold:release rollback` — Undo the most recent release.
+- If the release needs undoing: Run `/scaffold:release rollback` — Undo the most recent release and any clearly documented release artifacts.
 - For development milestone checkpoints without releasing: Run `/scaffold:version-bump` — Bump version and changelog only.
 
 **Pipeline reference:** `/scaffold:prompt-pipeline`

package/tools/version-bump.md

@@ -15,9 +15,9 @@ argument-hint: "<major|minor|patch or --dry-run>"
 ## Purpose
 
 Bump the project version and update the changelog without tagging, pushing, or
-creating a GitHub release. A lightweight companion to `/scaffold:release` for
-marking development milestones — like completing a set of user stories or
-reaching a pre-release checkpoint.
+running the formal release ceremony. A lightweight companion to
+`/scaffold:release` for marking development milestones — like completing a set
+of user stories or reaching a pre-release checkpoint.
 
 ## Inputs
 
@@ -37,7 +37,7 @@ Combine flags freely (e.g., `minor --dry-run`).
 - `CHANGELOG.md` updated (or created) with grouped commit entries
 - Single commit with message `chore(version): vX.Y.Z`
 
-No tags, no push, no GitHub release.
+No tags, no push, no formal release artifacts.
 
 ## Instructions
 
@@ -247,7 +247,7 @@ Version bump complete!
   Version files updated: <list>
   Changelog: CHANGELOG.md updated
 
-  This was a version bump only — no tags, no push, no GitHub release.
+  This was a version bump only — no tags, no push, no formal release artifacts.
   When ready for a formal release: /scaffold:release current
 ```
 
@@ -268,7 +268,7 @@ Run /scaffold:version-bump to execute.
 ## Process Rules
 
 1. **No quality gates** — this is a lightweight milestone marker.
-2. **No tags, no push, no GitHub release** — use `/scaffold:release` for the full ceremony.
+2. **No tags, no push, no formal release artifacts** — use `/scaffold:release` for the full ceremony.
 3. **Dry-run: zero mutations** — no file writes, no git operations.
 4. **Beads integration is optional** — silently skip if `.beads/` doesn't exist.
 5. **Dirty working tree: warn only** — do not block.
@@ -282,7 +282,7 @@ When this step is complete, tell the user:
 **Version bump complete** — version files updated, changelog written, commit created.
 
 **Next (if applicable):**
-- When ready for a formal release: Run `/scaffold:release current` — Tag, publish, and create a GitHub release for the version already in files.
+- When ready for a formal release: Run `/scaffold:release current` — Use the version already in files and execute the target project's release ceremony.
 - If follow-up tasks are needed: Run `/scaffold:quick-task` — Create a focused task for post-bump work.
 
 **Pipeline reference:** `/scaffold:prompt-pipeline`