npm-release

name: npm-release version: 1.1.0 description: Use when ready to publish a new version of cc-devflow npm package to npm registry, including version sync, changelog finalization, git tag creation, and publish verification. reads: - PLAYBOOK.md - CHANGELOG.md - references/git-commit-guidelines.md - references/checklist-contract.md

NPM Release Workflow

Read First

1. PLAYBOOK.md
2. CHANGELOG.md
3. references/git-commit-guidelines.md
4. references/checklist-contract.md

[PROTOCOL]: 发布前先确认 git 干净、版本结论正确、CHANGELOG 已落地、npm 身份可用，然后再 commit/tag/push/publish

Release commits follow references/git-commit-guidelines.md; tags keep the release note format in this skill.

Checklist Contract

Follow references/checklist-contract.md before each pause point. The checklist is the local do-confirm/read-do contract for this skill; skip only with an explicit blocker or route.

Overview

Standardized release process for cc-devflow npm package ensuring consistent versioning, changelog maintenance, and safe publishing.

Core Principle: Atomic release - all version markers (package.json, CHANGELOG.md, git tag) must stay in sync.

npm-release 是内部维护 skill，不属于对外公开分发的五步 workflow。

When to Use

Use this skill when:

• ✅ Ready to release a new version of cc-devflow
• ✅ All changes committed and pushed
• ✅ Already in the user-confirmed release worktree and target branch
• ✅ Need to publish to npm registry
• ✅ npm auth is available for the target registry

Don't use when:

• ❌ Working directory has uncommitted changes
• ❌ Current worktree or branch is not the user-confirmed release target
• ❌ Pre-release/beta versions (needs adaptation)

Release Types

Follow Semantic Versioning:

Complete Workflow

Phase 1: Pre-Release Checks

Release skills must never auto-switch branches. If the current worktree is not already the user-confirmed release target, stop and ask for the correct release worktree/branch or create a separate release worktree without changing the main checkout.

# 1. Verify git status
git status --short

# 2. Capture current branch as the release target
release_target_branch="$(git branch --show-current)"
test -n "$release_target_branch"

# 3. Check current version
cat package.json | grep version
# e.g., "version": "2.4.3"

# 4. Review recent changes
git log --oneline -10

STOP if:

• Current branch is not the user-confirmed release target
• Uncommitted changes exist
• Unpushed commits exist
• npm whoami fails for the publish registry

Phase 2: Version Updates

Step 1: Update CHANGELOG.md

Add new version section at the top (after ---):

## [X.Y.Z] - YYYY-MM-DD

### 🎯 Release Title

Brief description of main changes.

#### Changed / Added / Fixed
- Bullet point 1
- Bullet point 2

#### Benefits
- ✅ Benefit 1
- ✅ Benefit 2

Step 2: Update package.json

# Manually edit or use npm version
npm version patch --no-git-tag-version  # For patch release
npm version minor --no-git-tag-version  # For minor release
npm version major --no-git-tag-version  # For major release

Or edit directly:

{
  "version": "X.Y.Z"
}

Phase 3: Git Operations

Step 1: Create Release Commit

git add CHANGELOG.md package.json

git commit -m "$(cat <<'EOF'
chore(release): bump version to X.Y.Z

问题:
- 公开包版本、CHANGELOG 和发布标签需要落到同一个可追溯节点。

变更:
- 更新 package version 和 CHANGELOG 到 X.Y.Z。
- 为 npm publish 准备 release commit。

原因:
- release commit 把版本标记和说明绑定，避免 tag 指向不可解释的历史。

验证:
- npm run verify:publish
- npm pack --dry-run

风险:
- 中：版本、tag、registry 三者必须保持一致；失败时按本 skill 的恢复流程处理。
EOF
)"

Step 2: Create Annotated Tag

git tag -a vX.Y.Z -m "$(cat <<'EOF'
Release vX.Y.Z - [Brief title]

🎯 Main changes:
- Change 1
- Change 2

Benefits:
✅ Benefit 1
✅ Benefit 2

