Release playbook

July 29, 2026 · View on GitHub

This repo ships public npm packages from tools/. Front door for users: @cobusgreyling/loop (cli-front-door.md). Sibling packages stay published and supported.

PackageDirectoryRelease tag
@cobusgreyling/looptools/looploop-v*
@cobusgreyling/readiness-coretools/readiness-corereadiness-core-v*
@cobusgreyling/loop-audittools/loop-auditloop-audit-v*
@cobusgreyling/loop-inittools/loop-initloop-init-v*
@cobusgreyling/loop-costtools/loop-costloop-cost-v*
@cobusgreyling/loop-synctools/loop-syncloop-sync-v*
@cobusgreyling/loop-contexttools/loop-contextloop-context-v*
@cobusgreyling/loop-mcp-servertools/mcp-serverloop-mcp-server-v*
@cobusgreyling/loop-worktreetools/loop-worktreeloop-worktree-v*
@cobusgreyling/loop-sandboxtools/loop-sandboxloop-sandbox-v*
@cobusgreyling/loop-swarmtools/loop-swarmloop-swarm-v*
@cobusgreyling/loop-gatetools/loop-gateloop-gate-v*
@cobusgreyling/goal-audittools/goal-auditgoal-audit-v*
@cobusgreyling/goal-inittools/goal-initgoal-init-v*

Link npm to GitHub, then for each package on npmjs.com → package Settings → Trusted Publisher → GitHub Actions:

PackageRepositoryWorkflow filename
@cobusgreyling/loopcobusgreyling/loop-engineeringrelease-loop.yml
@cobusgreyling/readiness-corecobusgreyling/loop-engineeringrelease-readiness-core.yml
@cobusgreyling/loop-auditcobusgreyling/loop-engineeringrelease-loop-audit.yml
@cobusgreyling/loop-initcobusgreyling/loop-engineeringrelease-loop-init.yml
@cobusgreyling/loop-costcobusgreyling/loop-engineeringrelease-loop-cost.yml
@cobusgreyling/loop-synccobusgreyling/loop-engineeringrelease-loop-sync.yml
@cobusgreyling/loop-contextcobusgreyling/loop-engineeringrelease-loop-context.yml
@cobusgreyling/loop-mcp-servercobusgreyling/loop-engineeringrelease-loop-mcp-server.yml
@cobusgreyling/loop-worktreecobusgreyling/loop-engineeringrelease-loop-worktree.yml
@cobusgreyling/loop-sandboxcobusgreyling/loop-engineeringrelease-loop-sandbox.yml
@cobusgreyling/loop-swarmcobusgreyling/loop-engineeringrelease-loop-swarm.yml
@cobusgreyling/loop-gatecobusgreyling/loop-engineeringrelease-loop-gate.yml
@cobusgreyling/goal-auditcobusgreyling/loop-engineeringrelease-goal-audit.yml
@cobusgreyling/goal-initcobusgreyling/loop-engineeringrelease-goal-init.yml

Names must match exactly (case-sensitive). No NPM_TOKEN secret is required when trusted publishing is configured.

Auth: release workflows use repo secret NPM_TOKEN (Automation token). Refresh it at npmjs.com → Access Tokens if publishes fail with E401/E404.

Retry without re-tagging: Actions → Release workflow → Run workflow → enter the tag (e.g. loop-audit-v1.6.0).

Trusted publishing (optional): configure per package on npm; OIDC alone is not sufficient unless NPM_TOKEN is removed and trusted publishers are verified.

Version bump

Edit version in the package package.json, update that package's CHANGELOG.md if present, and commit to main via PR.

Publish

Tag pushes trigger the release workflows:

# readiness-core (MUST be published before loop-audit and goal-audit)
git tag readiness-core-v1.0.0
git push origin readiness-core-v1.0.0

# loop (unified front door — pass-through + doctor/status)
git tag loop-v0.1.0
git push origin loop-v0.1.0

# loop-audit (runs tests before publish)
git tag loop-audit-v1.6.0
git push origin loop-audit-v1.6.0

# loop-init (bundles starters/templates, runs smoke tests)
git tag loop-init-v1.3.3
git push origin loop-init-v1.3.3

# loop-cost (bundles patterns/registry.yaml)
git tag loop-cost-v1.0.3
git push origin loop-cost-v1.0.3

# loop-sync (drift detection between STATE.md and LOOP.md)
git tag loop-sync-v1.0.0
git push origin loop-sync-v1.0.0

# loop-context (stateful memory manager + circuit breaker)
git tag loop-context-v1.0.0
git push origin loop-context-v1.0.0

# loop-mcp-server (MCP runtime lookup for patterns, skills, state)
git tag loop-mcp-server-v1.0.0
git push origin loop-mcp-server-v1.0.0

# loop-worktree (isolated git worktrees per fix attempt)
git tag loop-worktree-v1.0.0
git push origin loop-worktree-v1.0.0

# loop-gate (path denylist + auto-merge allowlist)
git tag loop-gate-v1.0.0
git push origin loop-gate-v1.0.0

# goal-audit (Goal Engineering readiness scorer — companion repo)
git tag goal-audit-v1.0.2
git push origin goal-audit-v1.0.2

# goal-init (scaffold goal engineering setups)
git tag goal-init-v1.0.0
git push origin goal-init-v1.0.0

Workflows: .github/workflows/release-loop.yml, .github/workflows/release-readiness-core.yml, .github/workflows/release-loop-audit.yml, .github/workflows/release-loop-init.yml, .github/workflows/release-loop-cost.yml, .github/workflows/release-loop-sync.yml, .github/workflows/release-loop-context.yml, .github/workflows/release-loop-mcp-server.yml, .github/workflows/release-loop-worktree.yml, .github/workflows/release-loop-gate.yml, .github/workflows/release-goal-audit.yml, .github/workflows/release-goal-init.yml.

Verify after publish

npx @cobusgreyling/loop-audit --help
npx @cobusgreyling/loop-init --help
npx @cobusgreyling/loop-cost --help
npx @cobusgreyling/loop-sync --help
npx @cobusgreyling/loop-context --help
npx @cobusgreyling/loop-mcp-server --help
npx @cobusgreyling/loop-worktree --help
npx @cobusgreyling/goal-audit --help

mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run

Changelog & release notes (no root CHANGELOG.md)

This repo does not maintain a root CHANGELOG.md. Use:

SurfacePurpose
RELEASE_NOTES_DRAFT.mdWorking draft for the next community update (changelog-drafter + human edit)
GitHub Discussions → AnnouncementsPublished release notes (e.g. #89, #219)
tools/*/CHANGELOG.mdPer-package history when a tool version bumps

After publish: trim RELEASE_NOTES_DRAFT.md to a short “since last discussion” stub for the next drafter run.

Before npm is live (local / monorepo)

cd tools/loop-audit && npm ci && npm test && node dist/cli.js ../.. --suggest
cd tools/loop-init && npm ci && npm test && node dist/cli.js /tmp/target --pattern daily-triage --dry-run