How do I install the TASK-04: Version Sync Fix & Release Process Improvement skill?

Run npx skillmds@latest add tools-only/task-04-version-sync-fix-and-release-process-improvement in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Which AI agents work with TASK-04: Version Sync Fix & Release Process Improvement?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is TASK-04: Version Sync Fix & Release Process Improvement free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published TASK-04: Version Sync Fix & Release Process Improvement?

tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.

TASK-04: Version Sync Fix & Release Process Improvement by tools-only

Name: TASK-04: Version Sync Fix & Release Process Improvement
Author: tools-only

TASK-04: Version Sync Fix & Release Process Improvement

Status: 🚧 In Progress Version: 1.5.0 → 1.6.0 Priority: High (prevents documentation drift) Started: 2025-10-13

Problem Statement

Current Issue

Version references are scattered across multiple files, leading to inconsistencies:

marketplace.json: ✅ v1.5.0 (correct)
README.md: ❌ v1.4.0 (outdated in 4 places)
.agent/DEVELOPMENT-README.md: ✅ v1.5.0 (correct)

Root Cause: No single source of truth for version, no automated sync, no checklist in release workflow.

Impact

Users see wrong version number in README
Confusion about actual plugin version
GitHub releases missing for v1.3.0, v1.4.0, v1.5.0
Trust erosion (docs don't match reality)

Goals

Primary

Fix current version inconsistency (README.md → v1.5.0)
Create missing GitHub releases with proper notes
Prevent future version drift with improved process

Secondary

Add automated version sync checklist
Document version management SOP
Test the new process end-to-end

Technical Analysis

Files with Version References

# Current audit results:
./README.md:**Status**: ✅ Published v1.4.0
./README.md:[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)]
./README.md:- v1.4.0 published
./README.md:**Version**: 1.4.0

./.claude-plugin/marketplace.json:  "version": "1.5.0"  # ✅ Correct
./.agent/DEVELOPMENT-README.md:**Last Updated**: 2025-10-12 (v1.5.0)  # ✅ Correct

Version Reference Locations

Source of Truth: .claude-plugin/marketplace.json → metadata.version and plugins[0].version
User-Facing: README.md (4 locations)
Internal: .agent/DEVELOPMENT-README.md (1 location)
Git: Tags (v1.5.0 exists)
GitHub: Releases (missing for v1.3.0, v1.4.0, v1.5.0)

Implementation Plan

Step 1: Fix Current Version (README.md)

Update 4 locations:

# Line 5
**Status**: ✅ Published v1.5.0

