beads/.beads/formulas/beads-release.formula.json

{
  "formula": "beads-release",
  "type": "workflow",
  "description": "Beads release workflow - from version bump to verified release.\n\nThis formula orchestrates a complete release cycle:\n1. Preflight checks (clean git, up to date)\n2. Documentation updates (CHANGELOG, info.go)\n3. Version bump (all components)\n4. Git operations (commit, tag, push)\n5. CI verification (GitHub Actions)\n6. Artifact verification (GitHub, npm, PyPI)\n7. Local installation update\n8. Daemon restart\n\n## Usage\n\n```bash\nbd wisp create beads-release --var version=0.37.0\n```\n\nOr assign to a polecat:\n```bash\ngt sling beads/polecats/p1 --formula beads-release --var version=0.37.0\n```",
  "version": 1,
  "vars": {
    "version": {
      "description": "The semantic version to release (e.g., 0.37.0)",
      "required": true
    }
  },
  "steps": [
    {
      "id": "preflight-git",
      "title": "Preflight: Check git status",
      "description": "Ensure working tree is clean before starting release.\n\n```bash\ngit status\n```\n\nIf there are uncommitted changes, either:\n- Commit them first\n- Stash them: `git stash`\n- Abort and resolve"
    },
    {
      "id": "preflight-pull",
      "title": "Preflight: Pull latest",
      "description": "Ensure we're up to date with origin.\n\n```bash\ngit pull --rebase\n```\n\nResolve any conflicts before proceeding.",
      "needs": ["preflight-git"]
    },
    {
      "id": "review-changes",
      "title": "Review changes since last release",
      "description": "Understand what's being released.\n\n```bash\ngit log $(git describe --tags --abbrev=0)..HEAD --oneline\n```\n\nCategorize changes:\n- Features (feat:)\n- Fixes (fix:)\n- Breaking changes\n- Documentation",
      "needs": ["preflight-pull"]
    },
    {
      "id": "update-changelog",
      "title": "Update CHANGELOG.md",
      "description": "Write the [Unreleased] section with all changes for {{version}}.\n\nFormat: Keep a Changelog (https://keepachangelog.com)\n\nSections:\n- ### Added\n- ### Changed\n- ### Fixed\n- ### Documentation\n\nThe bump script will stamp the date automatically.",
      "needs": ["review-changes"]
    },
    {
      "id": "update-info-go",
      "title": "Update info.go versionChanges",
      "description": "Add entry to versionChanges in cmd/bd/info.go.\n\nThis powers `bd info --whats-new` for agents.\n\n```go\n\"{{version}}\": {\n    \"summary\": \"Brief description\",\n    \"changes\": []string{\n        \"Key change 1\",\n        \"Key change 2\",\n    },\n},\n```\n\nFocus on workflow-impacting changes agents need to know.",
      "needs": ["update-changelog"]
    },
    {
      "id": "run-bump-script",
      "title": "Run bump-version.sh",
      "description": "Update all component versions atomically.\n\n```bash\n./scripts/bump-version.sh {{version}}\n```\n\nThis updates:\n- cmd/bd/version.go\n- .claude-plugin/*.json\n- integrations/beads-mcp/pyproject.toml\n- integrations/beads-mcp/src/beads_mcp/__init__.py\n- npm-package/package.json\n- Hook templates\n- README.md\n- CHANGELOG.md (adds date)",
      "needs": ["update-info-go"]
    },
    {
      "id": "verify-versions",
      "title": "Verify version consistency",
      "description": "Confirm all versions match {{version}}.\n\n```bash\ngrep 'Version = ' cmd/bd/version.go\njq -r '.version' .claude-plugin/plugin.json\njq -r '.version' npm-package/package.json\ngrep 'version = ' integrations/beads-mcp/pyproject.toml\n```\n\nAll should show {{version}}.",
      "needs": ["run-bump-script"]
    },
    {
      "id": "commit-release",
      "title": "Commit release",
      "description": "Stage and commit all version changes.\n\n```bash\ngit add -A\ngit commit -m \"chore: Bump version to {{version}}\"\n```\n\nReview the commit to ensure all expected files are included.",
      "needs": ["verify-versions"]
    },
    {
      "id": "create-tag",
      "title": "Create release tag",
      "description": "Create annotated git tag.\n\n```bash\ngit tag -a v{{version}} -m \"Release v{{version}}\"\n```\n\nVerify: `git tag -l | tail -5`",
      "needs": ["commit-release"]
    },
    {
      "id": "push-main",
      "title": "Push to main",
      "description": "Push the release commit to origin.\n\n```bash\ngit push origin main\n```\n\nIf rejected, someone else pushed. Pull, rebase, try again.",
      "needs": ["create-tag"]
    },
    {
      "id": "push-tag",
      "title": "Push release tag",
      "description": "Push the version tag to trigger CI release.\n\n```bash\ngit push origin v{{version}}\n```\n\nThis triggers GitHub Actions to build artifacts and publish.",
      "needs": ["push-main"]
    },
    {
      "id": "wait-ci",
      "title": "Wait for CI",
      "description": "Monitor GitHub Actions for release completion.\n\nhttps://github.com/steveyegge/beads/actions\n\nExpected time: 5-10 minutes\n\nWatch for:\n- Build artifacts (all platforms)\n- Test suite pass\n- npm publish\n- PyPI publish",
      "needs": ["push-tag"]
    },
    {
      "id": "verify-github-release",
      "title": "Verify GitHub release",
      "description": "Check the GitHub releases page.\n\nhttps://github.com/steveyegge/beads/releases/tag/v{{version}}\n\nVerify:\n- Release created\n- Binaries attached (linux, darwin, windows)\n- Checksums present",
      "needs": ["wait-ci"]
    },
    {
      "id": "verify-npm",
      "title": "Verify npm package",
      "description": "Confirm npm package published.\n\n```bash\nnpm show @beads/bd version\n```\n\nShould show {{version}}.\n\nAlso check: https://www.npmjs.com/package/@beads/bd",
      "needs": ["verify-github-release"]
    },
    {
      "id": "verify-pypi",
      "title": "Verify PyPI package",
      "description": "Confirm PyPI package published.\n\n```bash\npip index versions beads-mcp 2>/dev/null | head -3\n```\n\nOr check: https://pypi.org/project/beads-mcp/\n\nShould show {{version}}.",
      "needs": ["verify-github-release"]
    },
    {
      "id": "local-install",
      "title": "Update local installation",
      "description": "Update local bd to the new version.\n\nOption 1 - Homebrew:\n```bash\nbrew upgrade bd\n```\n\nOption 2 - Install script:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash\n```\n\nVerify:\n```bash\nbd --version\n```\n\nShould show {{version}}.",
      "needs": ["verify-npm", "verify-pypi"]
    },
    {
      "id": "restart-daemons",
      "title": "Restart daemons",
      "description": "Restart bd daemons to pick up new version.\n\n```bash\nbd daemons killall\n```\n\nDaemons will auto-restart with new version on next bd command.\n\nVerify:\n```bash\nbd daemons list\n```",
      "needs": ["local-install"]
    },
    {
      "id": "release-complete",
      "title": "Release complete",
      "description": "Release v{{version}} is complete!\n\nSummary:\n- All version files updated\n- Git tag pushed\n- CI artifacts built\n- npm and PyPI packages published\n- Local installation updated\n- Daemons restarted\n\nOptional next steps:\n- Announce on social media\n- Update documentation site\n- Close related milestone",
      "needs": ["restart-daemons"]
    }
  ]
}