Release Theme Skill

Execute a theme release following the established workflow.

Key points:

•Themes are published to markashton480/sum-themes distribution repo
•Each theme is versioned independently using namespaced tags: <theme_slug>/v<VERSION>
•VERSION file is the source of truth for each theme

Input

Required: Theme name (e.g., theme_a) Optional: Version (e.g., 1.2.0) - if omitted, uses VERSION file

Parse from $ARGUMENTS:

•theme_a → theme_name=theme_a, version from VERSION file
•theme_a v1.2.0 → theme_name=theme_a, version=1.2.0
•theme_a 1.2.0 → theme_name=theme_a, version=1.2.0

If theme name is missing, ASK the user before proceeding.

Pre-Flight Checks

1. Run Lint and Tests

bash

make lint && make test

If either fails: STOP and report failures before proceeding.

2. Verify Clean Working Tree

bash

git status
# Should show no uncommitted changes (except untracked files)

If dirty: STOP and ask user to commit or stash changes.

3. Verify Theme Exists

bash

ls -la themes/$THEME_NAME/
cat themes/$THEME_NAME/VERSION

If theme doesn't exist: STOP and report available themes.

4. Validate Theme Versions

bash

python scripts/validate_theme_versions.py

If validation fails: STOP and report version mismatches.

Phase 1: Determine Version

If version provided in arguments:

Update VERSION file to match:

bash

echo "$VERSION" > themes/$THEME_NAME/VERSION

If theme has theme.json, update its version field:

bash

# Check if theme.json exists
if [ -f "themes/$THEME_NAME/theme.json" ]; then
  jq ".version = \"$VERSION\"" themes/$THEME_NAME/theme.json > /tmp/theme.json
  mv /tmp/theme.json themes/$THEME_NAME/theme.json
fi

If no version provided:

Read from VERSION file:

bash

VERSION=$(cat themes/$THEME_NAME/VERSION)

If VERSION is 0.0.0, this is a placeholder theme - ASK user for the release version.

Phase 2: Version Bump (if needed)

If version was updated, commit the change:

bash

git add themes/$THEME_NAME/VERSION themes/$THEME_NAME/theme.json 2>/dev/null
git commit -m "chore($THEME_NAME): bump version to $VERSION"
git push origin HEAD

Phase 3: Dry Run

Test the sync without making changes:

bash

python scripts/publish_themes.py --dry-run

Expected output:

code

============================================================
SUM Platform -> sum-themes sync
============================================================
Dry run enabled: no commit or push will occur.

Checking source repo status...
Updating sum-themes repo...
Syncing themes...
  theme_a/ -> themes/theme_a/
  theme_b/ -> themes/theme_b/

Committing changes...
Dry run: skipping commit and push.
Pending changes:
 M themes/theme_a/VERSION
...

Sync complete.

Review the pending changes. If unexpected files appear, STOP and investigate.

Phase 4: Sync and Commit

Run the sync script to push changes:

bash

python scripts/publish_themes.py

This will:

•Clone/update sum-themes to /tmp/sum-themes-sync
•Copy all themes from sum-platform/themes/ to sum-themes/themes/
•Commit with message including source SHA and theme list
•Push to origin/main

Phase 5: Create Namespaced Tag

After publishing, create a tag in the sum-themes repo:

bash

cd /tmp/sum-themes-sync

# Create annotated tag with namespace
git tag -a "$THEME_NAME/v$VERSION" -m "$THEME_NAME: Release v$VERSION

- [Add release notes here or omit for simple releases]"

# Push the tag
git push origin "$THEME_NAME/v$VERSION"

Tag naming convention:

•Format: <theme_slug>/v<VERSION>
•Examples: theme_a/v1.0.0, theme_b/v0.5.1

Phase 6: Verification

bash

cd /tmp/sum-themes-sync

# Verify tag exists
git ls-remote --tags origin | grep "$THEME_NAME/v$VERSION"

Expected output:

code

abc123...  refs/tags/theme_a/v1.2.0

Phase 7: Report Success

code

Theme release complete!

Theme: $THEME_NAME
Version: $VERSION
Tag: $THEME_NAME/v$VERSION

Tag URL: https://github.com/markashton480/sum-themes/releases/tag/$THEME_NAME/v$VERSION

Clients can update via:
git subtree pull --prefix=themes/$THEME_NAME \
    git@github.com:markashton480/sum-themes.git \
    $THEME_NAME/v$VERSION --squash

Error Handling

Theme doesn't exist

code

Theme not found: $THEME_NAME

Available themes:
- theme_a (v0.5.0)
- theme_b (v0.0.0 - placeholder)

Please specify a valid theme name.

Validation fails

code

Theme version validation failed:
- theme_a: VERSION '1.0.0' does not match theme.json version '0.9.0'

Fix VERSION/theme.json mismatch before releasing.

Sync fails

code

Sync to sum-themes failed

Error: [details]

Check:
1. SSH access to sum-themes repo
2. Clean working tree
3. No conflicts

Please resolve and try again.

Tag exists

code

Tag $THEME_NAME/v$VERSION already exists

Options:
1. Use next patch version (e.g., v$VERSION_PATCH)
2. Investigate why tag exists

Reply with choice.

Rollback Procedure

Option A: Publish a fix (recommended)

•Fix the issue in sum-platform/themes/<theme>/
•Bump the patch version (e.g., 1.2.0 -> 1.2.1)
•Run this skill again

Option B: Delete the bad tag (if no clients consumed it)

bash

cd /tmp/sum-themes-sync

# Delete remote tag
git push origin --delete $THEME_NAME/v$VERSION

# Delete local tag
git tag -d $THEME_NAME/v$VERSION

Note: Tags are immutable. Never re-tag the same version - always increment.

Safety Rules

•Never re-tag existing versions - Create new patch version instead
•Always run dry-run first - Review changes before publishing
•Validate before publish - validate_theme_versions.py must pass
•Clean working tree required - Commit or stash changes first