# Line 8
[![Version](https://img.shields.io/badge/version-1.5.0-blue.svg)]

# Line 434
- v1.5.0 published

# Line 505
**Version**: 1.5.0

Test: Verify badge renders correctly, all references consistent.

Step 2: Create Missing GitHub Releases

v1.3.0 Release Notes (from TASK-01):

# Navigator v1.3.0 - Session Start & PM Integration

## 🚀 New Features

### `/nav:start` Command
- Loads documentation navigator automatically
- Checks for assigned tasks (Linear MCP, GitHub CLI support)
- Sets Navigator workflow context
- Shows token optimization status

### Enhanced `/nav:init`
- Auto-detects Linear MCP and GitHub CLI
- Generates setup guidance for PM tools
- Creates integration SOPs automatically
- Improved error handling

## 🔧 Improvements
- Stronger Navigator workflow enforcement in CLAUDE.md
- Better onboarding UX for new users
- PM tool configuration simplified

## 📦 What's Included
- 5 slash commands total
- Linear and GitHub integrations
- Auto-generated SOPs

**Full Changelog**: v1.0.1...v1.3.0

v1.4.0 Release Notes (from TASK-02):

# Navigator v1.4.0 - Context Markers & README Overhaul

## 🚀 New Features

### `/nav:marker` Command
- Create conversation save points anytime
- Compress 130k sessions → 3k snapshots (97.7% reduction)
- Safety nets before risky changes
- Perfect handoffs between sessions

### Updated `/nav:init`
- Creates `.context-markers/` directory
- Adds `.context-markers/` to .gitignore
- Sets up marker infrastructure

## 📖 Documentation
- Comprehensive README rewrite
- Clear feature explanations with examples
- Token optimization strategy documented
- Context markers explained step-by-step

## 🔧 Improvements
- Better value proposition (understand Navigator in 30 seconds)
- Real-world workflow examples
- Metrics and benefits clearly shown

## 📦 What's Included
- 6 slash commands total
- Context marker system
- Updated templates

**Full Changelog**: v1.3.0...v1.4.0

v1.5.0 Release Notes (from TASK-03):

# Navigator v1.5.0 - Interactive Marker Management & Auto-Resume

## 🚀 New Features

### `/nav:markers` Command
- **Interactive marker management**
  - List all markers with timestamps and descriptions
  - Load any marker with visual selection
  - Clean old markers (by age or count)
- **Performance**: <1s for 50+ markers
- **UX**: Arrow navigation, clear visual feedback

### Active Marker Auto-Resume
- **Automatic context restoration**
  - `/nav:compact` creates "active" marker
  - `/nav:start` detects and offers to load it
  - One-command resume (vs 3 manual steps)
- **Smart workflow**: Compact → Start → Continue

### Updated Commands
- `/nav:compact`: Now creates `.active` marker automatically
- `/nav:start`: Auto-detects active marker, prompts to load

## 🔧 Improvements
- Marker file naming: `YYYY-MM-DD_HH-MM-SS_name.md`
- Chronological sorting (newest first)
- Better error handling for corrupted markers
- Graceful degradation if no markers exist

## 📦 What's Included
- 7 slash commands total
- Interactive marker UI
- Auto-resume system
- Performance optimizations

## 💡 Workflow Impact

**Before v1.5.0**:
```bash
/nav:compact                          # Creates marker
# ...new session...
ls .agent/.context-markers/            # Find marker manually
Read .agent/.context-markers/file.md   # Load manually

After v1.5.0:

/nav:compact                          # Creates active marker
# ...new session...
/nav:start                            # Detects & loads automatically
# Continue working immediately!

Full Changelog: v1.4.0...v1.5.0


---

### Step 3: Enhance Release Workflow SOP

**Add to `.agent/sops/development/plugin-release-workflow.md`**:

#### New Section: "Pre-Release Version Sync Checklist"

```markdown
### Step 0: Pre-Release Version Sync (MANDATORY)

**Before making any changes, verify version consistency**:

1. **Determine new version**:
   ```bash
   # Check current version
   cat .claude-plugin/marketplace.json | jq -r '.metadata.version'

   # Determine bump type
   # - Patch (1.5.0 → 1.5.1): Bug fixes only
   # - Minor (1.5.0 → 1.6.0): New features, backward compatible
   # - Major (1.5.0 → 2.0.0): Breaking changes

Update all version references (NEW_VERSION = X.Y.Z):

# Audit current references
grep -r "version.*[0-9]\.[0-9]\.[0-9]" . \
  --include="*.md" \
  --include="*.json" \
  --exclude-dir=.git \
  --exclude-dir=node_modules

# Files to update:
# 1. .claude-plugin/marketplace.json (2 places)
#    - metadata.version
#    - plugins[0].version

# 2. README.md (4 places)
#    - Line ~5: **Status**: ✅ Published vX.Y.Z
#    - Line ~8: [![Version](badge/version-X.Y.Z-blue.svg)]
#    - Line ~434: - vX.Y.Z published
#    - Line ~505: **Version**: X.Y.Z

# 3. .agent/DEVELOPMENT-README.md (1 place)
#    - Bottom: **Last Updated**: YYYY-MM-DD (vX.Y.Z)

Verify consistency:

# All should show NEW_VERSION
jq -r '.metadata.version' .claude-plugin/marketplace.json
jq -r '.plugins[0].version' .claude-plugin/marketplace.json
grep -A1 "Status" README.md | grep "Published"
grep "Version.*badge" README.md
grep "Last Updated" .agent/DEVELOPMENT-README.md

Commit version bump:

git add .claude-plugin/marketplace.json README.md .agent/DEVELOPMENT-README.md
git commit -m "chore: bump version to vX.Y.Z"

⚠️ STOP: If any version mismatch found, fix before proceeding!


---

### Step 4: Create Version Management SOP

**New file**: `.agent/sops/development/version-management.md`

```markdown
# Version Management - Standard Operating Procedure

**Last Updated**: 2025-10-13
**Applies To**: All Navigator plugin releases

---

## Overview

This SOP ensures version numbers stay consistent across all files during releases.

**Problem**: Version references scattered across 7+ locations
**Solution**: Single source of truth + automated checklist
**Result**: Zero version drift

---

## Single Source of Truth

**Primary**: `.claude-plugin/marketplace.json`
```json
{
  "metadata": {
    "version": "1.5.0"  // ← SSOT
  },
  "plugins": [
    {
      "version": "1.5.0"  // ← Must match metadata.version
    }
  ]
}

All other files reference this version.

Version Reference Map

File	Location	Format	Update Frequency
`marketplace.json`	`metadata.version`	`"1.5.0"`	Every release
`marketplace.json`	`plugins[0].version`	`"1.5.0"`	Every release
`README.md`	Line ~5	`v1.5.0`	Every release
`README.md`	Line ~8 (badge)	`1.5.0`	Every release
`README.md`	Line ~434 (roadmap)	`v1.5.0`	Every release
`README.md`	Line ~505 (footer)	`1.5.0`	Every release
`DEVELOPMENT-README.md`	Bottom	`(v1.5.0)`	Every release
Git tag	Tag name	`v1.5.0`	Every release
GitHub release	Release version	`v1.5.0`	Every release

Pre-Release Checklist

Use this checklist before every release:

Determine semantic version bump (patch/minor/major)
Update marketplace.json (both locations)
Update README.md (4 locations)
Update DEVELOPMENT-README.md (1 location)
Run version consistency audit
Commit version bump separately
Verify all references match

Command:

# Audit script (run before commit)
NEW_VERSION="1.6.0"  # Set your target version

echo "Checking marketplace.json..."
jq -r '.metadata.version' .claude-plugin/marketplace.json | grep "$NEW_VERSION"
jq -r '.plugins[0].version' .claude-plugin/marketplace.json | grep "$NEW_VERSION"

echo "Checking README.md..."
grep "Published v$NEW_VERSION" README.md
grep "version-$NEW_VERSION" README.md
grep "^- v$NEW_VERSION" README.md
grep "^\*\*Version\*\*: $NEW_VERSION" README.md

echo "Checking DEVELOPMENT-README.md..."
grep "(v$NEW_VERSION)" .agent/DEVELOPMENT-README.md

echo "✅ All version references consistent!"

Post-Release Checklist

Create Git tag: git tag -a v1.6.0 -m "Version 1.6.0: Description"
Push tag: git push origin v1.6.0
Create GitHub release with notes
Verify badge renders correctly
Update plugin marketplace listing (if applicable)

Semantic Versioning Guide

Patch (1.5.0 → 1.5.1):

Bug fixes only
No new features
No breaking changes
Example: Fix typo in template

Minor (1.5.0 → 1.6.0):

New features
Backward compatible
No breaking changes
Example: Add new slash command

Major (1.5.0 → 2.0.0):

Breaking changes
May require user action
Changed APIs or workflows
Example: Rename command, change file structure

Troubleshooting

Version Mismatch Detected

Symptoms: Grep shows different versions across files

Solution:

Identify which files are out of sync
Determine correct version (from marketplace.json)
Update all mismatched files
Re-run audit script
Commit fix separately

Badge Not Rendering

Symptoms: Version badge shows old version or 404

Solution:

Check README.md badge URL format
Verify version number has no typos
Shield.io cache may need 5-10 minutes
Force refresh with ?v=timestamp param

Git Tag Already Exists

Symptoms: tag 'v1.6.0' already exists

Solution:

# Delete local tag
git tag -d v1.6.0

# Delete remote tag (if pushed)
git push origin :refs/tags/v1.6.0

# Recreate tag
git tag -a v1.6.0 -m "Version 1.6.0: Description"
git push origin v1.6.0

Future Improvements

Potential Automation

Pre-commit hook to verify version consistency
Script to bump all versions at once
GitHub Action to validate PRs
Bot to create release notes from task docs

For now: Manual checklist is sufficient for plugin development pace.

This SOP prevents version drift and ensures professional release quality.


---

### Step 5: Update Release Workflow SOP

**Modify**: `.agent/sops/development/plugin-release-workflow.md`

Add reference to new version management SOP at the beginning:

```markdown
## Prerequisites

**Before starting any release**:
1. Read [Version Management SOP](./version-management.md)
2. Complete version sync checklist
3. Verify no version mismatches exist

Step 6: Test the Process

Simulate a release:

Create test branch
Bump version to 1.5.1 (simulated patch)
Run audit script
Verify checklist catches all locations
Roll back changes

Success criteria:

Audit script detects all 7 version locations
Checklist is easy to follow
No manual hunting required

Implementation Order

✅ Create this task doc (TASK-04)
🔄 Fix README.md → v1.5.0
🔄 Create missing GitHub releases (v1.3.0, v1.4.0, v1.5.0)
🔄 Create version management SOP
🔄 Update release workflow SOP
🔄 Test the new process
🔄 Archive TASK-04

Success Criteria

Immediate

README.md shows v1.5.0 everywhere
GitHub releases exist for v1.3.0, v1.4.0, v1.5.0
Version management SOP created
Release workflow SOP updated

Long-term

Future releases have no version drift
New contributors follow checklist
Zero version-related user confusion
Professional release quality maintained

Risks & Mitigations

Risk	Impact	Mitigation
Forget to update location	Medium	Audit script catches it
Badge cache issues	Low	Wait 10 min or force refresh
Manual process errors	Medium	Checklist + audit script
Future files added	Low	Update SOP + map when detected

Documentation Impact

Files created:

.agent/tasks/TASK-04-version-sync-release-process.md (this file)
.agent/sops/development/version-management.md (new SOP)

Files modified:

README.md (version updates)
.agent/sops/development/plugin-release-workflow.md (checklist addition)

Timeline

Day 1: Fix current version, create GitHub releases
Day 1: Create version management SOP
Day 1: Test process
Day 1: Archive task

Estimated Time: 2-3 hours

Notes

This issue surfaced because v1.5.0 was released without updating README.md
Root cause: No systematic checklist in release workflow
Prevention: Pre-release version sync becomes mandatory step
Future: Consider automating with pre-commit hooks

Next Steps: Execute implementation plan, starting with README.md fix.

TASK-04: Version Sync Fix & Release Process Improvement

File contents

TASK-04: Version Sync Fix & Release Process Improvement

Problem Statement

Current Issue

Impact

Goals

Primary

Secondary

Technical Analysis

Files with Version References

Version Reference Locations

Implementation Plan

Step 1: Fix Current Version (README.md)

Step 2: Create Missing GitHub Releases

Version Reference Map

Pre-Release Checklist

Post-Release Checklist

Semantic Versioning Guide

Troubleshooting

Version Mismatch Detected

Badge Not Rendering

Git Tag Already Exists

Future Improvements

Potential Automation

Step 6: Test the Process

Implementation Order

Success Criteria

Immediate

Long-term

Risks & Mitigations

Documentation Impact

Timeline

Notes

Frequently asked questions

TASK-04: Version Sync Fix & Release Process Improvement

File contents

TASK-04: Version Sync Fix & Release Process Improvement

Problem Statement

Current Issue

Impact

Goals

Primary

Secondary

Technical Analysis

Files with Version References

Version Reference Locations

Implementation Plan

Step 1: Fix Current Version (README.md)

Step 2: Create Missing GitHub Releases

Version Reference Map

Pre-Release Checklist

Post-Release Checklist

Semantic Versioning Guide

Troubleshooting

Version Mismatch Detected

Badge Not Rendering

Git Tag Already Exists

Future Improvements

Potential Automation

Step 6: Test the Process

Implementation Order

Success Criteria

Immediate

Long-term

Risks & Mitigations

Documentation Impact

Timeline

Notes

Related skills

Frequently asked questions

How do I install the TASK-04: Version Sync Fix & Release Process Improvement skill?

What does the TASK-04: Version Sync Fix & Release Process Improvement skill do?

Is TASK-04: Version Sync Fix & Release Process Improvement safe to use?

Which AI agents work with TASK-04: Version Sync Fix & Release Process Improvement?

Is TASK-04: Version Sync Fix & Release Process Improvement free to use?

Who published TASK-04: Version Sync Fix & Release Process Improvement?