beads/cmd/bd/templates/workflows/version-bump.yaml

schema_version: 1

name: version-bump
description: |
  Bumps version across all beads components and coordinates the release.
  Creates tasks for file updates, verification, git operations, CI monitoring,
  and local installation.

defaults:
  priority: 1
  type: task

variables:
  - name: version
    description: "New semantic version (e.g., 0.31.0)"
    required: true
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"

  - name: previous_version
    description: "Current version (auto-detected from version.go)"
    required: false
    default_command: "grep 'Version = ' cmd/bd/version.go | sed 's/.*\"\\(.*\\)\".*/\\1/'"

preflight:
  - command: "git diff-index --quiet HEAD --"
    message: "Working directory must be clean (no uncommitted changes)"
  - command: "which jq >/dev/null 2>&1"
    message: "jq must be installed for JSON file updates"
  - command: "which gh >/dev/null 2>&1"
    message: "GitHub CLI (gh) must be installed"

epic:
  title: "Release v{{version}}"
  description: |
    ## Version Bump Workflow

    Coordinating release from {{previous_version}} to {{version}}.

    ### Components Updated
    - Go CLI (cmd/bd/version.go)
    - Claude Plugin (.claude-plugin/*.json)
    - MCP Server (integrations/beads-mcp/)
    - npm Package (npm-package/package.json)
    - Git hooks (cmd/bd/templates/hooks/)

    ### Release Channels
    - GitHub Releases (GoReleaser)
    - PyPI (beads-mcp)
    - npm (@beads/cli)
    - Homebrew (homebrew-beads tap)
  priority: 1
  labels:
    - release
    - v{{version}}

tasks:
  - id: update-version-go
    title: "Update cmd/bd/version.go to {{version}}"
    description: |
      Update the Version constant in cmd/bd/version.go:
      ```go
      Version = "{{version}}"
      ```
    verification:
      command: "grep -q 'Version = \"{{version}}\"' cmd/bd/version.go"

  - id: update-changelog
    title: "Update CHANGELOG.md for {{version}}"
    description: |
      1. Change `## [Unreleased]` to `## [{{version}}] - {{today}}`
      2. Add new empty `## [Unreleased]` section at top
      3. Ensure all changes since {{previous_version}} are documented

  - id: update-info-go
    title: "Add {{version}} to info.go release notes"
    description: |
      Update cmd/bd/info.go versionChanges map with release notes for {{version}}.
      Include any workflow-impacting changes for --whats-new output.
    depends_on:
      - update-changelog

  - id: update-plugin-json
    title: "Update .claude-plugin/plugin.json to {{version}}"
    description: |
      Update version field in .claude-plugin/plugin.json:
      ```json
      "version": "{{version}}"
      ```
    verification:
      command: "jq -e '.version == \"{{version}}\"' .claude-plugin/plugin.json"

  - id: update-marketplace-json
    title: "Update .claude-plugin/marketplace.json to {{version}}"
    description: |
      Update version field in .claude-plugin/marketplace.json:
      ```json
      "version": "{{version}}"
      ```
    verification:
      command: "jq -e '.plugins[0].version == \"{{version}}\"' .claude-plugin/marketplace.json"

  - id: update-pyproject
    title: "Update integrations/beads-mcp/pyproject.toml to {{version}}"
    description: |
      Update version in pyproject.toml:
      ```toml
      version = "{{version}}"
      ```
    verification:
      command: "grep -q 'version = \"{{version}}\"' integrations/beads-mcp/pyproject.toml"

  - id: update-python-init
    title: "Update beads_mcp/__init__.py to {{version}}"
    description: |
      Update __version__ in integrations/beads-mcp/src/beads_mcp/__init__.py:
      ```python
      __version__ = "{{version}}"
      ```
    verification:
      command: "grep -q '__version__ = \"{{version}}\"' integrations/beads-mcp/src/beads_mcp/__init__.py"

  - id: update-npm-package
    title: "Update npm-package/package.json to {{version}}"
    description: |
      Update version field in npm-package/package.json:
      ```json
      "version": "{{version}}"
      ```
    verification:
      command: "jq -e '.version == \"{{version}}\"' npm-package/package.json"

  - id: update-hook-templates
    title: "Update hook templates to {{version}}"
    description: |
      Update bd-hooks-version comment in all 4 hook templates:
      - cmd/bd/templates/hooks/pre-commit
      - cmd/bd/templates/hooks/post-merge
      - cmd/bd/templates/hooks/pre-push
      - cmd/bd/templates/hooks/post-checkout

      Each should have:
      ```bash
      # bd-hooks-version: {{version}}
      ```
    verification:
      command: "grep -l 'bd-hooks-version: {{version}}' cmd/bd/templates/hooks/* | wc -l | grep -q '4'"

  - id: verify-all-versions
    title: "Run check-versions.sh - all must pass"
    description: |
      Run the version consistency check:
      ```bash
      ./scripts/check-versions.sh
      ```

      All versions must match {{version}}.
    depends_on:
      - update-version-go
      - update-plugin-json
      - update-marketplace-json
      - update-pyproject
      - update-python-init
      - update-npm-package
      - update-hook-templates
    verification:
      command: "./scripts/check-versions.sh"

  - id: git-commit-tag
    title: "Commit changes and create v{{version}} tag"
    description: |
      ```bash
      git add -A
      git commit -m "chore: Bump version to {{version}}"
      git tag -a v{{version}} -m "Release v{{version}}"
      ```
    depends_on:
      - verify-all-versions
      - update-changelog
      - update-info-go
    verification:
      command: "git describe --tags --exact-match HEAD 2>/dev/null | grep -q 'v{{version}}'"

  - id: git-push
    title: "Push commit and tag to origin"
    description: |
      ```bash
      git push origin main
      git push origin v{{version}}
      ```

      This triggers GitHub Actions:
      - GoReleaser build
      - PyPI publish
      - npm publish
    depends_on:
      - git-commit-tag
    verification:
      command: "git ls-remote origin refs/tags/v{{version}} | grep -q 'v{{version}}'"

  - id: monitor-goreleaser
    title: "Monitor GoReleaser CI job"
    description: |
      Watch the GoReleaser action:
      https://github.com/steveyegge/beads/actions/workflows/release.yml

      Should complete in ~10 minutes and create:
      - GitHub Release with binaries for all platforms
      - Checksums and signatures

      Check status:
      ```bash
      gh run list --workflow=release.yml -L 1
      gh run watch  # to monitor live
      ```

      Verify release exists:
      ```bash
      gh release view v{{version}}
      ```
    priority: 2
    depends_on:
      - git-push
    verification:
      command: "gh release view v{{version}} --json tagName -q .tagName | grep -q 'v{{version}}'"

  - id: monitor-pypi
    title: "Monitor PyPI publish"
    description: |
      Watch the PyPI publish action:
      https://github.com/steveyegge/beads/actions/workflows/pypi-publish.yml

      Verify at: https://pypi.org/project/beads-mcp/{{version}}/

      Check:
      ```bash
      pip index versions beads-mcp 2>/dev/null | grep -q '{{version}}'
      ```
    priority: 2
    depends_on:
      - git-push
    verification:
      command: "pip index versions beads-mcp 2>/dev/null | grep -q '{{version}}' || curl -s https://pypi.org/pypi/beads-mcp/json | jq -e '.releases[\"{{version}}\"]'"

  - id: monitor-npm
    title: "Monitor npm publish"
    description: |
      Watch the npm publish action:
      https://github.com/steveyegge/beads/actions/workflows/npm-publish.yml

      Verify at: https://www.npmjs.com/package/@anthropics/claude-code-beads-plugin/v/{{version}}

      Check:
      ```bash
      npm view @anthropics/claude-code-beads-plugin@{{version}} version
      ```
    priority: 2
    depends_on:
      - git-push
    verification:
      command: "npm view @anthropics/claude-code-beads-plugin@{{version}} version 2>/dev/null | grep -q '{{version}}'"

  - id: update-homebrew
    title: "Update Homebrew formula"
    description: |
      After GoReleaser completes, the Homebrew tap should be auto-updated.

      If manual update needed:
      ```bash
      ./scripts/update-homebrew.sh v{{version}}
      ```

      Or manually update steveyegge/homebrew-beads with new SHA256.

      Verify:
      ```bash
      brew update
      brew info beads
      ```
    priority: 2
    depends_on:
      - monitor-goreleaser

  - id: local-go-install
    title: "Install {{version}} Go binary locally"
    description: |
      Rebuild and install the Go binary:
      ```bash
      go install ./cmd/bd
      # OR
      make install
      ```

      Verify:
      ```bash
      bd --version
      ```
    depends_on:
      - monitor-goreleaser
    verification:
      command: "bd --version 2>&1 | grep -q '{{version}}'"

  - id: restart-daemon
    title: "Restart beads daemon"
    description: |
      Kill any running daemons so they pick up the new version:
      ```bash
      bd daemons killall
      ```

      Start fresh daemon:
      ```bash
      bd list  # triggers daemon start
      ```

      Verify daemon version:
      ```bash
      bd version --daemon
      ```
    depends_on:
      - local-go-install
    verification:
      command: "bd version --daemon 2>&1 | grep -q '{{version}}'"

  - id: local-mcp-install
    title: "Install {{version}} MCP server locally"
    description: |
      Upgrade the MCP server (after PyPI publish):
      ```bash
      pip install --upgrade beads-mcp
      # OR if using uv:
      uv tool upgrade beads-mcp
      ```

      Verify:
      ```bash
      pip show beads-mcp | grep Version
      ```
    depends_on:
      - monitor-pypi
    verification:
      command: "pip show beads-mcp 2>/dev/null | grep -q 'Version: {{version}}'"

  - id: update-hooks
    title: "Update git hooks"
    description: |
      Install the updated hooks:
      ```bash
      bd hooks install
      ```

      Verify hook version:
      ```bash
      grep 'bd-hooks-version' .git/hooks/pre-commit
      ```
    depends_on:
      - local-go-install
    verification:
      command: "grep -q 'bd-hooks-version: {{version}}' .git/hooks/pre-commit 2>/dev/null || echo 'Hooks may not be installed - verify manually'"

  - id: final-verification
    title: "Final release verification"
    description: |
      Verify all release artifacts are accessible:

      - [ ] `bd --version` shows {{version}}
      - [ ] `bd version --daemon` shows {{version}}
      - [ ] GitHub release exists: https://github.com/steveyegge/beads/releases/tag/v{{version}}
      - [ ] `brew upgrade beads && bd --version` shows {{version}} (if using Homebrew)
      - [ ] `pip show beads-mcp` shows {{version}}
      - [ ] npm package available at {{version}}
      - [ ] `bd info --whats-new` shows {{version}} notes

      Run final checks:
      ```bash
      bd --version
      bd version --daemon
      pip show beads-mcp | grep Version
      bd info --whats-new
      ```
    depends_on:
      - restart-daemon
      - local-mcp-install
      - update-hooks
      - monitor-npm
      - update-homebrew