release

name	release
description	Run the SPECTRE release workflow, including version bumps, Codex sync, global Codex install verification, GitHub release, manual npm publish handoff, npm verification, and final global Codex refresh.
user-invocable	true

Release

You are running the SPECTRE release workflow. Follow each step precisely.

Input Handling

Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded $ARGUMENTS value.

Arguments

$ARGUMENTS is optional: patch, minor, or major. If not provided, ask the user.

Version Files

All three files must be bumped in sync:

• plugins/spectre/.claude-plugin/plugin.json -> version field (Claude Code plugin manifest)
• .claude-plugin/marketplace.json -> top-level version and plugins[0].version (Claude Code marketplace)
• package.json -> version field (npm package @codename_inc/spectre, used by Codex npx installs)

Skipping package.json strands Codex users on the previous version even though the marketplace is current.

Execution Flow

Step 1: Determine Version Bump

Read all version files to get the current version.

If $ARGUMENTS contains patch, minor, or major, use that. Otherwise, ask the user:

Which version bump?
- patch (bug fixes, small changes)
- minor (new features, non-breaking)
- major (breaking changes)

Calculate the new version number and confirm it with the user before proceeding.

Step 2: Handle Dirty Working Tree

Run git status and git diff (staged and unstaged).

If there are uncommitted changes:

1. Analyze what changed: read the diffs and understand the intent.
2. Stage the relevant files with specific filenames, not git add -A.
3. Write a descriptive commit message that summarizes the actual changes. Do not use release: vX.Y.Z here; that comes later.
4. Create the commit.
5. If there are no changes, skip this step.

Step 3: Sync Codex Generated Tree

Run the Codex author-time sync before any version files are updated:

1. Run npm run sync-codex.

2. Run npm run sync-codex -- --check.

3. Run git diff -- plugins/spectre-codex/ and inspect any generated changes.

4. If plugins/spectre-codex/ changed, stage only the generated tree and commit it separately:

   git add plugins/spectre-codex
   git commit -m "release: sync codex tree"
   

5. If there are no generated changes, skip the sync commit.

Do not bump versions until the sync check passes.

Step 4: Bump Versions

1. Update plugins/spectre/.claude-plugin/plugin.json with the new version.

2. Update .claude-plugin/marketplace.json: both version (top-level) and plugins[0].version.

3. Update package.json version.

4. Commit these version bumps:

   git add plugins/spectre/.claude-plugin/plugin.json .claude-plugin/marketplace.json package.json
   git commit -m "release: vX.Y.Z"
   

Step 5: Refresh Global Codex Install Before Shipping

Before changelog, tag, push, or npm publish, make sure the global Codex install is running the exact generated assets from this checkout.

1. Run the source-local user-scope update:

   node bin/spectre.js update codex --scope user --project-dir "$PWD"
   

2. Verify the installed Codex runtime and hook wiring:

   node bin/spectre.js doctor codex --scope user --project-dir "$PWD" --verify-hooks
   

3. If the update or doctor command fails, stop and fix it before shipping.

4. Do not stage ignored local runtime state such as .codex/, .spectre/, ~/.codex/, or AGENTS.override.md unless the user explicitly asks. This step is a local install guard, not a release artifact commit.

Step 6: Build Changelog

Generate a changelog by analyzing commits since the last tag:

git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline

Organize the commits into a changelog with these categories, skipping empty categories:

• New - new features or capabilities
• Changed - modifications to existing behavior
• Fixed - bug fixes
• Removed - removed features or code

Write the changelog in concise bullet points. Each bullet should describe the user-facing change, not the implementation detail. Present the draft to the user and ask if they want to edit it before proceeding.

Step 7: Tag and Push

1. Create the git tag: vX.Y.Z.
2. Ask the user to confirm before pushing:
   • git push
   • git push --tags

Step 8: Create GitHub Release

After pushing, create a GitHub release with the changelog:

gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog>"

Use a heredoc for the notes body to preserve formatting.

Step 9: Manual npm Publish Handoff

Codex users install via npx @codename_inc/spectre install codex, so the npm package must be published for them to pick up the new version. The marketplace alone is not enough.

Do not run npm login or npm publish for the user. npm auth, OTP, and publish confirmation are user-owned interactive steps. This is the final manual publish step.

Ask the user to run these commands themselves:

npm login
npm publish --access public

If they are already logged in, they can skip npm login. If npm requires an OTP, they should rerun publish with:

npm publish --access public --otp=<code>

Wait for the user to confirm the package is published before proceeding.

Step 10: Verify npm and Refresh Global Codex Install

After the user confirms npm publish completed:

1. Verify the new version is live:

   npm view @codename_inc/spectre versions --json
   

2. Refresh the global Codex install one final time from this checkout:

   node bin/spectre.js update codex --scope user --project-dir "$PWD"
   

3. Verify the installed Codex runtime and hook wiring:

   node bin/spectre.js doctor codex --scope user --project-dir "$PWD" --verify-hooks
   

4. Do not stage ignored local runtime state such as .codex/, .spectre/, ~/.codex/, or AGENTS.override.md unless the user explicitly asks.

Step 11: Done

Print a summary:

Release complete: vX.Y.Z
- Commit: <short sha>
- Tag: vX.Y.Z
- GitHub release: <url>
- npm: @codename_inc/spectre@X.Y.Z