Full changelog: https://github.com/Dimon94/cc-devflow/blob/main/CHANGELOG.md
EOF
)"

Step 3: Verify

# Check commit
git log --oneline -1

# Check tag
git tag -l "v2.4.*" | tail -3

# Verify tag annotation
git show vX.Y.Z

Phase 4: Publish

Step 1: Push to GitHub

# Push current release branch without switching worktrees
git push origin "HEAD:${release_target_branch}"

# Push tags
git push origin vX.Y.Z
# Or push all tags: git push origin --tags

Step 2: Create GitHub Release (Optional)

Via GitHub CLI:

gh release create vX.Y.Z \
  --title "vX.Y.Z - [Title]" \
  --notes-file <(sed -n '/## \[X.Y.Z\]/,/## \[/p' CHANGELOG.md | head -n -1)

Or manually at: https://github.com/Dimon94/cc-devflow/releases/new

Step 3: Publish to npm

# Test publish first (dry-run)
npm publish --dry-run

# Actual publish
npm publish

# Verify publication
npm view cc-devflow version

Quick Reference

Bundled Resources

• PLAYBOOK.md
• CHANGELOG.md

Exit Criteria

• package.json, package-lock.json, CHANGELOG.md, git tag version all match
• Release commit exists and points to the final changelog
• Annotated tag exists for the exact release commit
• GitHub push is complete
• npm publish either succeeded or failed with a captured reason

Common Mistakes

❌ Mistake 1: Forgetting to Update CHANGELOG.md

Problem: Version bumped but no changelog entry

Fix: Always update CHANGELOG.md BEFORE committing

❌ Mistake 2: Inconsistent Version Numbers

Problem: package.json shows 2.4.4 but CHANGELOG.md shows 2.4.3

Fix: Double-check all version numbers match before committing

❌ Mistake 3: Pushing Tag Before Commit

Problem: Tag points to wrong commit

Fix: Always commit first, then tag, then push both together

❌ Mistake 4: Not Testing npm publish

Problem: Published package is broken

Fix: Run npm publish --dry-run first to catch issues

❌ Mistake 5: Network Timeout During Push

Problem: Failed to connect to github.com port 443

Fix:

# Option 1: Retry after network stabilizes
git push origin "HEAD:${release_target_branch}"
git push origin vX.Y.Z

# Option 2: Switch to SSH (if HTTPS blocked)
git remote set-url origin git@github.com:Dimon94/cc-devflow.git
git push origin "HEAD:${release_target_branch}"

Network Troubleshooting

If git push fails with timeout:

1. Check network connectivity:

   curl -I https://github.com 2>&1 | head -5
   

2. Try SSH instead of HTTPS:

   git remote -v  # Check current remote URL
   git remote set-url origin git@github.com:Dimon94/cc-devflow.git
   

3. If SSH fails (publickey error):

   • Check SSH key: ssh -T git@github.com
   • Add SSH key to GitHub: https://github.com/settings/keys
   • Or stay with HTTPS and retry later

4. Commits and tags are safe locally:

   • They won't be lost
   • Push when network is available

Post-Release Verification

After successful release:

# 1. Verify GitHub tag
open https://github.com/Dimon94/cc-devflow/tags

# 2. Verify npm package
npm view cc-devflow version
npm view cc-devflow time

# 3. Test installation
npm install -g cc-devflow@latest
cc-devflow --version  # Should show new version

Rollback (If Needed)

If published version has critical bugs:

# 1. Unpublish from npm (within 72 hours)
npm unpublish cc-devflow@X.Y.Z

# 2. Delete git tag locally and remotely
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

# 3. Revert commit
git revert HEAD

# 4. Fix bug and re-release with new patch version

Note: npm unpublish is only available within 72 hours of publication. After that, publish a new patch version instead.

Real-World Impact

Following this workflow ensures:

• ✅ Consistency: All version markers stay in sync
• ✅ Traceability: Clear changelog and git history
• ✅ Safety: Dry-run catches issues before publishing
• ✅ Recoverability: Can rollback if needed
• ✅ Automation-ready: Scriptable workflow for future CI/CD

[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md