npm-release by Dimon94

---
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](https://semver.org/):

| Type | Version Change | When |
|------|---------------|------|
| **Patch** | 2.4.3 → 2.4.4 | Bug fixes, minor improvements |
| **Minor** | 2.4.4 → 2.5.0 | New features, backward compatible |
| **Major** | 2.5.0 → 3.0.0 | Breaking changes |

## 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.

```bash
# 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 `---`):

```markdown
## [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**

```bash
# 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:
```json
{
  "version": "X.Y.Z"
}
```

### Phase 3: Git Operations

**Step 1: Create Release Commit**

```bash
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**

```bash
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**

```bash
# 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**

```bash
# 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:
```bash
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**

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

# Actual publish
npm publish

# Verify publication
npm view cc-devflow version
```

## Quick Reference

| Step | Command | Purpose |
|------|---------|---------|
| Check status | `git status` | Verify clean state |
| Check version | `grep version package.json` | Current version |
| Bump version | Edit package.json | Update version number |
| Update changelog | Edit CHANGELOG.md | Document changes |
| Create commit | `git commit -m "chore(release): ..."` | Commit version bump |
| Create tag | `git tag -a vX.Y.Z -m "..."` | Tag release |
| Push commits | `git push origin "HEAD:${release_target_branch}"` | Push current release branch |
| Push tags | `git push origin vX.Y.Z` | Push tag to GitHub |
| Publish npm | `npm publish` | Publish to registry |

## 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**:
```bash
# 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 [email protected]:Dimon94/cc-devflow.git
git push origin "HEAD:${release_target_branch}"
```

## Network Troubleshooting

If `git push` fails with timeout:

1. **Check network connectivity**:
   ```bash
   curl -I https://github.com 2>&1 | head -5
   ```

2. **Try SSH instead of HTTPS**:
   ```bash
   git remote -v  # Check current remote URL
   git remote set-url origin [email protected]:Dimon94/cc-devflow.git
   ```

3. **If SSH fails (publickey error)**:
   - Check SSH key: `ssh -T [email protected]`
   - 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:

```bash
# 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:

```bash
# 1. Unpublish from npm (within 72 hours)
npm unpublish [email protected]

# 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